- 主キー: 最もわかりやすい方法は、テーブルに主キーを定義することです。これにより各行に一意の識別子が与えられ、更新や削除を追跡するうえで重要になります。この場合、REPLICA IDENTITY は
DEFAULT(既定の動作) に設定できます。 - Replica Identity: テーブルに主キーがない場合は、レプリカアイデンティティ を設定できます。レプリカアイデンティティ は
FULLに設定でき、この場合は行全体を使って変更を識別します。あるいは、テーブルに一意な索引がある場合はその索引を使用するように設定し、REPLICA IDENTITY をUSING INDEX index_nameに設定することもできます。 レプリカアイデンティティ を FULL に設定するには、次の SQL コマンドを使用します。
REPLICA IDENTITY FULL を使用すると、変更されていない TOAST カラムもレプリケーションの対象になります。詳しくはこちらをご覧ください。
REPLICA IDENTITY FULL の使用は、パフォーマンスに影響する可能性があるほか、WAL の増加が速くなる場合がある点に注意してください。特に、主キーがなく、更新や削除が頻繁に発生するテーブルでは、変更ごとにより多くのデータをログに記録する必要があるため、その影響が大きくなります。テーブルの主キーやレプリカアイデンティティの設定について不明な点がある場合、または設定の支援が必要な場合は、サポートチームまでお問い合わせください。
また、主キーとレプリカアイデンティティのいずれも定義されていない場合、ClickPipes はそのテーブルの変更をレプリケートできず、レプリケーション処理中にエラーが発生する可能性があります。そのため、ClickPipe を設定する前にテーブルのスキーマを確認し、これらの要件を満たしていることを確認することをお勧めします。
はい。パーティション化テーブルは、PRIMARY KEY または REPLICA IDENTITY が定義されていれば、追加設定なしでサポートされます。PRIMARY KEY と REPLICA IDENTITY は、親テーブルとそのパーティションの両方に設定されている必要があります。詳細については、こちらをご覧ください。
はい。パブリックインターネットに公開されていないデータソースに ClickPipes が接続する方法については、ClickPipes ネットワーキングをご覧ください。
ClickPipes for Postgres は、Postgres の INSERT と UPDATE の両方を、ClickHouse では異なるバージョン (_peerdb_ バージョンカラムを使用) を持つ新しい行として取り込みます。ReplacingMergeTree テーブルエンジンは、順序キー (ORDER BY カラム) に基づいてバックグラウンドで定期的に重複排除を行い、最新の _peerdb_ バージョンを持つ行だけを保持します。
Postgres の DELETE は、削除済みとしてマークされた新しい行 (_peerdb_is_deleted カラムを使用) として伝播されます。重複排除プロセスは非同期のため、一時的に重複が見える場合があります。これに対処するには、クエリレイヤーで重複排除を行う必要があります。
また、デフォルトでは、Postgres は DELETE 操作時に、主キーまたは レプリカアイデンティティ に含まれないカラムの値を送信しない点にも注意してください。DELETE 時に行全体のデータを取得したい場合は、REPLICA IDENTITY を FULL に設定できます。
詳細については、以下を参照してください。
主キーは変更されない識別子として設計されるため、PostgreSQL のデータベース設計において主キーカラムの更新は一般的ではない点にも注意してください。ほとんどのアプリケーションでは、設計上主キーの更新を避けているため、この制限が問題になるケースは通常まれです。
主キー更新の処理を有効にできる実験的な設定もありますが、パフォーマンスへの影響が大きく、十分に検討せずに本番環境で使用することは推奨されません。
PostgreSQL で主キーカラムを更新し、その変更を ClickHouse に正しく反映させる必要がある場合は、具体的な要件や考えられる解決策について相談するため、db-integrations-support@clickhouse.com までサポートチームにご連絡ください。
詳しくは、ClickPipes for Postgres: スキーマ変更の反映サポート ページを参照してください。
料金の詳細については、メインの請求概要ページにある ClickPipes for Postgres CDC (変更データキャプチャ) の料金セクションをご参照ください。
Postgres のレプリケーションスロットのサイズが増え続けていたり、なかなか小さくならなかったりする場合、通常は WAL (Write-Ahead Log) レコードが CDC パイプラインまたはレプリケーション処理で十分な速度で消費 (または「再生」) されていない ことを意味します。以下では、よくある原因とその対処方法を説明します。
-
データベースアクティビティの急増
- 大規模なバッチ更新、大量挿入、または大きなスキーマ変更により、短時間で大量の WAL データが生成されることがあります。
- レプリケーションスロットは、これらの WAL レコードが消費されるまで保持するため、一時的にサイズが急増します。
-
長時間実行されるトランザクション
- トランザクションが開いたままになっていると、Postgres はそのトランザクションの開始以降に生成されたすべての WAL セグメントを保持する必要があり、スロットサイズが大幅に増えることがあります。
- トランザクションが無期限に開いたままにならないよう、
statement_timeoutとidle_in_transaction_session_timeoutを妥当な値に設定してください。このクエリを使うと、異常に長時間実行されているトランザクションを特定できます。
-
メンテナンスまたはユーティリティ処理 (例:
pg_repack)pg_repackのようなツールはテーブル全体を書き換えることがあり、短時間で大量の WAL データを生成します。- これらの処理はトラフィックの少ない時間帯に実行するか、実行中は WAL 使用量を注意深く監視してください。
-
VACUUM と VACUUM ANALYZE
- これらの処理はデータベースの健全性維持に必要ですが、特に大きなテーブルをスキャンする場合は、追加の WAL トラフィックを発生させることがあります。
- autovacuum の調整パラメータを利用するか、手動の VACUUM 処理をピーク外の時間帯に実行することを検討してください。
-
レプリケーション consumer がスロットを継続的に読み取っていない
- CDC パイプライン (例: ClickPipes) または別のレプリケーション consumer が停止、一時停止、またはクラッシュすると、WAL データがスロット内に蓄積されます。
- パイプラインが継続的に稼働していることを確認し、接続や認証の error がないか logs を確認してください。
json および jsonb カラムは、native JSON type との互換性がないため、ClickHouse では String 型としてレプリケートされます。たとえば、次のような理由があります。
- PostgreSQL では、トップレベルに任意の有効な JSON 値 (文字列、数値、配列など) を置けますが、ClickHouse の JSON type はオブジェクトしかサポートしていません。
- ドットを含むキー (例: “app.kubernetes.io/name”) は、ClickHouse の JSON type ではネストされたパスとしても解釈されるため、データ構造が変わってしまう可能性があります。
- sync では、途中でキャンセルされた場合、Postgres の confirmed_flush_lsn は更新されないため、次回の sync は中断されたものと同じ位置から開始され、データの整合性が保たれます。
- normalize では、ReplacingMergeTree における insert 順序によって重複排除が行われます。
snapshot number of tables in parallel を増やすか、大きなテーブルに対して独自の索引付きパーティション化カラムを指定してください。
パブリケーションは ClickPipes に管理させることもできます (追加の権限が必要です) 。また、自分で作成して管理することもできます。ClickPipes 管理のパブリケーションでは、パイプの編集に応じたテーブルの追加・削除が自動的に処理されます。自分で管理する場合は、レプリケーションが必要なテーブルだけを含めるよう、パブリケーションのスコープを慎重に設定してください。不要なテーブルまで含めると、Postgres の WAL デコードが遅くなります。
パブリケーションに含めるテーブルには、必ず主キーまたは REPLICA IDENTITY FULL のいずれかが設定されていることを確認してください。主キーのないテーブルがある状態で、すべてのテーブルを対象とするパブリケーションを作成すると、それらのテーブルでは DELETE や UPDATE が失敗します。
データベース内で主キーのないテーブルを特定するには、次のクエリを使用できます。
-
主キーのないテーブルを ClickPipes から除外する:
主キーのあるテーブルだけを含むようにパブリケーションを作成します。
-
主キーのないテーブルを ClickPipes に含める:
主キーのないテーブルを含める場合は、それらのレプリカアイデンティティを
FULLに変更する必要があります。これにより、UPDATE および DELETE 操作が正しく機能します。
- 最低限:
max_slot_wal_keep_sizeは、少なくとも 2 日分 の WAL データを保持できるように設定します。 - 大規模なデータベース向け (トランザクション量が多い場合) : 1 日あたりの WAL 生成量のピーク時の 2~3 倍 を少なくとも保持します。
- ストレージ容量に制約がある環境向け: レプリケーションの安定性を確保しつつ、ディスク容量の枯渇を避ける ため、控えめに調整します。
PostgreSQL 10以降
PostgreSQL 9.6 以下の場合:
- 上記のクエリを、1日のさまざまな時間帯、特にトランザクション量が多い時間帯に実行します。
- 24時間あたりに生成されるWALの量を計算します。
- 十分な保持期間を確保するため、その値に2倍または3倍を掛けます。
max_slot_wal_keep_sizeを、算出した値 (MB または GB) に設定します。
例
ReceiveMessage は、Postgres のロジカルデコードプロトコルで、レプリケーションストリームからメッセージを読み取る関数です。EOF (End of File) エラーは、レプリケーションストリームの読み取り中に、Postgres サーバーへの connection が予期せず閉じられたことを示します。
これは回復可能で、まったく致命的ではないエラーです。ClickPipes は自動的に再接続を試み、レプリケーションを再開します。
これは、いくつかの理由で発生する可能性があります。
- ネットワークの問題: 一時的なネットワーク障害によって、connection が切断されることがあります。
- Postgres サーバーの再起動: Postgres サーバーが再起動された、またはクラッシュした場合、connection は失われます。
max_slot_wal_keep_size の設定値が小さいことです (たとえば数 GB) 。この値を増やすことを推奨します。max_slot_wal_keep_size の調整については、こちらのセクションを参照してください。レプリケーションスロットの無効化を防ぐには、理想的には少なくとも 200GB に設定してください。
まれに、max_slot_wal_keep_size が設定されていない場合でもこの問題が発生することがあります。これは PostgreSQL の複雑でまれな不具合が原因である可能性がありますが、原因は依然として明らかになっていません。
ClickHouse で OOM が発生する一般的な原因の 1 つは、サービスのサイズが不足していることです。つまり、現在のサービス構成では、インジェスト負荷を効率よく処理するのに十分なリソース (たとえばメモリや CPU) がありません。ClickPipe のデータインジェストに必要な負荷を満たせるよう、サービスをスケールアップすることを強く推奨します。
もう 1 つ確認されている原因は、十分に最適化されていない JOIN を含む下流の materialized view が存在することです。
-
JOINの一般的な最適化手法の 1 つは、右側のテーブルが非常に大きいLEFT JOINがある場合です。この場合は、クエリをRIGHT JOINを使う形に書き換え、大きいテーブルを左側に移してください。これにより、クエリプランナーはよりメモリ効率よく処理できるようになります。 -
JOINの別の最適化方法としては、subqueriesやCTEsを使ってテーブルを明示的に絞り込み、その後それらのサブクエリ同士でJOINを実行する方法があります。これにより、プランナーは、行を効率よく絞り込み、JOINを実行するためのヒントを得られます。
invalid snapshot identifier エラーは、ClickPipes と Postgres データベース間の接続が切断されたときに発生します。これは、ゲートウェイのタイムアウト、データベースの再起動、またはその他の一時的な問題が原因で起こることがあります。
初期ロードの実行中は、Postgres データベースに対してアップグレードや再起動などの影響の大きい操作は行わず、データベースへのネットワーク接続が安定していることを確認することを推奨します。
この問題を解決するには、ClickPipes UI から再同期をトリガーできます。これにより、初期ロードは最初からやり直されます。
Postgres でパブリケーションを削除すると、ClickPipe がソースから変更を取得するにはそのパブリケーションが必要なため、ClickPipe 接続は機能しなくなります。この場合、通常はパブリケーションが存在しなくなったことを示すエラーアラートを受け取ります。
パブリケーションを削除したあとに ClickPipe を復旧するには:
- Postgres で、同じ名前と必要なテーブルを含む新しいパブリケーションを作成します
- ClickPipe の Settings タブで ‘Resync tables’ ボタンをクリックします
ソースのPostgresデータベースからデータが削除されても、ClickHouse に完全な履歴レコードを保持しておく必要があります。ClickPipes で Postgres の DELETE 操作と TRUNCATE 操作を完全に無視できますか?
- ユーザーにソーステーブルを読み取るための十分な権限があるか。
- ClickHouse 側に、行を除外してしまう可能性のある行ポリシーがないか。
Advanced Settings セクションで以下のスイッチを有効にすることで、ClickPipes にフェイルオーバー対応のレプリケーションスロットを作成させることができます。なお、この機能を使用するには Postgres 17 以降が必要です。

ReorderBufferPreserveLastSpilledSnapshot ルーチンから発生していることから、ロジカルデコードがディスクにスピルされたスナップショットを読み取れていない可能性があります。logical_decoding_work_mem をより大きな値に増やしてみることをお勧めします。
CDC (変更データキャプチャ) レプリケーション中に error converting new tuple to map や error parsing logical message のようなエラーが表示される
CREATE_REPLICATION_SLOT クエリが Lock 状態のまま停止していることがあります。これは、Postgres がレプリケーションスロットの作成時に使用するオブジェクトに対して、別のトランザクションがロックを保持していることが原因である可能性があります。
どのクエリがブロックしているかを確認するには、Postgres ソースで以下のクエリを実行してください。