03 マネージド Postgres CDC

学習者向けレッスン 03 マネージド Postgres CDC に対応するファシリテーター用の手引きです。

タイミング

約20分。マネージド Postgres インスタンスは clickhousectl cloud postgres create から約1分で 接続を受け付けるようになるため、あなたが CDC を説明している間に参加者はプロビジョニングして環境変数を 埋められます。ClickPipe はスナップショットを取得してストリーミングを開始するまでに数分かかることが多く、 検証ではプロビジョニングが10分を超えるケースも観測されました。早めに開始し、完了時間を約束するのではなく、 学習者向けトラブルシューティングのエスカレーション確認手順を使ってください。

トークトラック

• 参加者はそれぞれ自分のトライアル組織で、ClickHouse にマネージドされた 自分専用の Postgres を作成する。 主経路に共有インスタンスは存在しない。参加者1人が必要とするレプリケーションスロットはちょうど1つで、 すべてのマネージドインスタンスはデフォルトで wal_level=logical とスロット10個を備えているため、 「max_replication_slots を上げる」という関門はそもそも当てはまらない。
• 参加者の Postgres と ClickPipe は同じ組織にあり、どちらも clickhousectl で作成される。 コンソールのウィザードに分岐する必要はない。
• CDC を高レベルで説明し（先行書き込みログを読む）、宛先テーブルに _peerdb_* の管理用カラムが付く理由を 説明する。materialized view は _peerdb_is_deleted = 0 でフィルタする。
• 準備完了のシグナルはジェネレーター自身のログである点を指摘する。つまりアプリがプローブであり、 ステータス API をポーリングすることは一切ない（ベータの postgres get/list 呼び出しは、 正常なインスタンスでも空や FORBIDDEN を返すことがある）。

よくある失敗

• ワンタイムパスワードを紛失した。 create が1度だけ表示するものである。リセットするには: clickhousectl cloud postgres reset-password <service-id> を実行し、.env.workshop を更新して ジェネレーターを再起動する。
• 最初はジェネレーターのログに接続エラーが出る。 インスタンスがまだプロビジョニング中である。 コンテナは終了して自動的に再起動するため、約1分で自己修復する。エラーが数分続く場合のみ調査する。
• ClickPipe が接続できない。 通常はホストかパスワードの誤り、または PGSSLMODE が require に設定されていない（マネージド Postgres は TLS を必須とする）。
• リージョンの不一致。 リージョンをまたぐ Postgres から ClickHouse への接続は動作するがレイテンシーが増える。 参加者には ClickHouse サービスと同じリージョンに Postgres を作成するよう誘導する。
• データジェネレーターが起動していない ため何も動いていないように見える。pg-trip-writer が 起動しており、そのログに inserted N trips が出ていることを確認する。
• パイプの作成が BAD_REQUEST: table realtime_trips exists and is not empty で失敗する。 新規の参加者ではなく、再実行/リセット の場合にのみ起こる。ClickPipe を削除するとソース側の レプリケーションスロットは消えるが宛先テーブルは残り、CLI は空でないテーブルの再利用を拒否する。 学習者向けトラブルシューティングガイドにあるタイムスタンプ付きバックアップの手順を使ってから パイプを再作成する。デフォルトで参加者のデータを捨ててはいけない。
• 組織でマネージド Postgres が利用できない（ベータの提供状況は環境によって異なる）— これが インストラクターの共有プールにフォールバックする唯一のケース。下記参照。

フォールバック: インストラクター管理のクラウド Postgres

参加者の組織でマネージド Postgres を作成できない場合は、マネージドクラウドの接続情報を渡してください。 クラウドプール（および30名以上の規模でついてくるスロット/送信側の注意点）は infra/README.md でプロビジョニングされ、文書化されています。共有経路ではテーブルと publication があらかじめ作成されているため、ジェネレーターのログには 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）。
• 紛失した Postgres のパスワードは clickhousectl cloud postgres reset-password でリセットする。
• イベント後、参加者は自分の ClickPipe を削除する（モジュール 09）。参加者のマネージド Postgres は 本人のものなので、コンソールまたは clickhousectl cloud postgres delete <service-id> で削除できる。