03 CDC com Postgres gerenciado

Material do facilitador correspondente à lição 03 CDC com Postgres gerenciado do participante.

Cronograma

Uma instância gerenciada do Postgres aceita conexões cerca de um minuto após clickhousectl cloud postgres create. Assim, os participantes podem provisioná-la e preencher as variáveis de ambiente enquanto você explica o CDC. O ClickPipe costuma levar alguns minutos para criar o snapshot e iniciar o streaming, mas, na validação, o provisionamento levou mais de 10 minutos. Inicie-o cedo e use as verificações de escalonamento da seção de solução de problemas do participante, em vez de prometer um tempo fixo de conclusão.

Roteiro de apresentação

• Cada participante cria seu PRÓPRIO Postgres gerenciado pelo ClickHouse na respectiva organização de avaliação — não há uma instância compartilhada no percurso principal. Cada participante precisa de exatamente um slot de replicação, e toda instância gerenciada vem com wal_level=logical e 10 slots por padrão. Portanto, a verificação de “aumentar max_replication_slots” simplesmente não se aplica a eles.
• O Postgres e o ClickPipe ficam na mesma organização e ambos são criados com clickhousectl; não é necessário seguir um caminho alternativo pelo assistente do console.
• Explique o CDC em termos gerais (ele lê o log de gravação antecipada) e por que as tabelas de destino contêm colunas de controle _peerdb_*; a MV filtra _peerdb_is_deleted = 0.
• Destaque que o próprio log do gerador é o sinal de prontidão — o aplicativo funciona como sonda; os participantes nunca consultam repetidamente uma API de status (as chamadas beta postgres get/list podem retornar vazio ou FORBIDDEN até mesmo em uma instância íntegra).

Falhas comuns

• A senha de uso único foi perdida. Ela é exibida apenas uma vez por create. Redefina-a: clickhousectl cloud postgres reset-password <service-id>, atualize .env.workshop e reinicie o gerador.
• Os logs do gerador mostram erros de conexão no início. A instância ainda está sendo provisionada; o contêiner encerra e reinicia automaticamente, portanto se recupera sozinho em cerca de um minuto. Investigue apenas se os erros continuarem depois de alguns minutos.
• O ClickPipe não consegue se conectar. Em geral, o host ou a senha está incorreto, ou PGSSLMODE não foi definido como require (o Postgres gerenciado exige TLS).
• Regiões diferentes. A conexão entre Postgres e ClickHouse em regiões distintas funciona, mas aumenta a latência; oriente os participantes a criar o Postgres na mesma região do serviço ClickHouse.
• O gerador de dados não foi iniciado, portanto nada parece se mover — confira se pg-trip-writer está em execução e se o log mostra inserted N trips.
• A criação do pipe falha com BAD_REQUEST: table realtime_trips exists and is not empty. Isso ocorre apenas em uma nova execução/redefinição, não com um novo participante: a exclusão de um ClickPipe remove o slot de replicação na origem, mas deixa a tabela de destino, e a CLI se recusa a reutilizar uma tabela que não esteja vazia. Use o procedimento de backup com carimbo de data e hora no guia de solução de problemas do participante e recrie o pipe; por padrão, não descarte os dados do participante.
• O Postgres gerenciado não está disponível na organização (a disponibilidade da versão beta varia) — este é o único caso que usa o conjunto compartilhado do instrutor como contingência; veja abaixo.

Contingência: Postgres na nuvem gerenciado pelo instrutor

Se a organização de um participante não puder criar um Postgres gerenciado, entregue-lhe uma ficha com uma conexão gerenciada na nuvem. O conjunto na nuvem (e as ressalvas sobre slots/remetentes que surgem em escala de 30 ou mais participantes) está provisionado e documentado em infra/README.md. No percurso compartilhado, a tabela e a publicação são pré-criadas, por isso o log do gerador mostra publication ... already exists em vez de criar uma nova. Esse comportamento é esperado, não um erro.

Etapas de redefinição

• Exclua e recrie o ClickPipe com os comandos do módulo 03 do participante.
• Reinicie o gerador de dados: docker compose --profile cdc --env-file .env.workshop -f docker-compose.workshop.yml up -d pg-trip-writer (desative-o com --scale pg-trip-writer=0).
• Redefina uma senha perdida do Postgres com clickhousectl cloud postgres reset-password.
• Após o evento, os participantes excluem seu ClickPipe (módulo 09); cada participante pode excluir seu Postgres gerenciado pelo console ou com clickhousectl cloud postgres delete <service-id>.