Re: DOCS - Clarify that REFRESH SEQUENCES might be using stale publication data

On Thu, Jul 2, 2026 at 6:48 PM Amit Kapila <amit(dot)kapila16(at)gmail(dot)com> wrote:
>
> On Thu, Jul 2, 2026 at 8:29 AM Peter Smith <smithpb2250(at)gmail(dot)com> wrote:
> >
> > The docs do refer to "currently subscribed sequences" but do not
> > explicitly warn about this gotcha.
> >
> > PSA: a patch to add a clarifying sentence.
> >
>
> It does not add or remove
> sequences from the subscription to match the publication.
> </para>
> + <para>
> + If the publication's sequence membership has changed,
> + <link linkend="sql-altersubscription-params-refresh-publication">
> + <command>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</command></link>
> + should be run before <literal>REFRESH SEQUENCES</literal> to ensure the
> + subscription's known sequence list is current.
> + </para>
>
> It is already mentioned that this command "does not add or remove
> sequences from the subscription to match the publication.". Adding
> more information, especially a separate para for the same, appears
> like bloating the text in docs. OTOH, I see your point of running
> REFRESH PUBLICATION before REFRESH SEQUENCES which I tried to cover in
> the existing paragraph. Apart from that, I have merged your
> doc-changes from another thread [1] which is on the same topic. Let's
> commit them together.
>

+1 to combine both patches.

Upon re-reading, I think there is still ambiguity due to that word
"synchronizing".

IMO, when we are talking about "synchronizing" sequences, we mean that
the sequence *values* on the subscriber will be synchronized with
those from the publisher.

So, REFRESH SEQUENCES synchronizes all currently known sequences.

OTOH, the REFRESH PUBLICATION refreshes all sequences known to the
subscriber, but it will only synchronize values for newly added ones
(not all of them). So "synchnonizing" is a misleading term to use when
describing the `pg_subscription_rel` members getting updated.

~~~

CHANGES:

Alter Subscription REFRESH SEQUENCES:

The REFRESH PUBLICATION option already correctly describes all that
above ("Previously subscribed sequences are not re-synchronized."), so
I think the fix is to remove the unnecessary explanation: "Unlike
...". After doing that, the remaining text is shorter and more
correct.

Logical Replication:

(2nd bullet) Should also mention that REFRESH PUBLICATION refreshes
the sequences known to the subscription.

~~~

PSA v3.

======
Kind Regards,
Peter Smith.
Fujitsu Australia