Re: Documentation to upgrade logical replication cluster

On Thu, 25 Jan 2024 at 05:45, Peter Smith <smithpb2250(at)gmail(dot)com> wrote:
>
> Here are some review comments for patch v3.
>
> ======
> doc/src/sgml/ref/pgupgrade.sgml
>
> 1.
> +
> + <para>
> + This page does not cover steps to upgrade logical replication
> clusters, refer
> + <xref linkend="logical-replication-upgrade"/> for details on upgrading
> + logical replication clusters.
> + </para>
> +
>
> I felt that maybe this note was misplaced. Won't it be better to put
> this down in the "Usage" section of this page?
>
> BEFORE
> These are the steps to perform an upgrade with pg_upgrade:
>
> SUGGESTION (or something like this)
> Below are the steps to perform an upgrade with pg_upgrade.
>
> Note, the steps to upgrade logical replication clusters are not
> covered here; refer to <xref linkend="logical-replication-upgrade"/>
> for details.

Modified

> ~~~
>
> 2.
> Configure the servers for log shipping. (You do not need to run
> <function>pg_backup_start()</function> and
> <function>pg_backup_stop()</function>
> or take a file system backup as the standbys are still synchronized
> - with the primary.) Only logical slots on the primary are copied to the
> - new standby, but other slots on the old standby are not copied so must
> - be recreated manually.
> + with the primary.) In version 17.0 or later, only logical slots on the
> + primary are copied to the new standby, but other slots on the
> old standby
> + are not copied so must be recreated manually.
> </para>
>
> This para was still unclear to me. What is version 17.0 referring to
> -- the old_cluster version? Do you mean something like:
> If the old cluster is < v17 then logical slots are not copied. If the
> old_cluster is >= v17 then...

Yes, I have rephrased it now.

> ======
> doc/src/sgml/logical-replication.sgml
>
> 3.
> + <para>
> + While upgrading a subscriber, write operations can be performed in the
> + publisher, these changes will be replicated to the subscriber once the
> + subscriber upgradation is completed.
> + </para>
>
> 3a.
> /publisher, these changes/publisher. These changes/

Modified

> ~
>
> 3b.
> "upgradation" ??. See [1]
>
> maybe just /upgradation/upgrade/

Modified

> ~~~
>
> 4. GENERAL - prompts/paths
>
> I noticed in v3 you removed all the cmd prompts like:
> dba(at)node1:/opt/PostgreSQL/postgres/17/bin$
> dba(at)node2:/opt/PostgreSQL/postgres/18/bin$
> etc.
>
> I thought those were helpful to disambiguate which server/version was
> being operated on. I wonder if there is some way to keep information
> still but not make it look like a real current directory that
> Kuroda-san did not like:
>
> e.g. Maybe something like the below is possible?
>
> (dba(at)node1: v17) pg_upgrade...
> (dba(at)node2: v18) pg_upgrade...

I did not want to add this as our current documentation is consistent
with how it is documented in the pg_upgrade page at [1].

The v4 version patch attached at [2] has the changes for the same.

[1] - https://www.postgresql.org/docs/devel/pgupgrade.html
[2] - https://www.postgresql.org/message-id/CALDaNm1wCHmBwpLM%3Dd9oBoZqKXOe-TwC-LCcHC9gFy0bazZU6Q%40mail.gmail.com

Regards,
Vignesh