Synopsis
The pgd node upgrade command is used to upgrade the Postgres version on a node in the EDB Postgres Distributed cluster.
Note
Starting from PGD 6.4, pgd node setup advances the NextOID counter before creating BDR objects in single-user mode, preventing those objects from receiving system-range OIDs (< 16384) that would cause upgrade failures. Before performing the upgrade, the command checks whether existing BDR objects were created with system-range OIDs. If detected, the command fails immediately with a clear error identifying the affected objects. See Resolving system-range OID errors for steps to recover.
Syntax
pgd node <NODE_NAME> upgrade [OPTIONS] --old-bindir <OLD_BINDIR> --new-bindir <NEW_BINDIR> --old-datadir <OLD_DATADIR> --new-datadir <NEW_DATADIR> --database <DATABASE> --username <USER_NAME>
Where <NODE_NAME> is the name of the node which you want to upgrade and <OLD_BINDIR>, <NEW_BINDIR>, <OLD_DATADIR>, <NEW_DATADIR>, <DATABASE>, and <USER_NAME> are the old and new Postgres instance bin directories, old and new Postgres instance data directories, database name, and cluster's install user name respectively.
Options
The following table lists the options available for the pgd node upgrade command:
| Short | Long | Default | Env | Description |
|---|---|---|---|---|
| -b | --old-bindir | PGBINOLD | Old Postgres instance bin directory | |
| -B | --new-bindir | PGBINNEW | New Postgres instance bin directory | |
| -d | --old-datadir | PGDATAOLD | Old Postgres instance data directory | |
| -D | --new-datadir | PGDATANEW | New Postgres instance data directory | |
| --database | PGDATABASE | PGD database name | ||
| -p | --old-port | 5432 | PGPORTOLD | Old Postgres instance port |
| --socketdir | /var/run/postgresql | PGSOCKETDIR | Directory to use for postmaster sockets during upgrade | |
| --new-socketdir | /var/run/postgresql | PGSOCKETDIRNEW | Directory to use for postmaster sockets in the new cluster | |
| --check | Specify to only perform checks and not modify clusters | |||
| -j | --jobs | 1 | Number of simultaneous processes or threads to use | |
| -k | --link | Use hard links instead of copying files to the new cluster | ||
| --old-options | Option to pass to old postgres command, multiple invocations are appended | |||
| --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 | 5432 | PGPORTNEW | New Postgres instance port number |
| -r | --retain | Retain SQL and log files even after successful completion | ||
| -U | --username | PGUSER | Cluster's install user name | |
| --clone | Use efficient file cloning | |||
| --copy-by-block | Used to migrate data between clusters with different encryption settings. This option is supported for databases that use Transparent Data Encryption (TDE) | |||
| --key-unwrap-command | PGDATAKEYUNWRAPCMD | Command to unwrap (decrypt) the data encryption key and access the files to copy. The command must be the same specified during the server initialization using pgd node setup |
See also Global Options.
Resolving system-range OID errors
If the command fails with a system-range OID error, the cluster was set up with a version of pgd node setup earlier than 6.4 that didn't advance the NextOID counter before creating BDR objects in single-user mode. The affected objects can't be reassigned new OIDs in place.
To resolve the error, part the node, drop and recreate the BDR extension in a standard psql session (not single-user mode), then rejoin the cluster without synchronizing structure to preserve existing data.
Part the node from the cluster:
pgd node <node-name> part
In a psql session connected to the BDR database, drop the extension:
DROP EXTENSION bdr CASCADE;
In a standard psql session (not single-user mode), recreate the extension:
CREATE EXTENSION bdr;
Use
bdr.create_node()andbdr.join_node_group()to recreate the node and rejoin the group, withsynchronize_structureset to'none'.Run
pgd node upgradeagain.
Examples
In the following examples, "kaolin" is the name of the node to upgrade, from the Quickstart democluster.
Upgrade the Postgres version on a node
pgd node kaolin upgrade --old-bindir /usr/pgsql-16/bin --new-bindir /usr/pgsql-17/bin --old-datadir /var/lib/pgsql/16/data --new-datadir /var/lib/pgsql/17/data --database pgddb --username enterprisedb
Upgrade the Postgres version on a node with hard links
pgd node kaolin upgrade --old-bindir /usr/pgsql-16/bin --new-bindir /usr/pgsql-17/bin --old-datadir /var/lib/pgsql/16/data --new-datadir /var/lib/pgsql/17/data --database pgddb --username enterprisedb --link
Upgrade the Postgres version on a node with efficient file cloning
pgd node kaolin upgrade --old-bindir /usr/pgsql-16/bin --new-bindir /usr/pgsql-17/bin --old-datadir /var/lib/pgsql/16/data --new-datadir /var/lib/pgsql/17/data --database pgddb --username enterprisedb --clone
Upgrade the Postgres version on a node with a different port number
pgd node kaolin upgrade --old-bindir /usr/pgsql-16/bin --new-bindir /usr/pgsql-17/bin --old-datadir /var/lib/pgsql/16/data --new-datadir /var/lib/pgsql/17/data --database pgddb --username enterprisedb --old-port 5433 --new-port 5434
Upgrade the Postgres Extended version on a node with Transparent Data Encryption (TDE)
pgd node kaolin upgrade --database pgddb -B /usr/lib/edb-pge/16/bin --socketdir /var/run/edb-pge/ --old-bindir /usr/lib/edb-pge/15/bin --old-datadir /var/lib/edb-pge/15/main --new-datadir /var/lib/edb-pge/16/main --username postgres --key-unwrap-command "openssl enc -d -aes-128-cbc -pbkdf2 -pass pass:secret -in %p" --copy-by-block