begriffs open source - ai-pg/blob - full-docs/txt/logical-replication-upgrade.txt

   1
   2 29.13. Upgrade #
   3
   4    29.13.1. Prepare for Publisher Upgrades
   5    29.13.2. Prepare for Subscriber Upgrades
   6    29.13.3. Upgrading Logical Replication Clusters
   7
   8    Migration of logical replication clusters is possible only when all the
   9    members of the old logical replication clusters are version 17.0 or
  10    later.
  11
  12 29.13.1. Prepare for Publisher Upgrades #
  13
  14    pg_upgrade attempts to migrate logical slots. This helps avoid the need
  15    for manually defining the same logical slots on the new publisher.
  16    Migration of logical slots is only supported when the old cluster is
  17    version 17.0 or later. Logical slots on clusters before version 17.0
  18    will silently be ignored.
  19
  20    Before you start upgrading the publisher cluster, ensure that the
  21    subscription is temporarily disabled, by executing ALTER SUBSCRIPTION
  22    ... DISABLE. Re-enable the subscription after the upgrade.
  23
  24    There are some prerequisites for pg_upgrade to be able to upgrade the
  25    logical slots. If these are not met an error will be reported.
  26      * The new cluster must have wal_level as logical.
  27      * The new cluster must have max_replication_slots configured to a
  28        value greater than or equal to the number of slots present in the
  29        old cluster.
  30      * The output plugins referenced by the slots on the old cluster must
  31        be installed in the new PostgreSQL executable directory.
  32      * The old cluster has replicated all the transactions and logical
  33        decoding messages to subscribers.
  34      * All slots on the old cluster must be usable, i.e., there are no
  35        slots whose pg_replication_slots.conflicting is not true.
  36      * The new cluster must not have permanent logical slots, i.e., there
  37        must be no slots where pg_replication_slots.temporary is false.
  38
  39 29.13.2. Prepare for Subscriber Upgrades #
  40
  41    Setup the subscriber configurations in the new subscriber. pg_upgrade
  42    attempts to migrate subscription dependencies which includes the
  43    subscription's table information present in pg_subscription_rel system
  44    catalog and also the subscription's replication origin. This allows
  45    logical replication on the new subscriber to continue from where the
  46    old subscriber was up to. Migration of subscription dependencies is
  47    only supported when the old cluster is version 17.0 or later.
  48    Subscription dependencies on clusters before version 17.0 will silently
  49    be ignored.
  50
  51    There are some prerequisites for pg_upgrade to be able to upgrade the
  52    subscriptions. If these are not met an error will be reported.
  53      * All the subscription tables in the old subscriber should be in
  54        state i (initialize) or r (ready). This can be verified by checking
  55        pg_subscription_rel.srsubstate.
  56      * The replication origin entry corresponding to each of the
  57        subscriptions should exist in the old cluster. This can be found by
  58        checking pg_subscription and pg_replication_origin system tables.
  59      * The new cluster must have max_active_replication_origins configured
  60        to a value greater than or equal to the number of subscriptions
  61        present in the old cluster.
  62
  63 29.13.3. Upgrading Logical Replication Clusters #
  64
  65    While upgrading a subscriber, write operations can be performed in the
  66    publisher. These changes will be replicated to the subscriber once the
  67    subscriber upgrade is completed.
  68
  69 Note
  70
  71    The logical replication restrictions apply to logical replication
  72    cluster upgrades also. See Section 29.8 for details.
  73
  74    The prerequisites of publisher upgrade apply to logical replication
  75    cluster upgrades also. See Section 29.13.1 for details.
  76
  77    The prerequisites of subscriber upgrade apply to logical replication
  78    cluster upgrades also. See Section 29.13.2 for details.
  79
  80 Warning
  81
  82    Upgrading logical replication cluster requires multiple steps to be
  83    performed on various nodes. Because not all operations are
  84    transactional, the user is advised to take backups as described in
  85    Section 25.3.2.
  86
  87    The steps to upgrade the following logical replication clusters are
  88    detailed below:
  89      * Follow the steps specified in Section 29.13.3.1 to upgrade a
  90        two-node logical replication cluster.
  91      * Follow the steps specified in Section 29.13.3.2 to upgrade a
  92        cascaded logical replication cluster.
  93      * Follow the steps specified in Section 29.13.3.3 to upgrade a
  94        two-node circular logical replication cluster.
  95
  96 29.13.3.1. Steps to Upgrade a Two-node Logical Replication Cluster #
  97
  98    Let's say publisher is in node1 and subscriber is in node2. The
  99    subscriber node2 has a subscription sub1_node1_node2 which is
 100    subscribing the changes from node1.
 101     1. Disable all the subscriptions on node2 that are subscribing the
 102        changes from node1 by using ALTER SUBSCRIPTION ... DISABLE, e.g.:
 103 /* node2 # */ ALTER SUBSCRIPTION sub1_node1_node2 DISABLE;
 104
 105     2. Stop the publisher server in node1, e.g.:
 106 pg_ctl -D /opt/PostgreSQL/data1 stop
 107
 108     3. Initialize data1_upgraded instance by using the required newer
 109        version.
 110     4. Upgrade the publisher node1's server to the required newer version,
 111        e.g.:
 112 pg_upgrade
 113         --old-datadir "/opt/PostgreSQL/postgres/17/data1"
 114         --new-datadir "/opt/PostgreSQL/postgres/18/data1_upgraded"
 115         --old-bindir "/opt/PostgreSQL/postgres/17/bin"
 116         --new-bindir "/opt/PostgreSQL/postgres/18/bin"
 117
 118     5. Start the upgraded publisher server in node1, e.g.:
 119 pg_ctl -D /opt/PostgreSQL/data1_upgraded start -l logfile
 120
 121     6. Stop the subscriber server in node2, e.g.:
 122 pg_ctl -D /opt/PostgreSQL/data2 stop
 123
 124     7. Initialize data2_upgraded instance by using the required newer
 125        version.
 126     8. Upgrade the subscriber node2's server to the required new version,
 127        e.g.:
 128 pg_upgrade
 129        --old-datadir "/opt/PostgreSQL/postgres/17/data2"
 130        --new-datadir "/opt/PostgreSQL/postgres/18/data2_upgraded"
 131        --old-bindir "/opt/PostgreSQL/postgres/17/bin"
 132        --new-bindir "/opt/PostgreSQL/postgres/18/bin"
 133
 134     9. Start the upgraded subscriber server in node2, e.g.:
 135 pg_ctl -D /opt/PostgreSQL/data2_upgraded start -l logfile
 136
 137    10. On node2, create any tables that were created in the upgraded
 138        publisher node1 server between Step 1 and now, e.g.:
 139 /* node2 # */ CREATE TABLE distributors (did integer PRIMARY KEY, name varchar(4
 140 0));
 141
 142    11. Enable all the subscriptions on node2 that are subscribing the
 143        changes from node1 by using ALTER SUBSCRIPTION ... ENABLE, e.g.:
 144 /* node2 # */ ALTER SUBSCRIPTION sub1_node1_node2 ENABLE;
 145
 146    12. Refresh the node2 subscription's publications using ALTER
 147        SUBSCRIPTION ... REFRESH PUBLICATION, e.g.:
 148 /* node2 # */ ALTER SUBSCRIPTION sub1_node1_node2 REFRESH PUBLICATION;
 149
 150 Note
 151
 152    In the steps described above, the publisher is upgraded first, followed
 153    by the subscriber. Alternatively, the user can use similar steps to
 154    upgrade the subscriber first, followed by the publisher.
 155
 156 29.13.3.2. Steps to Upgrade a Cascaded Logical Replication Cluster #
 157
 158    Let's say we have a cascaded logical replication setup
 159    node1->node2->node3. Here node2 is subscribing the changes from node1
 160    and node3 is subscribing the changes from node2. The node2 has a
 161    subscription sub1_node1_node2 which is subscribing the changes from
 162    node1. The node3 has a subscription sub1_node2_node3 which is
 163    subscribing the changes from node2.
 164     1. Disable all the subscriptions on node2 that are subscribing the
 165        changes from node1 by using ALTER SUBSCRIPTION ... DISABLE, e.g.:
 166 /* node2 # */ ALTER SUBSCRIPTION sub1_node1_node2 DISABLE;
 167
 168     2. Stop the server in node1, e.g.:
 169 pg_ctl -D /opt/PostgreSQL/data1 stop
 170
 171     3. Initialize data1_upgraded instance by using the required newer
 172        version.
 173     4. Upgrade the node1's server to the required newer version, e.g.:
 174 pg_upgrade
 175         --old-datadir "/opt/PostgreSQL/postgres/17/data1"
 176         --new-datadir "/opt/PostgreSQL/postgres/18/data1_upgraded"
 177         --old-bindir "/opt/PostgreSQL/postgres/17/bin"
 178         --new-bindir "/opt/PostgreSQL/postgres/18/bin"
 179
 180     5. Start the upgraded server in node1, e.g.:
 181 pg_ctl -D /opt/PostgreSQL/data1_upgraded start -l logfile
 182
 183     6. Disable all the subscriptions on node3 that are subscribing the
 184        changes from node2 by using ALTER SUBSCRIPTION ... DISABLE, e.g.:
 185 /* node3 # */ ALTER SUBSCRIPTION sub1_node2_node3 DISABLE;
 186
 187     7. Stop the server in node2, e.g.:
 188 pg_ctl -D /opt/PostgreSQL/data2 stop
 189
 190     8. Initialize data2_upgraded instance by using the required newer
 191        version.
 192     9. Upgrade the node2's server to the required new version, e.g.:
 193 pg_upgrade
 194         --old-datadir "/opt/PostgreSQL/postgres/17/data2"
 195         --new-datadir "/opt/PostgreSQL/postgres/18/data2_upgraded"
 196         --old-bindir "/opt/PostgreSQL/postgres/17/bin"
 197         --new-bindir "/opt/PostgreSQL/postgres/18/bin"
 198
 199    10. Start the upgraded server in node2, e.g.:
 200 pg_ctl -D /opt/PostgreSQL/data2_upgraded start -l logfile
 201
 202    11. On node2, create any tables that were created in the upgraded
 203        publisher node1 server between Step 1 and now, e.g.:
 204 /* node2 # */ CREATE TABLE distributors (did integer PRIMARY KEY, name varchar(4
 205 0));
 206
 207    12. Enable all the subscriptions on node2 that are subscribing the
 208        changes from node1 by using ALTER SUBSCRIPTION ... ENABLE, e.g.:
 209 /* node2 # */ ALTER SUBSCRIPTION sub1_node1_node2 ENABLE;
 210
 211    13. Refresh the node2 subscription's publications using ALTER
 212        SUBSCRIPTION ... REFRESH PUBLICATION, e.g.:
 213 /* node2 # */ ALTER SUBSCRIPTION sub1_node1_node2 REFRESH PUBLICATION;
 214
 215    14. Stop the server in node3, e.g.:
 216 pg_ctl -D /opt/PostgreSQL/data3 stop
 217
 218    15. Initialize data3_upgraded instance by using the required newer
 219        version.
 220    16. Upgrade the node3's server to the required new version, e.g.:
 221 pg_upgrade
 222         --old-datadir "/opt/PostgreSQL/postgres/17/data3"
 223         --new-datadir "/opt/PostgreSQL/postgres/18/data3_upgraded"
 224         --old-bindir "/opt/PostgreSQL/postgres/17/bin"
 225         --new-bindir "/opt/PostgreSQL/postgres/18/bin"
 226
 227    17. Start the upgraded server in node3, e.g.:
 228 pg_ctl -D /opt/PostgreSQL/data3_upgraded start -l logfile
 229
 230    18. On node3, create any tables that were created in the upgraded node2
 231        between Step 6 and now, e.g.:
 232 /* node3 # */ CREATE TABLE distributors (did integer PRIMARY KEY, name varchar(4
 233 0));
 234
 235    19. Enable all the subscriptions on node3 that are subscribing the
 236        changes from node2 by using ALTER SUBSCRIPTION ... ENABLE, e.g.:
 237 /* node3 # */ ALTER SUBSCRIPTION sub1_node2_node3 ENABLE;
 238
 239    20. Refresh the node3 subscription's publications using ALTER
 240        SUBSCRIPTION ... REFRESH PUBLICATION, e.g.:
 241 /* node3 # */ ALTER SUBSCRIPTION sub1_node2_node3 REFRESH PUBLICATION;
 242
 243 29.13.3.3. Steps to Upgrade a Two-node Circular Logical Replication Cluster #
 244
 245    Let's say we have a circular logical replication setup node1->node2 and
 246    node2->node1. Here node2 is subscribing the changes from node1 and
 247    node1 is subscribing the changes from node2. The node1 has a
 248    subscription sub1_node2_node1 which is subscribing the changes from
 249    node2. The node2 has a subscription sub1_node1_node2 which is
 250    subscribing the changes from node1.
 251     1. Disable all the subscriptions on node2 that are subscribing the
 252        changes from node1 by using ALTER SUBSCRIPTION ... DISABLE, e.g.:
 253 /* node2 # */ ALTER SUBSCRIPTION sub1_node1_node2 DISABLE;
 254
 255     2. Stop the server in node1, e.g.:
 256 pg_ctl -D /opt/PostgreSQL/data1 stop
 257
 258     3. Initialize data1_upgraded instance by using the required newer
 259        version.
 260     4. Upgrade the node1's server to the required newer version, e.g.:
 261 pg_upgrade
 262         --old-datadir "/opt/PostgreSQL/postgres/17/data1"
 263         --new-datadir "/opt/PostgreSQL/postgres/18/data1_upgraded"
 264         --old-bindir "/opt/PostgreSQL/postgres/17/bin"
 265         --new-bindir "/opt/PostgreSQL/postgres/18/bin"
 266
 267     5. Start the upgraded server in node1, e.g.:
 268 pg_ctl -D /opt/PostgreSQL/data1_upgraded start -l logfile
 269
 270     6. Enable all the subscriptions on node2 that are subscribing the
 271        changes from node1 by using ALTER SUBSCRIPTION ... ENABLE, e.g.:
 272 /* node2 # */ ALTER SUBSCRIPTION sub1_node1_node2 ENABLE;
 273
 274     7. On node1, create any tables that were created in node2 between Step
 275        1 and now, e.g.:
 276 /* node1 # */ CREATE TABLE distributors (did integer PRIMARY KEY, name varchar(4
 277 0));
 278
 279     8. Refresh the node1 subscription's publications to copy initial table
 280        data from node2 using ALTER SUBSCRIPTION ... REFRESH PUBLICATION,
 281        e.g.:
 282 /* node1 # */ ALTER SUBSCRIPTION sub1_node2_node1 REFRESH PUBLICATION;
 283
 284     9. Disable all the subscriptions on node1 that are subscribing the
 285        changes from node2 by using ALTER SUBSCRIPTION ... DISABLE, e.g.:
 286 /* node1 # */ ALTER SUBSCRIPTION sub1_node2_node1 DISABLE;
 287
 288    10. Stop the server in node2, e.g.:
 289 pg_ctl -D /opt/PostgreSQL/data2 stop
 290
 291    11. Initialize data2_upgraded instance by using the required newer
 292        version.
 293    12. Upgrade the node2's server to the required new version, e.g.:
 294 pg_upgrade
 295         --old-datadir "/opt/PostgreSQL/postgres/17/data2"
 296         --new-datadir "/opt/PostgreSQL/postgres/18/data2_upgraded"
 297         --old-bindir "/opt/PostgreSQL/postgres/17/bin"
 298         --new-bindir "/opt/PostgreSQL/postgres/18/bin"
 299
 300    13. Start the upgraded server in node2, e.g.:
 301 pg_ctl -D /opt/PostgreSQL/data2_upgraded start -l logfile
 302
 303    14. Enable all the subscriptions on node1 that are subscribing the
 304        changes from node2 by using ALTER SUBSCRIPTION ... ENABLE, e.g.:
 305 /* node1 # */ ALTER SUBSCRIPTION sub1_node2_node1 ENABLE;
 306
 307    15. On node2, create any tables that were created in the upgraded node1
 308        between Step 9 and now, e.g.:
 309 /* node2 # */ CREATE TABLE distributors (did integer PRIMARY KEY, name varchar(4
 310 0));
 311
 312    16. Refresh the node2 subscription's publications to copy initial table
 313        data from node1 using ALTER SUBSCRIPTION ... REFRESH PUBLICATION,
 314        e.g.:
 315 /* node2 # */ ALTER SUBSCRIPTION sub1_node1_node2 REFRESH PUBLICATION;