03 CDC avec Postgres managé

Document d’accompagnement du formateur pour la leçon participant 03 CDC avec Postgres managé.

Durée

Environ 20 minutes. Une instance Postgres managée accepte les connexions environ une minute après clickhousectl cloud postgres create : les participants peuvent donc la provisionner et renseigner leur environnement pendant vos explications sur la CDC. Il faut souvent quelques minutes au ClickPipe pour prendre son instantané et commencer la diffusion, mais la validation a observé un provisionnement dépassant 10 minutes. Lancez-le tôt et suivez les contrôles d’escalade du guide de dépannage participant au lieu d’annoncer une durée d’achèvement fixe.

Trame d’animation

• Chaque participant crée sa PROPRE instance Postgres managée par ClickHouse dans son organisation d’essai : aucun partage d’instance n’est prévu dans le parcours principal. Une personne n’a besoin que d’un emplacement de réplication, et chaque instance managée est livrée avec wal_level=logical et 10 emplacements par défaut ; la vérification « augmenter max_replication_slots » ne s’applique donc tout simplement pas.
• Leur Postgres et leur ClickPipe se trouvent dans la même organisation et sont tous deux créés avec clickhousectl ; aucune variante passant par un assistant de la console n’est requise.
• Présentez la CDC dans les grandes lignes (lecture du journal d’écriture anticipée) et expliquez pourquoi les tables de destination comportent des colonnes techniques _peerdb_* ; la vue matérialisée filtre _peerdb_is_deleted = 0.
• Soulignez que le journal du générateur constitue le signal de disponibilité : l’application sert de sonde. Les participants n’interrogent jamais une API d’état (les appels bêta postgres get/list peuvent renvoyer un résultat vide ou FORBIDDEN, même lorsque l’instance fonctionne correctement).

Problèmes courants

• Mot de passe à usage unique perdu. Il n’est affiché qu’une fois par create. Réinitialisez-le avec clickhousectl cloud postgres reset-password <service-id>, puis mettez à jour .env.workshop et redémarrez le générateur.
• Le journal du générateur signale d’abord des erreurs de connexion. L’instance est encore en cours de provisionnement ; le conteneur s’arrête puis redémarre automatiquement, et récupère donc de lui-même en une minute environ. N’enquêtez que si les erreurs persistent au-delà de quelques minutes.
• Le ClickPipe ne parvient pas à se connecter. La cause est généralement un hôte ou un mot de passe incorrect, ou l’absence de la valeur require pour PGSSLMODE (Postgres managé impose TLS).
• Régions différentes. Une connexion Postgres vers ClickHouse entre régions fonctionne, mais augmente la latence ; invitez les participants à créer Postgres dans la même région que leur service ClickHouse.
• Le générateur de données n’a pas démarré : rien ne semble donc bouger. Vérifiez que pg-trip-writer est actif et que son journal affiche inserted N trips.
• La création du pipeline échoue avec BAD_REQUEST: table realtime_trips exists and is not empty. Cela ne se produit que lors d’une nouvelle exécution ou réinitialisation, jamais pour une première exécution : la suppression d’un ClickPipe supprime l’emplacement de réplication source, mais conserve sa table de destination, et la CLI refuse de réutiliser une table non vide. Suivez la procédure de sauvegarde horodatée du guide de dépannage participant, puis recréez le pipeline ; ne supprimez pas les données des participants par défaut.
• Postgres managé n’est pas disponible dans l’organisation (la disponibilité de la bêta varie) : c’est le seul cas qui doit basculer vers le pool partagé du formateur ; consultez la section ci-dessous.

Solution de repli : Postgres cloud géré par le formateur

Si l’organisation d’un participant ne peut pas créer de Postgres managé, remettez-lui une fiche de connexion à une instance cloud managée. Le pool cloud (ainsi que les contraintes d’emplacements et d’expéditeurs qui apparaissent à partir de 30 personnes) est provisionné et documenté dans infra/README.md. Dans le parcours partagé, la table et la publication sont créées à l’avance ; le journal du générateur affiche donc publication ... already exists au lieu de les créer. C’est normal, pas une erreur.

Procédures de réinitialisation

• Supprimez et recréez le ClickPipe avec les commandes du module participant 03.
• Redémarrez le générateur de données : docker compose --profile cdc --env-file .env.workshop -f docker-compose.workshop.yml up -d pg-trip-writer (désactivez-le avec --scale pg-trip-writer=0).
• Réinitialisez un mot de passe Postgres perdu avec clickhousectl cloud postgres reset-password.
• Après l’événement, les participants suppriment leur ClickPipe (module 09) ; chacun reste libre de supprimer son Postgres managé depuis la console ou avec clickhousectl cloud postgres delete <service-id>.