From 84255b6f72ab1c388b964782c8a9219a40492fb6 Mon Sep 17 00:00:00 2001 From: Robert Treat Date: Thu, 9 Jan 2025 21:23:31 -0500 Subject: [PATCH v2] Expand and clarify Replica Identity information Based on discussion from James Coleman, Peter Smith, Laurenz Albe, and Amit Kapala. --- doc/src/sgml/logical-replication.sgml | 79 +++++++++++++++++---------- doc/src/sgml/ref/alter_table.sgml | 5 +- 2 files changed, 53 insertions(+), 31 deletions(-) diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml index 8290cd1a08..8e7fcf0f8f 100644 --- a/doc/src/sgml/logical-replication.sgml +++ b/doc/src/sgml/logical-replication.sgml @@ -124,35 +124,6 @@ TRUNCATE. See ). - - A published table must have a replica identity configured in - order to be able to replicate UPDATE - and DELETE operations, so that appropriate rows to - update or delete can be identified on the subscriber side. By default, - this is the primary key, if there is one. Another unique index (with - certain additional requirements) can also be set to be the replica - identity. If the table does not have any suitable key, then it can be set - to replica identity FULL, which means the entire row becomes - the key. When replica identity FULL is specified, - indexes can be used on the subscriber side for searching the rows. Candidate - indexes must be btree or hash, non-partial, and the leftmost index field must - be a column (not an expression) that references the published table column. - These restrictions on the non-unique index properties adhere to some of the - restrictions that are enforced for primary keys. If there are no such - suitable indexes, the search on the subscriber side can be very inefficient, - therefore replica identity FULL should only be used as a - fallback if no other solution is possible. If a replica identity other - than FULL is set on the publisher side, a replica identity - comprising the same or fewer columns must also be set on the subscriber - side. See for details on - how to set the replica identity. If a table without a replica identity is - added to a publication that replicates UPDATE - or DELETE operations then - subsequent UPDATE or DELETE - operations will cause an error on the publisher. INSERT - operations can proceed regardless of any replica identity. - - Every publication can have multiple subscribers. @@ -169,6 +140,56 @@ transactional, so the table will start or stop replicating at the correct snapshot once the transaction has committed. + + + Replica Identity + + A published table must have a replica identity configured in + order to be able to replicate UPDATE + and DELETE operations, so that appropriate rows to + update or delete can be identified on the subscriber side. + + + By default, + this is the primary key, if there is one. Another unique index (with + certain additional requirements) can also be set to be the replica + identity. If the table does not have any suitable key, then it can be set + to replica identity FULL, which means the entire row becomes + the key. When replica identity FULL is specified, + indexes can be used on the subscriber side for searching the rows. Candidate + indexes must be btree or hash, non-partial, and the leftmost index field must + be a column (not an expression) that references the published table column. + These restrictions on the non-unique index properties adhere to some of the + restrictions that are enforced for primary keys. If there are no such + suitable indexes, the search on the subscriber side can be very inefficient, + therefore replica identity FULL should only be used as a + fallback if no other solution is possible. + + + If a replica identity other + than FULL is set on the publisher side, a replica identity + comprising the same or fewer columns must also be set on the subscriber + side. + + + If a table with replica identity set to NOTHING + (or set DEFAULT but with no primary key, or set + USING INDEX but the index has been dropped) is + added to a publication that replicates UPDATE + or DELETE operations, + subsequent UPDATE or DELETE + operations will cause an error on the publisher. + + + INSERT + operations can proceed regardless of any replica identity. + + + See for details on + how to set the replica identity. + + + diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml index c8f7ab7d95..ac67c3f25f 100644 --- a/doc/src/sgml/ref/alter_table.sgml +++ b/doc/src/sgml/ref/alter_table.sgml @@ -927,8 +927,9 @@ WITH ( MODULUS numeric_literal, REM DEFAULT - Records the old values of the columns of the primary key, if any. - This is the default for non-system tables. + Records the old values of the columns of the primary key. + This is the default for non-system tables. When there + is no primary key, the behavior is the same as NOTHING. -- 2.24.3 (Apple Git-128)