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/[email protected]

Author: Amit Kapila

doc/src/sgml/func.sgml

@@ -29118,6 +29118,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>
 

src/backend/replication/slotfuncs.c

@@ -698,13 +698,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,