database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-05-03 22:24:49 +03:00
Code

Doc: Improve the Replica Identity information.

Browse Source 
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
This commit is contained in:
Amit Kapila 2025-01-16 08:33:02 +05:30
parent 32a18cc0a7
commit 965b2cc0a4
2 changed files with 55 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
doc/src/sgml/logical-replication.sgml
View File

@ -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">

3
doc/src/sgml/ref/alter_table.sgml
View File

@ -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>