From 1ac51a2d678435ab72bee23381e26d0f6ead64a0 Mon Sep 17 00:00:00 2001 From: Kaushik Iska Date: Wed, 27 Aug 2025 10:59:57 -0700 Subject: [PATCH 1/2] Document caveats with primary key updates --- .../data-ingestion/clickpipes/postgres/faq.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/integrations/data-ingestion/clickpipes/postgres/faq.md b/docs/integrations/data-ingestion/clickpipes/postgres/faq.md index 08b658a311c..9d1b8c2409d 100644 --- a/docs/integrations/data-ingestion/clickpipes/postgres/faq.md +++ b/docs/integrations/data-ingestion/clickpipes/postgres/faq.md @@ -58,6 +58,18 @@ For more details, refer to: * [ReplacingMergeTree table engine best practices](https://docs.peerdb.io/bestpractices/clickhouse_datamodeling#replacingmergetree-table-engine) * [Postgres-to-ClickHouse CDC internals blog](https://clickhouse.com/blog/postgres-to-clickhouse-data-modeling-tips) +### Can I update primary key columns in PostgreSQL? {#can-i-update-primary-key-columns-in-postgresql} + +**Important limitation:** Primary key updates in PostgreSQL cannot be properly replayed in ClickHouse by default. + +This limitation exists because `ReplacingMergeTree` deduplication works based on the `ORDER BY` columns (which typically correspond to the primary key). When a primary key is updated in PostgreSQL, it appears as a new row with a different key in ClickHouse, rather than an update to the existing row. This can lead to both the old and new primary key values existing in your ClickHouse table. + +Note that updating primary key columns is not a common practice in PostgreSQL database design, as primary keys are intended to be immutable identifiers. Most applications avoid primary key updates by design, making this limitation rarely encountered in typical use cases. + +There is an experimental setting available that can enable primary key update handling, but it comes with significant performance implications and is not recommended for production use without careful consideration. + +If your use case requires updating primary key columns in PostgreSQL and having those changes properly reflected in ClickHouse, please reach out to our support team at [db-integrations-support@clickhouse.com](mailto:db-integrations-support@clickhouse.com) to discuss your specific requirements and potential solutions. + ### Do you support schema changes? {#do-you-support-schema-changes} Please refer to the [ClickPipes for Postgres: Schema Changes Propagation Support](./schema-changes) page for more information. From 847fbf38e9b52562992d0dda23af1166d3d9ae43 Mon Sep 17 00:00:00 2001 From: Kaushik Iska Date: Wed, 27 Aug 2025 11:10:40 -0700 Subject: [PATCH 2/2] add warning --- docs/integrations/data-ingestion/clickpipes/postgres/faq.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/integrations/data-ingestion/clickpipes/postgres/faq.md b/docs/integrations/data-ingestion/clickpipes/postgres/faq.md index 9d1b8c2409d..0709df6f740 100644 --- a/docs/integrations/data-ingestion/clickpipes/postgres/faq.md +++ b/docs/integrations/data-ingestion/clickpipes/postgres/faq.md @@ -60,9 +60,11 @@ For more details, refer to: ### Can I update primary key columns in PostgreSQL? {#can-i-update-primary-key-columns-in-postgresql} -**Important limitation:** Primary key updates in PostgreSQL cannot be properly replayed in ClickHouse by default. +:::warning +Primary key updates in PostgreSQL cannot be properly replayed in ClickHouse by default. This limitation exists because `ReplacingMergeTree` deduplication works based on the `ORDER BY` columns (which typically correspond to the primary key). When a primary key is updated in PostgreSQL, it appears as a new row with a different key in ClickHouse, rather than an update to the existing row. This can lead to both the old and new primary key values existing in your ClickHouse table. +::: Note that updating primary key columns is not a common practice in PostgreSQL database design, as primary keys are intended to be immutable identifiers. Most applications avoid primary key updates by design, making this limitation rarely encountered in typical use cases.