From 4be8ea86504ec8c870ae0f615a5efef38b65571d Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Fri, 3 Jul 2026 15:03:08 +1200
Subject: [PATCH v3] doc: Clarify sequence synchronization commands.

Improve the REFRESH SEQUENCES description in ALTER SUBSCRIPTION to more
accurately explain how it differs from REFRESH PUBLICATION: REFRESH
PUBLICATION synchronizes the subscription's set of sequences with the
publication (adding new and removing dropped sequences), whereas REFRESH
SEQUENCES only re-synchronizes data for the currently subscribed sequences
without changing which sequences are subscribed.  Also advise running
REFRESH PUBLICATION first when the publication's set of sequences has
changed.

In the "Replicating Sequences" section, note that CREATE SUBSCRIPTION
uses copy_data = true (the default) to copy the initial sequence values,
and link to the copy_data parameter.
---
 doc/src/sgml/logical-replication.sgml    |  7 +++++--
 doc/src/sgml/ref/alter_subscription.sgml | 10 ++++------
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 5befefd9c5a..1df57eb1998 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -1769,14 +1769,17 @@ Included in publications:
     <listitem>
      <para>
       use <link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>
-      to initially synchronize the published sequences.
+      with <link linkend="sql-createsubscription-params-with-copy-data">
+      <literal>copy_data = true</literal></link> (the default) to copy the
+      initial sequence values from the publisher.
      </para>
     </listitem>
     <listitem>
      <para>
       use <link linkend="sql-altersubscription-params-refresh-publication">
       <command>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</command></link>
-      to synchronize only newly added sequences.
+      to refresh what sequences are known to the subscription, and
+      synchronize only newly added sequences.
      </para>
     </listitem>
     <listitem>
diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml
index e4f0b6b16c7..3d66a3b3a8f 100644
--- a/doc/src/sgml/ref/alter_subscription.sgml
+++ b/doc/src/sgml/ref/alter_subscription.sgml
@@ -235,13 +235,11 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
     <term><literal>REFRESH SEQUENCES</literal></term>
     <listitem>
      <para>
-      Re-synchronize sequence data with the publisher. Unlike
-      <link linkend="sql-altersubscription-params-refresh-publication">
-      <command>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</command></link> which
-      only has the ability to synchronize newly added sequences,
+      Re-synchronize sequence data with the publisher.
       <literal>REFRESH SEQUENCES</literal> will re-synchronize the sequence
-      data for all currently subscribed sequences. It does not add or remove
-      sequences from the subscription to match the publication.
+      data for all currently subscribed sequences without changing which
+      sequences are subscribed. Run <literal>REFRESH PUBLICATION</literal>
+      first if the publication's set of sequences has changed.
      </para>
      <para>
       See <xref linkend="sequence-definition-mismatches"/> for
-- 
2.47.3