Doc: Improve the Replica Identity information.

This commit improves the Replica Identity information and clarifies its
related restrictions.

Reported-by: James Coleman
Author: Peter Smith
Co-authored-by: Robert Treat
Reviewed-by: Laurenz Albe, Amit Kapila
Discussion: https://postgr.es/m/CAAaqYe_=7qFSqW7qavvhVy58mmzk1uSQ0RReRiUHyKO5znvr7g@mail.gmail.com

diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 8290cd1a083d82659e92fcd228358a1a2086a1cc..7cc5f4b18d66199ad060d90c2a76da5ff6fcaebb 100644 (file)
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -124,35 +124,6 @@
    <command>TRUNCATE</command>. See <xref linkend="logical-replication-row-filter"/>).
   </para>
 
-  <para>
-   A published table must have a <firstterm>replica identity</firstterm> configured in
-   order to be able to replicate <command>UPDATE</command>
-   and <command>DELETE</command> 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 <literal>FULL</literal>, which means the entire row becomes
-   the key.  When replica identity <literal>FULL</literal> 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 <literal>FULL</literal> should only be used as a
-   fallback if no other solution is possible.  If a replica identity other
-   than <literal>FULL</literal> is set on the publisher side, a replica identity
-   comprising the same or fewer columns must also be set on the subscriber
-   side.  See <xref linkend="sql-altertable-replica-identity"/> for details on
-   how to set the replica identity.  If a table without a replica identity is
-   added to a publication that replicates <command>UPDATE</command>
-   or <command>DELETE</command> operations then
-   subsequent <command>UPDATE</command> or <command>DELETE</command>
-   operations will cause an error on the publisher.  <command>INSERT</command>
-   operations can proceed regardless of any replica identity.
-  </para>
-
   <para>
    Every publication can have multiple subscribers.
   </para>
@@ -169,6 +140,59 @@
    transactional, so the table will start or stop replicating at the correct
    snapshot once the transaction has committed.
   </para>
+
+  <sect2 id="logical-replication-publication-replica-identity">
+   <title>Replica Identity</title>
+
+   <para>
+    A published table must have a <firstterm>replica identity</firstterm>
+    configured in order to be able to replicate <command>UPDATE</command>
+    and <command>DELETE</command> operations, so that appropriate rows to
+    update or delete can be identified on the subscriber side.
+   </para>
+
+   <para>
+    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 <literal>FULL</literal>, which means the entire row
+    becomes the key.  When replica identity <literal>FULL</literal> 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
+    <literal>FULL</literal> should only be used as a fallback if no other
+    solution is possible.
+   </para>
+
+   <para>
+    If a replica identity other than <literal>FULL</literal> is set on the
+    publisher side, a replica identity comprising the same or fewer columns
+    must also be set on the subscriber side.
+   </para>
+
+   <para>
+    Tables with a replica identity defined as <literal>NOTHING</literal>,
+    <literal>DEFAULT</literal> without a primary key, or <literal>USING
+    INDEX</literal> with a dropped index, cannot support
+    <command>UPDATE</command> or <command>DELETE</command> operations when
+    included in a publication replicating these actions. Attempting such
+    operations will result in an error on the publisher.
+   </para>
+
+   <para>
+    <command>INSERT</command> operations can proceed regardless of any replica identity.
+   </para>
+
+   <para>
+    See <link linkend="sql-altertable-replica-identity"><literal>ALTER TABLE...REPLICA IDENTITY</literal></link>
+    for details on how to set the replica identity.
+   </para>
+  </sect2>
+
  </sect1>
 
  <sect1 id="logical-replication-subscription">

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 938450fba18dd1635edfd70108d1dff9fdd538d5..df4f5d5bbd8e94c3bbcfc618e8a40762a8cbced8 100644 (file)
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -927,8 +927,9 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
        <term><literal>DEFAULT</literal></term>
        <listitem>
         <para>
-         Records the old values of the columns of the primary key, if any.
+         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 <literal>NOTHING</literal>.
         </para>
        </listitem>
       </varlistentry>