pgd node upgrade

pgd node upgrade#

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.

  1. Part the node from the cluster:

pgd node <node-name> part

  1. In a psql session connected to the BDR database, drop the extension:

DROP EXTENSION bdr CASCADE;

  1. In a standard psql session (not single-user mode), recreate the extension:

CREATE EXTENSION bdr;

  1. Use bdr.create_node() and bdr.join_node_group() to recreate the node and rejoin the group, with synchronize_structure set to 'none' .

  2. Run pgd node upgrade again.

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 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
Contents