Performing a Postgres minor upgrade v6.5.0

Move to a newer minor version of Postgres, without changing your PGD version, using one of three approaches: full downtime, a rolling upgrade in place, or a rolling upgrade that replaces nodes. An in-place upgrade needs no new data directory or pg_upgrade, since a minor version upgrade doesn't change Postgres's on-disk format.

Upgrading with full downtime

Choose this approach when a maintenance window is acceptable and finishing quickly matters more than staying online. See Choosing between a rolling and full-downtime upgrade for the trade-offs against the two rolling approaches described below.

1. Stop Postgres on every node:

   → WrapCopy

   sudo systemctl stop postgres

   You can run this step one node at a time, but you must wait for each node to shut down cleanly before moving to the next. Monitor progress with sudo journalctl -u postgres -f.

2. Install the latest minor version of your Postgres packages on every node, for example:

   → WrapCopy

   sudo apt update
   sudo apt install --only-upgrade <postgres_package>

3. Start Postgres on every node:

   → WrapCopy

   systemctl start postgres

4. Confirm the new version took effect on every node:

   → WrapCopy

   psql -c "SHOW server_version;"

5. Check overall cluster health:

   → WrapCopy

   pgd nodes list

Upgrading with a rolling upgrade, in place

For each node, one at a time:

1. Fence the node, so it can't become the write leader until the upgrade is complete:

   → WrapCopy

   pgd node <node_name> set-option route_fence true

2. Stop Postgres:

   → WrapCopy

   sudo systemctl stop postgres

   Monitor progress with sudo journalctl -u postgres -f.

3. Install the latest minor version of your Postgres packages, for example:

   → WrapCopy

   sudo apt update
   sudo apt install --only-upgrade <postgres_package>

4. Start Postgres:

   → WrapCopy

   systemctl start postgres

5. Unfence the node, then confirm it's healthy before moving to the next one:

   → WrapCopy

   pgd node <node_name> set-option route_fence false

6. Confirm the new version took effect on the node:

   → WrapCopy

   psql -c "SHOW server_version;"

Upgrading with a rolling upgrade, by replacing nodes

Instead of upgrading a node in place, join a new node that already has the new Postgres minor version installed, then part and drop one of the existing nodes. Use this approach if you're also replacing hardware or a base image at the same time as the minor version bump.

1. Provision a new node with the new Postgres minor version installed, and the same PGD version as the rest of the cluster.

2. Join the new node to the cluster. Since the PGD version isn't changing, you can use either a logical join with pgd node setup:

   → WrapCopy

   pgd node <node_name> setup --dsn "<new_node_dsn>" --cluster-dsn "<existing_node_dsn>" -D <pg_data>

   or a physical join with bdr_init_physical, which is faster since it uses pg_basebackup instead of a full logical replication catch-up. bdr_init_physical is deprecated in favor of pgd node setup, but it remains usable here because its only version restriction is that the source and joining node run the same PGD version, which a Postgres-only upgrade doesn't change.

3. Wait for the new node to catch up with the cluster before routing traffic to it, then confirm it's healthy:

   → WrapCopy

   pgd nodes list

4. Update your application's connection configuration to include the new node once it's ready to take traffic.

5. Part one of the existing nodes, then decommission it:

   → WrapCopy

   pgd node <node_name> part

6. Repeat for each remaining node, one at a time, until the whole cluster is on the new Postgres version.