Doc: Fix pg_copy_logical_replication_slot description.

This commit documents that the failover option is not copied when using
the pg_copy_logical_replication_slot function.

In passing, we modify the comments in the function clarifying the reason
for this behavior.

Reported-by: <[email protected]>
Author: Hou Zhijie <[email protected]>
Reviewed-by: Amit Kapila <[email protected]>
Backpatch-through: 17, where it was introduced
Discussion: https://postgr.es/m/173976850802.682632.11315364077431550250@wrigleys.postgresql.org

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 21a8ea42f5fcce577c4a89183b3a5650b685a798..f0ccb751106cb1bf6434ce7d517c8b4c8fce47aa 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -29374,6 +29374,10 @@ postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset
         from the same <acronym>LSN</acronym> as the source logical slot.  Both
         <parameter>temporary</parameter> and <parameter>plugin</parameter> are
         optional; if they are omitted, the values of the source slot are used.
+        The <literal>failover</literal> option of the source logical slot
+        is not copied and is set to <literal>false</literal> by default. This
+        is to avoid the risk of being unable to continue logical replication
+        after failover to standby where the slot is being synchronized.
        </para></entry>
       </row>
 

diff --git a/src/backend/replication/slotfuncs.c b/src/backend/replication/slotfuncs.c
index f652ec8a73e4562f5d5bf6cd8c78b29765fcd1ab..146eef5871e28067915cb644b3da07abbfb59759 100644 (file)
--- a/src/backend/replication/slotfuncs.c
+++ b/src/backend/replication/slotfuncs.c
@@ -695,13 +695,18 @@ copy_replication_slot(FunctionCallInfo fcinfo, bool logical_slot)
         * hence pass find_startpoint false.  confirmed_flush will be set
         * below, by copying from the source slot.
         *
-        * To avoid potential issues with the slot synchronization where the
-        * restart_lsn of a replication slot can go backward, we set the
-        * failover option to false here.  This situation occurs when a slot
-        * on the primary server is dropped and immediately replaced with a
-        * new slot of the same name, created by copying from another existing
-        * slot.  However, the slot synchronization will only observe the
-        * restart_lsn of the same slot going backward.
+        * We don't copy the failover option to prevent potential issues with
+        * slot synchronization. For instance, if a slot was synchronized to
+        * the standby, then dropped on the primary, and immediately recreated
+        * by copying from another existing slot with much earlier restart_lsn
+        * and confirmed_flush_lsn, the slot synchronization would only
+        * observe the LSN of the same slot moving backward. As slot
+        * synchronization does not copy the restart_lsn and
+        * confirmed_flush_lsn backward (see update_local_synced_slot() for
+        * details), if a failover happens before the primary's slot catches
+        * up, logical replication cannot continue using the synchronized slot
+        * on the promoted standby because the slot retains the restart_lsn
+        * and confirmed_flush_lsn that are much later than expected.
         */
        create_logical_replication_slot(NameStr(*dst_name),
                                        plugin,