03 托管 Postgres CDC

学员课程 03 托管 Postgres CDC 的讲师配套材料。

时间安排

约 20 分钟。托管 Postgres 实例在 clickhousectl cloud postgres create 之后大约一分钟内 就能接受连接，所以参与者可以边开通实例、填环境变量，你边讲 CDC。ClickPipe 通常需要几分钟 才能完成快照并开始流式同步，但验证过程中观察到开通耗时超过 10 分钟。尽早启动它，并使用 学员故障排查中的升级检查项，而不要承诺一个固定的完成时间。

讲解要点

• 每位参与者在自己的试用组织里创建自己的 ClickHouse 托管 Postgres， 主路径上没有共享实例。每位参与者只需要恰好一个复制槽，而每个托管实例默认都带 wal_level=logical 和 10 个槽，所以"提高 max_replication_slots"这道关卡对他们根本不适用。
• 他们的 Postgres 和 ClickPipe 位于同一个组织，并且都用 clickhousectl 创建； 不需要走控制台向导的分支路径。
• 从高层解释 CDC（读取预写日志），以及为什么目标表带有 _peerdb_* 记账列； materialized view 会过滤 _peerdb_is_deleted = 0。
• 指出生成器自己的日志就是就绪信号，应用本身就是探针；他们从不轮询状态 API （beta 版的 postgres get/list 调用即使在实例健康时也可能返回空或 FORBIDDEN）。

常见故障

• 丢了一次性密码。 它只在 create 时显示一次。重置方式： clickhousectl cloud postgres reset-password <service-id>，然后更新 .env.workshop 并重启生成器。
• 生成器一开始报连接错误。 实例还在开通中；容器会退出并自动重启，所以它会在大约一分钟内 自愈。只有当错误持续几分钟以上时才需要排查。
• ClickPipe 连不上。 通常是主机或密码填错，或者 PGSSLMODE 没有设为 require（托管 Postgres 强制要求 TLS）。
• 区域不匹配。 跨区域的 Postgres 到 ClickHouse 也能工作，但会增加延迟；引导参与者 把 Postgres 创建在与其 ClickHouse 服务相同的区域。
• 数据生成器没有启动，因此看起来什么都没动，检查 pg-trip-writer 是否在运行， 以及它的日志是否显示 inserted N trips。
• 创建 pipe 失败并报 BAD_REQUEST: table realtime_trips exists and is not empty。 这只会出现在重跑/重置时，而不是全新的参与者身上：删除 ClickPipe 会丢掉源端的复制槽， 但会留下它的目标表，而 CLI 拒绝复用一个非空的表。使用学员故障排查指南中带时间戳的备份流程， 然后重新创建 pipe；默认情况下不要丢弃参与者的数据。
• 组织中没有托管 Postgres（beta 版的可用性因组织而异），这是唯一需要回退到 共享讲师资源池的情况；见下文。

回退方案：讲师托管的云端 Postgres

如果某位参与者的组织无法创建托管 Postgres，就给他们一份托管云连接信息条。 这个云资源池（以及在 30 人以上规模下随之而来的复制槽/发送端注意事项） 在 infra/README.md 中开通并有文档说明。在共享路径上，表和 publication 是预先创建好的， 所以生成器日志会显示 publication ... already exists 而不是创建一个新的，这是预期行为，不是错误。

重置步骤

• 用学员模块 03 中的命令删除并重新创建 ClickPipe。
• 重启数据生成器： docker compose --profile cdc --env-file .env.workshop -f docker-compose.workshop.yml up -d pg-trip-writer （用 --scale pg-trip-writer=0 关闭它）。
• 用 clickhousectl cloud postgres reset-password 重置丢失的 Postgres 密码。
• 活动结束后，参与者删除自己的 ClickPipe（模块 09）；参与者的托管 Postgres 归他们自己所有， 可从控制台删除，也可以用 clickhousectl cloud postgres delete <service-id> 删除。