03 CDC con Postgres administrado

Material del facilitador correspondiente a la lección 03 CDC con Postgres administrado del participante.

Tiempos

Una instancia administrada de Postgres acepta conexiones aproximadamente un minuto después de clickhousectl cloud postgres create, por lo que los participantes pueden aprovisionarla y rellenar sus variables de entorno mientras explicas CDC. ClickPipe suele tardar unos minutos en crear el snapshot e iniciar el streaming, pero durante la validación el aprovisionamiento superó los 10 minutos. Inícialo pronto y usa las comprobaciones de escalado de la guía de solución de problemas del participante, en lugar de prometer un tiempo fijo de finalización.

Guion de presentación

• Cada participante crea su PROPIO Postgres administrado por ClickHouse en su organización de prueba; no hay una instancia compartida en el recorrido principal. Cada participante necesita exactamente una ranura de replicación, y todas las instancias administradas incluyen wal_level=logical y 10 ranuras de forma predeterminada, por lo que la comprobación «aumentar max_replication_slots» sencillamente no les corresponde.
• Su Postgres y ClickPipe están en la misma organización y se crean con clickhousectl; no hace falta seguir una ruta alternativa por el asistente de la consola.
• Explica CDC a grandes rasgos (lee el registro de escritura anticipada) y por qué las tablas de destino contienen columnas de control _peerdb_*; la MV filtra _peerdb_is_deleted = 0.
• Destaca que el propio registro del generador es la señal de disponibilidad: la aplicación actúa como sonda; nunca se consulta repetidamente una API de estado (las llamadas beta postgres get/list pueden devolver vacío o FORBIDDEN incluso con una instancia en buen estado).

Fallos habituales

• Se perdió la contraseña de un solo uso. create solo la muestra una vez. Restablécela: clickhousectl cloud postgres reset-password <service-id>, actualiza .env.workshop y reinicia el generador.
• Los registros del generador muestran errores de conexión al principio. La instancia aún se está aprovisionando; el contenedor se cierra y reinicia automáticamente, por lo que se recupera solo en un minuto aproximadamente. Investiga únicamente si los errores persisten durante varios minutos.
• ClickPipe no puede conectarse. Suele deberse a un host o una contraseña incorrectos, o a que PGSSLMODE no está definido como require (Postgres administrado exige TLS).
• Regiones distintas. La conexión entre Postgres y ClickHouse en regiones diferentes funciona, pero añade latencia; indica a los participantes que creen Postgres en la misma región que su servicio ClickHouse.
• El generador de datos no se ha iniciado, por lo que parece que nada se mueve: comprueba que pg-trip-writer esté activo y que su registro muestre inserted N trips.
• La creación del pipe falla con BAD_REQUEST: table realtime_trips exists and is not empty. Solo sucede durante una repetición/restablecimiento, no con un participante nuevo: eliminar un ClickPipe borra la ranura de replicación de origen, pero deja su tabla de destino, y la CLI se niega a reutilizar una tabla que no esté vacía. Usa el procedimiento de copia de seguridad con marca de tiempo de la guía de solución de problemas del participante y vuelve a crear el pipe; no descartes los datos del participante de forma predeterminada.
• Postgres administrado no está disponible en la organización (la disponibilidad de la versión beta varía): este es el único caso que recurre al grupo compartido del instructor; consulta la sección siguiente.

Alternativa: Postgres en la nube administrado por el instructor

Si la organización de un participante no puede crear Postgres administrado, entrégale una ficha con una conexión administrada en la nube. El grupo en la nube (y las consideraciones sobre ranuras y emisores que aparecen a una escala de 30 participantes o más) está aprovisionado y documentado en infra/README.md. En el recorrido compartido, la tabla y la publicación ya están creadas, por lo que el registro del generador muestra publication ... already exists en lugar de crear una; es lo esperado, no un error.

Pasos de restablecimiento

• Elimina y vuelve a crear ClickPipe con los comandos del módulo 03 del participante.
• Reinicia el generador de datos: docker compose --profile cdc --env-file .env.workshop -f docker-compose.workshop.yml up -d pg-trip-writer (desactívalo con --scale pg-trip-writer=0).
• Restablece una contraseña perdida de Postgres con clickhousectl cloud postgres reset-password.
• Tras el evento, los participantes eliminan su ClickPipe (módulo 09); cada participante puede eliminar su Postgres administrado desde la consola o con clickhousectl cloud postgres delete <service-id>.