Hi, We have documentation on how to upgrade "publisher" and "subscriber" at [1], but currently we do not have any documentation on how to upgrade logical replication clusters. Here is a patch to document how to upgrade different logical replication clusters: a) Upgrade 2 node logical replication cluster b) Upgrade cascaded logical replication cluster c) Upgrade 2 node circular logical replication cluster. Thoughts?
[1] - https://www.postgresql.org/docs/devel/pgupgrade.html Regards, Vignesh
From 9458a2c62a0702316d9ab339cd01dac0e088c52e Mon Sep 17 00:00:00 2001 From: Vignesh C <vignes...@gmail.com> Date: Wed, 13 Dec 2023 14:11:58 +0530 Subject: [PATCH v1] Documentation for upgrading logical replication cluster. Documentation for upgrading logical replication cluster. --- doc/src/sgml/ref/pgupgrade.sgml | 618 +++++++++++++++++++++++++++++++- 1 file changed, 616 insertions(+), 2 deletions(-) diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml index 87be1fb1c2..87f453d509 100644 --- a/doc/src/sgml/ref/pgupgrade.sgml +++ b/doc/src/sgml/ref/pgupgrade.sgml @@ -383,7 +383,7 @@ make prefix=/usr/local/pgsql.new install </para> </step> - <step> + <step id="prepare-publisher-upgrades"> <title>Prepare for publisher upgrades</title> <para> @@ -456,7 +456,7 @@ make prefix=/usr/local/pgsql.new install </step> - <step> + <step id="prepare-subscriber-upgrades"> <title>Prepare for subscriber upgrades</title> <para> @@ -506,6 +506,620 @@ make prefix=/usr/local/pgsql.new install </itemizedlist> </step> + <step> + <title>Prepare for logical replication cluster upgrades</title> + + <para> + Migration of logical replication clusters can be done when all the members + of the old logical replication clusters are version 17.0 or later. + </para> + + <note> + <para> + The logical replication restrictions apply to logical replication cluster + upgrades also. See <xref linkend="logical-replication-restrictions"/> for + the details of logical replication restrictions. + </para> + <para> + The prerequisites of publisher upgrade applies to logical Replication + cluster upgrades also. See <xref linkend="prepare-publisher-upgrades"/> + for the details of publisher upgrade prerequisites. + </para> + <para> + The prerequisites of subscriber upgrade applies to logical Replication + cluster upgrades also. See <xref linkend="prepare-subscriber-upgrades"/> + for the details of subscriber upgrade prerequisites. + </para> + </note> + + <warning> + <para> + Upgrading logical replication cluster requires multiple steps to be + performed on various nodes. Because not all operations are + transactional, the user is advised to take backups. Backups can be taken + as described in <xref linkend="backup-base-backup"/>. + </para> + </warning> + + <para> + The steps to upgrade logical replication clusters in various scenarios are + given below. + </para> + + <procedure> + <step> + <title>Steps to Upgrade 2 node logical replication cluster</title> + + <procedure> + <step> + <para> + Let's say publisher is in <literal>node1</literal> and subscriber is + in <literal>node2</literal>. + </para> + </step> + + <step> + <para> + Stop the publisher server in <literal>node1</literal>, for e.g.: + +<programlisting> +dba@node1:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/pub_data stop -l logfile +</programlisting> + + </para> + </step> + + <step> + <para> + Disable all the subscriptions on <literal>node2</literal> that are + subscribing the changes from <literal>node1</literal> by using + <link linkend="sql-altersubscription-params-disable"><command>ALTER SUBSCRIPTION ... DISABLE</command></link>, + for e.g.: +<programlisting> +node2=# ALTER SUBSCRIPTION sub1_node1_node2 DISABLE; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node1_node2 DISABLE; +ALTER SUBSCRIPTION +</programlisting> + </para> + </step> + + <step> + <para> + Upgrade the publisher node <literal>node1</literal>'s server to the + required newer version, for e.g.: +<programlisting> +dba@node1:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_upgrade + --old-datadir "/opt/PostgreSQL/postgres/17/pub_data" + --new-datadir "/opt/PostgreSQL/postgres/&majorversion;/pub_upgraded_data" + --old-bindir "/opt/PostgreSQL/postgres/17/bin" + --new-bindir "/opt/PostgreSQL/postgres/&majorversion;/bin" +</programlisting> + </para> + </step> + + <step> + <para> + Start the upgraded publisher node <literal>node1</literal>'s server, for e.g.: +<programlisting> +dba@node1:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/pub_upgraded_data start -l logfile +</programlisting> + </para> + </step> + + <step> + <para> + Stop the subscriber server in <literal>node2</literal>, for e.g.: +<programlisting> +dba@node2:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/sub_data stop -l logfile +</programlisting> + </para> + </step> + + <step> + <para> + Upgrade the subscriber node <literal>node2</literal>'s server to + the required new version, for e.g.: +<programlisting> +dba@node2:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_upgrade + --old-datadir "/opt/PostgreSQL/postgres/17/sub_data" + --new-datadir "/opt/PostgreSQL/postgres/&majorversion;/sub_upgraded_data" + --old-bindir "/opt/PostgreSQL/postgres/17/bin" + --new-bindir "/opt/PostgreSQL/postgres/&majorversion;/bin" +</programlisting> + </para> + </step> + + <step> + <para> + Start the upgraded subscriber node <literal>node2</literal>'s server, + for e.g.: +<programlisting> +dba@node2:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/sub_upgraded_data start -l logfile +</programlisting> + </para> + </step> + + <step> + <para> + Create any tables that were created in the upgraded publisher <literal>node1</literal> + server between step-5 and now, for e.g.: +<programlisting> +node2=# CREATE TABLE distributors ( +node2(# did integer CONSTRAINT no_null NOT NULL, +node2(# name varchar(40) NOT NULL +node2(# ); +CREATE TABLE +</programlisting> + </para> + </step> + + <step> + <para> + Enable all the subscriptions on <literal>node2</literal> that are + subscribing the changes from <literal>node1</literal> by using + <link linkend="sql-altersubscription-params-enable"><command>ALTER SUBSCRIPTION ... ENABLE</command></link>, + for e.g.: +<programlisting> +node2=# ALTER SUBSCRIPTION sub1_node1_node2 ENABLE; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node1_node2 ENABLE; +ALTER SUBSCRIPTION +</programlisting> + </para> + </step> + + <step> + <para> + Refresh the publications using + <link linkend="sql-altersubscription-params-refresh-publication"><command>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</command></link>, + for e.g.: +<programlisting> +node2=# ALTER SUBSCRIPTION sub1_node1_node2 REFRESH PUBLICATION; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node1_node2 REFRESH PUBLICATION; +ALTER SUBSCRIPTION +</programlisting> + </para> + </step> + + </procedure> + + </step> + </procedure> + + <procedure> + <step> + <title>Steps to upgrade cascaded logical replication clusters</title> + <procedure> + <step> + <para> + Let's say we have a cascaded logical replication setup + <literal>node1</literal>-><literal>node2</literal>-><literal>node3</literal>. + Here <literal>node2</literal> is subscribing the changes from + <literal>node1</literal> and <literal>node3</literal> is subscribing + the changes from <literal>node2</literal>. + </para> + </step> + <step> + <para> + Stop the server in <literal>node1</literal>, for e.g.: + +<programlisting> +dba@node1:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/data1 stop -l logfile +</programlisting> + </para> + </step> + + <step> + <para> + Disable all the subscriptions on <literal>node2</literal> that are + subscribing the changes from <literal>node1</literal> by using + <link linkend="sql-altersubscription-params-disable"><command>ALTER SUBSCRIPTION ... DISABLE</command></link>, + for e.g.: +<programlisting> +node2=# ALTER SUBSCRIPTION sub1_node1_node2 DISABLE; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node1_node2 DISABLE; +ALTER SUBSCRIPTION +</programlisting> + </para> + </step> + + <step> + <para> + Upgrade the publisher node <literal>node1</literal>'s server to the + required newer version, for e.g.: +<programlisting> +dba@node1:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_upgrade + --old-datadir "/opt/PostgreSQL/postgres/17/data1" + --new-datadir "/opt/PostgreSQL/postgres/&majorversion;/data1_upgraded" + --old-bindir "/opt/PostgreSQL/postgres/17/bin" + --new-bindir "/opt/PostgreSQL/postgres/&majorversion;/bin" +</programlisting> + </para> + </step> + + <step> + <para> + Start the upgraded node <literal>node1</literal>'s server, for e.g.: +<programlisting> +dba@node1:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/data1_upgraded start -l logfile +</programlisting> + </para> + </step> + + <step> + <para> + Stop the server in <literal>node2</literal>, for e.g.: +<programlisting> +dba@node2:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/data2 stop -l logfile +</programlisting> + </para> + </step> + + <step> + <para> + Disable all the subscriptions on <literal>node3</literal> that are + subscribing the changes from <literal>node2</literal> by using + <link linkend="sql-altersubscription-params-disable"><command>ALTER SUBSCRIPTION ... DISABLE</command></link>, + for e.g.: +<programlisting> +node3=# ALTER SUBSCRIPTION sub1_node2_node3 DISABLE; +ALTER SUBSCRIPTION +node3=# ALTER SUBSCRIPTION sub2_node2_node3 DISABLE; +ALTER SUBSCRIPTION +</programlisting> + </para> + </step> + + <step> + <para> + Upgrade the node <literal>node2</literal>'s server to the required + new version, for e.g.: +<programlisting> +dba@node2:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_upgrade + --old-datadir "/opt/PostgreSQL/postgres/17/data2" + --new-datadir "/opt/PostgreSQL/postgres/&majorversion;/data2_upgraded" + --old-bindir "/opt/PostgreSQL/postgres/17/bin" + --new-bindir "/opt/PostgreSQL/postgres/&majorversion;/bin" +</programlisting> + </para> + </step> + + <step> + <para> + Start the upgraded node <literal>node2</literal>'s server, for e.g.: +<programlisting> +dba@node2:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/data2_upgraded start -l logfile +</programlisting> + </para> + </step> + + <step> + <para> + Create any tables that were created in the upgraded publisher <literal>node1</literal> + server between step-5 and now, for e.g.: +<programlisting> +node2=# CREATE TABLE distributors ( +node2(# did integer CONSTRAINT no_null NOT NULL, +node2(# name varchar(40) NOT NULL +node2(# ); +CREATE TABLE +</programlisting> + </para> + </step> + + <step> + <para> + Enable all the subscriptions on <literal>node2</literal> that are + subscribing the changes from <literal>node2</literal> by using + <link linkend="sql-altersubscription-params-enable"><command>ALTER SUBSCRIPTION ... ENABLE</command></link>, + for e.g.: +<programlisting> +node2=# ALTER SUBSCRIPTION sub1_node1_node2 ENABLE; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node1_node2 ENABLE; +ALTER SUBSCRIPTION +</programlisting> + </para> + </step> + + <step> + <para> + Refresh the publications using + <link linkend="sql-altersubscription-params-refresh-publication"><command>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</command></link>, + for e.g.: +<programlisting> +node2=# ALTER SUBSCRIPTION sub1_node1_node2 REFRESH PUBLICATION; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node1_node2 REFRESH PUBLICATION; +ALTER SUBSCRIPTION +</programlisting> + </para> + </step> + + <step> + <para> + Stop the server in <literal>node3</literal>, for e.g.: +<programlisting> +dba@node3:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/data3 stop -l logfile +</programlisting> + </para> + </step> + + <step> + <para> + Upgrade the node <literal>node3</literal>'s server to the required + new version, for e.g.: +<programlisting> +dba@node3:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_upgrade + --old-datadir "/opt/PostgreSQL/postgres/17/data3" + --new-datadir "/opt/PostgreSQL/postgres/&majorversion;/data3_upgraded" + --old-bindir "/opt/PostgreSQL/postgres/17/bin" + --new-bindir "/opt/PostgreSQL/postgres/&majorversion;/bin" +</programlisting> + </para> + </step> + + <step> + <para> + Start the upgraded node <literal>node3</literal>'s server, for e.g.: +<programlisting> +dba@node3:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/data3_upgraded start -l logfile +</programlisting> + </para> + </step> + + <step> + <para> + Create any tables that were created in the upgraded node + <literal>node2</literal> between step-9 and now, for e.g.: +<programlisting> +node2=# CREATE TABLE distributors ( +node2(# did integer CONSTRAINT no_null NOT NULL, +node2(# name varchar(40) NOT NULL +node2(# ); +CREATE TABLE +</programlisting> + </para> + </step> + + <step> + <para> + Enable all the subscriptions on <literal>node3</literal> that are + subscribing the changes from <literal>node2</literal> by using + <link linkend="sql-altersubscription-params-enable"><command>ALTER SUBSCRIPTION ... ENABLE</command></link>, + for e.g.: +<programlisting> +node3=# ALTER SUBSCRIPTION sub1_node2_node3 ENABLE; +ALTER SUBSCRIPTION +node3=# ALTER SUBSCRIPTION sub2_node2_node3 ENABLE; +ALTER SUBSCRIPTION +</programlisting> + </para> + </step> + + <step> + <para> + Refresh the publications using + <link linkend="sql-altersubscription-params-refresh-publication"><command>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</command></link>, + for e.g.: +<programlisting> +node3=# ALTER SUBSCRIPTION sub1_node2_node3 REFRESH PUBLICATION; +ALTER SUBSCRIPTION +node3=# ALTER SUBSCRIPTION sub2_node2_node3 REFRESH PUBLICATION; +ALTER SUBSCRIPTION +</programlisting> + </para> + </step> + + </procedure> + + </step> + </procedure> + + <procedure> + <step> + <title>Steps to Upgrade 2 node circular logical replication cluster</title> + <procedure> + <step> + <para> + Let's say we have a circular logical replication setup + <literal>node1</literal>-><literal>node2</literal> and + <literal>node2</literal>-><literal>node1</literal>. Here + <literal>node2</literal> is subscribing the changes from + <literal>node1</literal> and <literal>node1</literal> is subscribing + the changes from <literal>node2</literal>. + </para> + </step> + <step> + <para> + Stop the server in <literal>node1</literal>, for e.g.: + +<programlisting> +dba@node1:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/data1 stop -l logfile +</programlisting> + + </para> + </step> + <step> + <para> + Disable all the subscriptions on <literal>node2</literal> that are + subscribing the changes from <literal>node1</literal> by using + <link linkend="sql-altersubscription-params-disable"><command>ALTER SUBSCRIPTION ... DISABLE</command></link>, + for e.g.: +<programlisting> +node2=# ALTER SUBSCRIPTION sub1_node1_node2 DISABLE; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node1_node2 DISABLE; +ALTER SUBSCRIPTION +</programlisting> + </para> + </step> + <step> + <para> + Upgrade the node <literal>node1</literal>'s server to the required + newer version, for e.g.: +<programlisting> +dba@node1:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_upgrade + --old-datadir "/opt/PostgreSQL/postgres/17/data1" + --new-datadir "/opt/PostgreSQL/postgres/&majorversion;/data1_upgraded" + --old-bindir "/opt/PostgreSQL/postgres/17/bin" + --new-bindir "/opt/PostgreSQL/postgres/&majorversion;/bin" +</programlisting> + </para> + </step> + <step> + <para> + Start the upgraded node <literal>node1</literal>'s server, for e.g.: +<programlisting> +dba@node1:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/data1_upgraded start -l logfile +</programlisting> + </para> + </step> + <step> + <para> + Wait till all the incremental changes are synchronized. + </para> + </step> + + <step> + <para> + Create any tables that were created in <literal>node2</literal> + between step-2 and now, for e.g.: +<programlisting> +node2=# CREATE TABLE distributors ( +node2(# did integer CONSTRAINT no_null NOT NULL, +node2(# name varchar(40) NOT NULL +node2(# ); +CREATE TABLE +</programlisting> + </para> + </step> + + <step> + <para> + Enable all the subscriptions on <literal>node2</literal> that are + subscribing the changes from <literal>node1</literal> by using + <link linkend="sql-altersubscription-params-enable"><command>ALTER SUBSCRIPTION ... ENABLE</command></link>, + for e.g.: +<programlisting> +node2=# ALTER SUBSCRIPTION sub1_node1_node2 ENABLE; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node1_node2 ENABLE; +ALTER SUBSCRIPTION +</programlisting> + </para> + </step> + + <step> + <para> + Refresh the publications using + <link linkend="sql-altersubscription-params-refresh-publication"><command>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</command></link>, + for e.g.: +<programlisting> +node2=# ALTER SUBSCRIPTION sub1_node1_node2 REFRESH PUBLICATION; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node1_node2 REFRESH PUBLICATION; +ALTER SUBSCRIPTION +</programlisting> + </para> + </step> + <step> + <para> + Stop the server in <literal>node2</literal>, for e.g.: +<programlisting> +dba@node2:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/data2 stop -l logfile +</programlisting> + </para> + </step> + <step> + <para> + Disable all the subscriptions on <literal>node1</literal> that are + subscribing the changes from <literal>node2</literal> by using + <link linkend="sql-altersubscription-params-disable"><command>ALTER SUBSCRIPTION ... DISABLE</command></link>, + for e.g.: +<programlisting> +node2=# ALTER SUBSCRIPTION sub1_node2_node1 DISABLE; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node2_node1 DISABLE; +ALTER SUBSCRIPTION +</programlisting> + </para> + </step> + <step> + <para> + Upgrade the node <literal>node2</literal>'s server to the required + new version, for e.g.: +<programlisting> +dba@node2:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_upgrade + --old-datadir "/opt/PostgreSQL/postgres/17/data2" + --new-datadir "/opt/PostgreSQL/postgres/&majorversion;/data2_upgraded" + --old-bindir "/opt/PostgreSQL/postgres/17/bin" + --new-bindir "/opt/PostgreSQL/postgres/&majorversion;/bin" +</programlisting> + </para> + </step> + <step> + <para> + Start the upgraded node <literal>node2</literal>'s server, for e.g.: +<programlisting> +dba@node2:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/data2_upgraded start -l logfile +</programlisting> + </para> + </step> + + <step> + <para> + Create any tables that were created in the upgraded node + <literal>node1</literal> between step-10 and now, for e.g.: +<programlisting> +node2=# CREATE TABLE distributors ( +node2(# did integer CONSTRAINT no_null NOT NULL, +node2(# name varchar(40) NOT NULL +node2(# ); +CREATE TABLE +</programlisting> + </para> + </step> + + <step> + <para> + Enable all the subscriptions on <literal>node1</literal> that are + subscribing the changes from <literal>node2</literal> by using + <link linkend="sql-altersubscription-params-enable"><command>ALTER SUBSCRIPTION ... ENABLE</command></link>, + for e.g.: +<programlisting> +node2=# ALTER SUBSCRIPTION sub1_node2_node1 ENABLE; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node2_node1 ENABLE; +ALTER SUBSCRIPTION +</programlisting> + </para> + </step> + + <step> + <para> + Refresh the publications using + <link linkend="sql-altersubscription-params-refresh-publication"><command>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</command></link> + for e.g.: +<programlisting> +node2=# ALTER SUBSCRIPTION sub1_node1_node2 REFRESH PUBLICATION; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node1_node2 REFRESH PUBLICATION; +ALTER SUBSCRIPTION +</programlisting> + </para> + </step> + + </procedure> + + </step> + </procedure> + + </step> + <step> <title>Stop both servers</title> -- 2.34.1