Upgrading VMware Postgres

This topic describes how to upgrade VMware Postgres from a major or a minor version.

If you are upgrading from a previous major release (10.x, 11.x or 12.x), follow the steps in Upgrading from an Older Major Version.

If you are upgrading from an older minor release (for example 13.2 to 13.4), follow the steps in Upgrading from an Older Minor Version.

Upgrading from an Older Major Version

VMware Postgres 13.4 supports the ability to upgrade from prior VMware Postgres major versions to 13.4. The steps rely on the open source Postgres pg_upgrade functionality.

Existing Patroni customers that wish to move to 13.4 (and later) must follow the instructions in Migrating from Patroni High Availability to pg_auto_failover.

Important: Customers using the PostGIS extension cannot upgrade to 13.4.

Prerequisites

  • Download the VMware Postgres Server RPM distribution from VMware Tanzu Network.
  • Any extensions installed on the older Postgres server must be manually added to the new release. Alternatively, remove them from the older Postgres cluster before starting the upgrade.
  • Confirm you have enough disk space to run pg_upgrade. The default setting copies all data files from the old to the new server. Alternatively, review the --link option, that provides reduced upgrade time and disk space benefits but impacts the revert process, see Reverting to old cluster. For a list of all the pg_upgrade options see Options in the pg_upgrade Open Source Postgres documentation.

Procedure

  1. Start from step 3 in the Usage topic of the pg_upgrade Open Source Postgres documentation.

    Replace the commands in step 3, Install the new PostgreSQL binaries, with the following command that installs the new VMware Postgres binaries:

    $ cd ~/Downloads
    $ sudo yum install vmware-postgres13-13.4.0.el7.x86_64.rpm
    
  2. Follow the remaining steps as outlined in pg_upgrade.

Upgrading from an Older Minor Version

VMware Postgres 13.4 introduces some RPM packaging changes that impact upgrades from previous minor versions.

The installation files location has changed from /usr to /opt/vmware/postgres/13, and the names of the installed packages have changed from vmware-postgres to vmware-postgres<version>. Follow these steps to upgrade from a previous 13.x release:

  1. Install the new RPM:

    $ cd ~/Downloads/vmware-postgres-13
    $ sudo yum install ./vmware-postgres13-13.4-0.el7.x86_64.rpm
    
  2. Update any absolute paths to the Postgres executables that reference the old installation path of /usr. These files might be Postgres server configuration files, or any custom scripts you may have written. For example, if you have an archive_cleanup_command set up in postgresql.conf with an absolute path:

    archive_cleanup_command = '/usr/bin/pg_archivecleanup ... %r'
    

    then remove the absolute path or update it to the new location:

    archive_cleanup_command = 'pg_archivecleanup ... %r'
    

    or

    archive_cleanup_command = '/opt/vmware/postgres/<postgres_version>/bin/pg_archivecleanup ... %r'
    
  3. When ready to upgrade, update the Postgres user’s PATH to point to the new installation. For Postgres 13, in the ~/postgres/.bash_profile add the following line:

    export PATH=/opt/vmware/postgres/13/bin:$PATH
    

    Verify that it has taken effect:

    $ su --login postgres
    $ which pg_ctl
    /opt/vmware/postgres/13/bin/pg_ctl
    
  4. Switch to the new installation by stopping and starting the server. Do not use the restart shortcut, because it will reuse the old installation:

    $ su --login postgres
    $ pg_ctl stop -l data/logfile
    $ pg_ctl start -l data/logfile
    

    Verify that the correct versions are in use, both on the client machine and the server:

    $ su --login postgres
    $ psql
    psql (13.4 (VMware Postgres 13.4.0))
    Type "help" for help.
    
    postgres=# show server_version;
              server_version         
    ---------------------------------
     13.4 (VMware Postgres 13.4.0) 
    (1 row)
    
  5. Confirm the new server is working correctly, and remove the old server package:

    $ sudo yum remove vmware-postgres