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 :ref:`Resolving system-range OID errors ` for steps to recover. Syntax ------ .. code:: plaintext pgd node upgrade [OPTIONS] --old-bindir --new-bindir --old-datadir --new-datadir --database --username Where ```` is the name of the node which you want to upgrade and ```` , ```` , ```` , ```` , ```` , and ```` 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: .. csv-table:: :header: Short,Long,Default,Env,Description :widths: 6,10,8,8,15 :align: left :class: longtable -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: .. code:: shell pgd node part 2. In a psql session connected to the BDR database, drop the extension: .. code:: sql DROP EXTENSION bdr CASCADE; 3. In a standard psql session (not single-user mode), recreate the extension: .. code:: sql CREATE EXTENSION bdr; 4. Use :ref:`bdr.create_node() ` and :ref:`bdr.join_node_group() ` to recreate the node and rejoin the group, with ``synchronize_structure`` set to ``'none'`` . 5. 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: shell 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: shell 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: shell 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: shell 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) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: shell 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