From 9458a2c62a0702316d9ab339cd01dac0e088c52e Mon Sep 17 00:00:00 2001 From: Vignesh C 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 - + Prepare for publisher upgrades @@ -456,7 +456,7 @@ make prefix=/usr/local/pgsql.new install - + Prepare for subscriber upgrades @@ -506,6 +506,620 @@ make prefix=/usr/local/pgsql.new install + + Prepare for logical replication cluster upgrades + + + Migration of logical replication clusters can be done when all the members + of the old logical replication clusters are version 17.0 or later. + + + + + The logical replication restrictions apply to logical replication cluster + upgrades also. See for + the details of logical replication restrictions. + + + The prerequisites of publisher upgrade applies to logical Replication + cluster upgrades also. See + for the details of publisher upgrade prerequisites. + + + The prerequisites of subscriber upgrade applies to logical Replication + cluster upgrades also. See + for the details of subscriber upgrade prerequisites. + + + + + + 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 . + + + + + The steps to upgrade logical replication clusters in various scenarios are + given below. + + + + + Steps to Upgrade 2 node logical replication cluster + + + + + Let's say publisher is in node1 and subscriber is + in node2. + + + + + + Stop the publisher server in node1, for e.g.: + + +dba@node1:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/pub_data stop -l logfile + + + + + + + + Disable all the subscriptions on node2 that are + subscribing the changes from node1 by using + ALTER SUBSCRIPTION ... DISABLE, + for e.g.: + +node2=# ALTER SUBSCRIPTION sub1_node1_node2 DISABLE; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node1_node2 DISABLE; +ALTER SUBSCRIPTION + + + + + + + Upgrade the publisher node node1's server to the + required newer version, for e.g.: + +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" + + + + + + + Start the upgraded publisher node node1's server, for e.g.: + +dba@node1:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/pub_upgraded_data start -l logfile + + + + + + + Stop the subscriber server in node2, for e.g.: + +dba@node2:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/sub_data stop -l logfile + + + + + + + Upgrade the subscriber node node2's server to + the required new version, for e.g.: + +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" + + + + + + + Start the upgraded subscriber node node2's server, + for e.g.: + +dba@node2:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/sub_upgraded_data start -l logfile + + + + + + + Create any tables that were created in the upgraded publisher node1 + server between step-5 and now, for e.g.: + +node2=# CREATE TABLE distributors ( +node2(# did integer CONSTRAINT no_null NOT NULL, +node2(# name varchar(40) NOT NULL +node2(# ); +CREATE TABLE + + + + + + + Enable all the subscriptions on node2 that are + subscribing the changes from node1 by using + ALTER SUBSCRIPTION ... ENABLE, + for e.g.: + +node2=# ALTER SUBSCRIPTION sub1_node1_node2 ENABLE; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node1_node2 ENABLE; +ALTER SUBSCRIPTION + + + + + + + Refresh the publications using + ALTER SUBSCRIPTION ... REFRESH PUBLICATION, + for e.g.: + +node2=# ALTER SUBSCRIPTION sub1_node1_node2 REFRESH PUBLICATION; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node1_node2 REFRESH PUBLICATION; +ALTER SUBSCRIPTION + + + + + + + + + + + + Steps to upgrade cascaded logical replication clusters + + + + Let's say we have a cascaded logical replication setup + node1->node2->node3. + Here node2 is subscribing the changes from + node1 and node3 is subscribing + the changes from node2. + + + + + Stop the server in node1, for e.g.: + + +dba@node1:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/data1 stop -l logfile + + + + + + + Disable all the subscriptions on node2 that are + subscribing the changes from node1 by using + ALTER SUBSCRIPTION ... DISABLE, + for e.g.: + +node2=# ALTER SUBSCRIPTION sub1_node1_node2 DISABLE; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node1_node2 DISABLE; +ALTER SUBSCRIPTION + + + + + + + Upgrade the publisher node node1's server to the + required newer version, for e.g.: + +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" + + + + + + + Start the upgraded node node1's server, for e.g.: + +dba@node1:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/data1_upgraded start -l logfile + + + + + + + Stop the server in node2, for e.g.: + +dba@node2:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/data2 stop -l logfile + + + + + + + Disable all the subscriptions on node3 that are + subscribing the changes from node2 by using + ALTER SUBSCRIPTION ... DISABLE, + for e.g.: + +node3=# ALTER SUBSCRIPTION sub1_node2_node3 DISABLE; +ALTER SUBSCRIPTION +node3=# ALTER SUBSCRIPTION sub2_node2_node3 DISABLE; +ALTER SUBSCRIPTION + + + + + + + Upgrade the node node2's server to the required + new version, for e.g.: + +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" + + + + + + + Start the upgraded node node2's server, for e.g.: + +dba@node2:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/data2_upgraded start -l logfile + + + + + + + Create any tables that were created in the upgraded publisher node1 + server between step-5 and now, for e.g.: + +node2=# CREATE TABLE distributors ( +node2(# did integer CONSTRAINT no_null NOT NULL, +node2(# name varchar(40) NOT NULL +node2(# ); +CREATE TABLE + + + + + + + Enable all the subscriptions on node2 that are + subscribing the changes from node2 by using + ALTER SUBSCRIPTION ... ENABLE, + for e.g.: + +node2=# ALTER SUBSCRIPTION sub1_node1_node2 ENABLE; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node1_node2 ENABLE; +ALTER SUBSCRIPTION + + + + + + + Refresh the publications using + ALTER SUBSCRIPTION ... REFRESH PUBLICATION, + for e.g.: + +node2=# ALTER SUBSCRIPTION sub1_node1_node2 REFRESH PUBLICATION; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node1_node2 REFRESH PUBLICATION; +ALTER SUBSCRIPTION + + + + + + + Stop the server in node3, for e.g.: + +dba@node3:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/data3 stop -l logfile + + + + + + + Upgrade the node node3's server to the required + new version, for e.g.: + +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" + + + + + + + Start the upgraded node node3's server, for e.g.: + +dba@node3:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/data3_upgraded start -l logfile + + + + + + + Create any tables that were created in the upgraded node + node2 between step-9 and now, for e.g.: + +node2=# CREATE TABLE distributors ( +node2(# did integer CONSTRAINT no_null NOT NULL, +node2(# name varchar(40) NOT NULL +node2(# ); +CREATE TABLE + + + + + + + Enable all the subscriptions on node3 that are + subscribing the changes from node2 by using + ALTER SUBSCRIPTION ... ENABLE, + for e.g.: + +node3=# ALTER SUBSCRIPTION sub1_node2_node3 ENABLE; +ALTER SUBSCRIPTION +node3=# ALTER SUBSCRIPTION sub2_node2_node3 ENABLE; +ALTER SUBSCRIPTION + + + + + + + Refresh the publications using + ALTER SUBSCRIPTION ... REFRESH PUBLICATION, + for e.g.: + +node3=# ALTER SUBSCRIPTION sub1_node2_node3 REFRESH PUBLICATION; +ALTER SUBSCRIPTION +node3=# ALTER SUBSCRIPTION sub2_node2_node3 REFRESH PUBLICATION; +ALTER SUBSCRIPTION + + + + + + + + + + + + Steps to Upgrade 2 node circular logical replication cluster + + + + Let's say we have a circular logical replication setup + node1->node2 and + node2->node1. Here + node2 is subscribing the changes from + node1 and node1 is subscribing + the changes from node2. + + + + + Stop the server in node1, for e.g.: + + +dba@node1:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/data1 stop -l logfile + + + + + + + Disable all the subscriptions on node2 that are + subscribing the changes from node1 by using + ALTER SUBSCRIPTION ... DISABLE, + for e.g.: + +node2=# ALTER SUBSCRIPTION sub1_node1_node2 DISABLE; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node1_node2 DISABLE; +ALTER SUBSCRIPTION + + + + + + Upgrade the node node1's server to the required + newer version, for e.g.: + +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" + + + + + + Start the upgraded node node1's server, for e.g.: + +dba@node1:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/data1_upgraded start -l logfile + + + + + + Wait till all the incremental changes are synchronized. + + + + + + Create any tables that were created in node2 + between step-2 and now, for e.g.: + +node2=# CREATE TABLE distributors ( +node2(# did integer CONSTRAINT no_null NOT NULL, +node2(# name varchar(40) NOT NULL +node2(# ); +CREATE TABLE + + + + + + + Enable all the subscriptions on node2 that are + subscribing the changes from node1 by using + ALTER SUBSCRIPTION ... ENABLE, + for e.g.: + +node2=# ALTER SUBSCRIPTION sub1_node1_node2 ENABLE; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node1_node2 ENABLE; +ALTER SUBSCRIPTION + + + + + + + Refresh the publications using + ALTER SUBSCRIPTION ... REFRESH PUBLICATION, + for e.g.: + +node2=# ALTER SUBSCRIPTION sub1_node1_node2 REFRESH PUBLICATION; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node1_node2 REFRESH PUBLICATION; +ALTER SUBSCRIPTION + + + + + + Stop the server in node2, for e.g.: + +dba@node2:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/data2 stop -l logfile + + + + + + Disable all the subscriptions on node1 that are + subscribing the changes from node2 by using + ALTER SUBSCRIPTION ... DISABLE, + for e.g.: + +node2=# ALTER SUBSCRIPTION sub1_node2_node1 DISABLE; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node2_node1 DISABLE; +ALTER SUBSCRIPTION + + + + + + Upgrade the node node2's server to the required + new version, for e.g.: + +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" + + + + + + Start the upgraded node node2's server, for e.g.: + +dba@node2:/opt/PostgreSQL/postgres/&majorversion;/bin$ pg_ctl -D /opt/PostgreSQL/data2_upgraded start -l logfile + + + + + + + Create any tables that were created in the upgraded node + node1 between step-10 and now, for e.g.: + +node2=# CREATE TABLE distributors ( +node2(# did integer CONSTRAINT no_null NOT NULL, +node2(# name varchar(40) NOT NULL +node2(# ); +CREATE TABLE + + + + + + + Enable all the subscriptions on node1 that are + subscribing the changes from node2 by using + ALTER SUBSCRIPTION ... ENABLE, + for e.g.: + +node2=# ALTER SUBSCRIPTION sub1_node2_node1 ENABLE; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node2_node1 ENABLE; +ALTER SUBSCRIPTION + + + + + + + Refresh the publications using + ALTER SUBSCRIPTION ... REFRESH PUBLICATION + for e.g.: + +node2=# ALTER SUBSCRIPTION sub1_node1_node2 REFRESH PUBLICATION; +ALTER SUBSCRIPTION +node2=# ALTER SUBSCRIPTION sub2_node1_node2 REFRESH PUBLICATION; +ALTER SUBSCRIPTION + + + + + + + + + + + Stop both servers -- 2.34.1