In-place Postgres major version upgrades v5

You can upgrade a PGD node to a newer major version of Postgres using the command-line utility bdr_pg_upgrade.

bdr_pg_upgrade internally uses the standard pg_upgrade with PGD-specific logic to ensure a smooth upgrade.


This terminology is used when describing the upgrade process and components involved:

Old cluster The existing Postgres cluster node to upgrade, the one from which to migrate data.

New cluster The new Postgres cluster that data is migrated to. This cluster node must be one major version ahead of the old cluster.


Standard Postgres major version upgrade precautions apply, including the fact both clusters must meet all the requirements for pg_upgrade.

Additionally, don't use bdr_pg_upgrade if other tools are using replication slots and replication origins. Only PGD slots and origins are restored after the upgrade.

You must meet several prerequisites for bdr_pg_upgrade:

  • Disconnect applications using the old cluster. You can, for example, redirect them to another node in the cluster.
  • Configure peer authentication for both clusters. bdr_pg_upgrade requires peer authentication.
  • PGD versions on both clusters must be exactly the same and must be version 4.1.0 or later.
  • The new cluster must be in a shutdown state.
  • You must install PGD packages in the new cluster.
  • The new cluster must be already initialized and configured as needed to match the old cluster configuration.
  • Databases, tables, and other objects must not exist in the new cluster.

We also recommend having the old cluster up prior to running bdr_pg_upgrade. The CLI starts the old cluster if it's shut down.


To upgrade to a newer major version of Postgres, you must first install the new version.

bdr_pg_upgrade command-line

bdr_pg_upgrade passes all parameters to pg_upgrade. Therefore, you can specify any parameters supported by pg_upgrade.


bdr_pg_upgrade [OPTION] ...


In addition to the options for pg_upgrade, you can pass the following parameters to bdr_pg_upgrade:

Required parameters

Specify these parameters either in the command line or, for all but the --database parameter, in their equivalent environment variable. They're used by bdr_pg_upgrade.

  • -b, --old-bindir Old cluster bin directory.
  • -B, --new-bindir New cluster bin directory.
  • -d, --old-datadir Old cluster data directory.
  • -D, --new-datadir New cluster data directory.
  • --database PGD database name.

Optional parameters

These parameters are optional and are used by bdr_pg_upgrade.

  • -p, --old-port Old cluster port number.
  • -s, --socketdir Directory to use for postmaster sockets during upgrade.
  • --check Specify to only perform checks and not modify clusters.

Other parameters

Any other parameter that's not one of the above is passed to pg_upgrade. pg_upgrade accepts the following parameters:

  • -j, --jobs Number of simultaneous processes or threads to use.
  • -k, --link Use hard links instead of copying files to the new cluster.
  • -o, --old-options Option to pass to old postgres command. Multiple invocations are appended.
  • -O, --new-options Option to pass to new postgres command. Multiple invocations are appended.
  • -N, --no-sync Don't wait for all files in the upgraded cluster to be written to disk.
  • -P, --new-port New cluster port number.
  • -r, --retain Retain SQL and log files even after successful completion.
  • -U, --username Cluster's install user name.
  • --clone Use efficient file cloning.

Environment variables

You can use these environment variables in place of command line parameters:

  • PGBINOLD Old cluster bin directory.
  • PGBINNEW New cluster bin directory.
  • PGDATAOLD Old cluster data directory.
  • PGDATANEW New cluster data directory.
  • PGPORTOLD Old cluster port number.
  • PGSOCKETDIR Directory to use for postmaster sockets during upgrade.


Given a scenario where:

  • Old cluster bin directory is /usr/lib/postgresql/13/bin.
  • New cluster bin directory is /usr/lib/postgresql/14/bin.
  • Old cluster data directory is /var/lib/postgresql/13/main.
  • New cluster data directory is /var/lib/postgresql/14/main.
  • Database name is bdrdb.

You can use the following command to upgrade the cluster:

bdr_pg_upgrade \
--old-bindir /usr/lib/postgresql/13/bin \
--new-bindir /usr/lib/postgresql/14/bin \
--old-datadir /var/lib/postgresql/13/main \
--new-datadir /var/lib/postgresql/14/main \
--database bdrdb

Steps performed

These steps are performed when running bdr_pg_upgrade.


When --check is supplied as an argument to bdr_pg_upgrade, the CLI skips steps that modify the database.

PGD Postgres checks

Steps--check supplied
Collecting pre-upgrade new cluster control datarun
Checking new cluster state is shutdownrun
Checking PGD versionsrun
Starting old cluster (if shutdown)skip
Connecting to old clusterskip
Checking if bdr schema existsskip
Turning DDL replication offskip
Terminating connections to database.skip
Disabling connections to databaseskip
Waiting for all slots to be flushedskip
Disconnecting from old clusterskip
Stopping old clusterskip
Starting old cluster with PGD disabledskip
Connecting to old clusterskip
Collecting replication originsskip
Collecting replication slotsskip
Disconnecting from old clusterskip
Stopping old clusterskip

pg_upgrade steps

Standard pg_upgrade steps are performed.


If supplied, --check is passed to pg_upgrade.

PGD post-upgrade steps

Steps--check supplied
Collecting old cluster control dataskip
Collecting new cluster control dataskip
Advancing LSN of new clusterskip
Starting new cluster with PGD disabledskip
Connecting to new clusterskip
Creating replication origin, repeated for each originskip
Advancing replication origin, repeated for each originskip
Creating replication slot, repeated for each slotskip
Stopping new clusterskip