Upgrade to AlloyDB Omni version 16.3.0 on a VM

This page describes how to upgrade your AlloyDB Omni PostgreSQL 15-based containers to AlloyDB Omni PostgreSQL 16 using pg_upgrade. The instructions in this page describe upgrade steps for AlloyDB Omni deployed as a standalone server and for AlloyDB Omni configured as replicated standby nodes. Using pg_upgrade helps to ensure that the upgrade completes without data loss.

For more information about PostgreSQL upgrade options, see pg_upgrade.

Before you begin

  • Before you initiate the upgrade, we recommend that you take a full backup of your database cluster.

  • To ensure that the AlloyDB Omni 15 service is running, execute the following command:

    Docker

    docker exec ALLOYDB15_CONTAINER psql -U postgres -c "SELECT 1;"

    Podman

    podman exec ALLOYDB15_CONTAINER psql -U postgres -c "SELECT 1;"

  • The pg_squeeze extension in PostgreSQL 15 isn't supported in AlloyDB Omni PostgreSQL 16.3.0. If pg_squeeze is in your AlloyDB Omni 15 installation, you must remove the extension before you perform the upgrade to AlloyDB Omni 16.

    If you installed custom extensions on top of AlloyDB Omni, make sure that those custom extensions are also installed in the 16.3.0 image. Check the installed extensions by running the following command:

    Docker

    docker exec ALLOYDB15_CONTAINER psql -U postgres -d postgres -c "
SELECT * FROM pg_extension;"

    Podman

    podman exec ALLOYDB15_CONTAINER psql -U postgres -d postgres -c "
SELECT * FROM pg_extension;

  • If you're upgrading from AlloyDB Omni version 15.5.2 or earlier, you must first upgrade to a more recent version of AlloyDB Omni 15. Migrate from AlloyDB Omni version 15.5.2 and earlier to the latest version.

Upgrade AlloyDB Omni in a Docker container environment

To upgrade from AlloyDB Omni PostgreSQL 15 to AlloyDB Omni PostgreSQL 16.3.0 in a Docker or Podman container environment, follow these steps:

Docker

  1. Copy bin and share the directory from the version of the AlloyDB Omni container that you want to upgrade:

    mkdir -p TMP/alloydb15_bin TMP/alloydb15_share
docker cp ALLOYDB15_CONTAINER:/usr/lib/postgresql/15 TMP/alloydb15_bin
docker cp ALLOYDB15_CONTAINER:/usr/share/postgresql/15 TMP/alloydb15_share

  2. Create a new data directory for the AlloyDB Omni PostgreSQL 16 container where the upgraded data will be stored:

    mkdir -p DATA_PATH/16/data
chown 999 DATA_PATH/16/data

  3. Start the AlloyDB Omni PostgreSQL 16 running container with all the paths mounted in the same network as the previous AlloyDB Omni container. See the following example:

    docker run -d --name ALLOYDB16_CONTAINER \
  -e POSTGRES_PASSWORD=PASSWORD -e PGPORT=5433 \
  -v DATA_PATH/16/data:/var/lib/postgresql/data \
  -v DATA_PATH/15/data:/var/lib/postgresql/old_data \
  -v TMP/alloydb15_bin/15:/usr/lib/postgresql/15 \
  -v TMP/alloydb15_share/15:/usr/share/postgresql/15 \
  --network container:ALLOYDB15_CONTAINER \
  google/alloydbomni:16 /bin/sleep infinity

  4. Initialize the new data directory for the upgraded version of container.

    docker exec -u postgres ALLOYDB16_CONTAINER bash -c "
  cd /tmp;
  initdb -D /var/lib/postgresql/data --frozen-collations --encoding=UTF8 --locale=C --locale-provider=icu --icu-locale=und-x-icu

    If the old cluster had any special settings, for example, --data-checksum or --locale, then you must also pass those parameters to create the AlloyDB Omni 16 container.

  5. If you enabled the restart policy on the earlier version container, then you must disable the restart policy, as shown in the following example:

    docker update --restart=no ALLOYDB15_CONTAINER

  6. Run pg_upgrade --check to verify that the cluster is ready to be upgraded to AlloyDB Omni 16.

    docker exec -u postgres ALLOYDB16_CONTAINER bash -c "
 cd /tmp;

 pg_upgrade -p 5432 -P 5433 --check -v \
            -b /usr/lib/postgresql/15/bin \
            -B /usr/lib/postgresql/16/bin \
            -d /var/lib/postgresql/old_data \
            -D /var/lib/postgresql/data"

    After the pg_upgrade --check command completes, you see an output that ends with Clusters are compatible, which indicates that the cluster is ready to be upgraded. This command also checks and shuts down the AlloyDB Omni PostgreSQL 15 container. After pg_upgrade --check completes, applications are no longer able to connect to the database or execute any queries.

  7. Run pg_upgrade to copy the upgraded data onto the new data directory, and then verify that pg_upgrade completed successfully and that the AlloyDB Omni PostgreSQL 15 container exited:

    docker exec -u postgres ALLOYDB16_CONTAINER bash -c "
  cd /tmp;
  pg_upgrade -v --copy \
       -b /usr/lib/postgresql/15/bin \
       -B /usr/lib/postgresql/16/bin \
       -d /var/lib/postgresql/old_data \
       -D /var/lib/postgresql/data"

docker ps -a

  8. If pg_upgrade fails, roll back to the AlloyDB Omni PostgreSQL 15 container by starting the PostgreSQL 15 container:

    docker logs ALLOYDB16_CONTAINER
docker rm -f ALLOYDB15_CONTAINER ALLOYDB16_CONTAINER
docker run -d --name ALLOYDB15_CONTAINER -p 5432:5432 \
  -e POSTGRES_PASSWORD=postgres \
  -v DATA_PATH/15/data:/var/lib/postgresql/data \
  google/alloydbomni:15

    To determine the reasons for the upgrade failure, review the logs.

  9. If the upgrade is successful, clean up and then restart the AlloyDB Omni PostgreSQL 16 container:

    docker rm -f ALLOYDB16_CONTAINER ALLOYDB15_CONTAINER
docker run -d --name ALLOYDB16_CONTAINER -p 5432:5432 \
  -e POSTGRES_PASSWORD=postgres \
  -v DATA_PATH/16/data:/var/lib/postgresql/data \
  google/alloydbomni:16

Podman

  1. Copy bin and share the directory from the version of the AlloyDB Omni container that you want to upgrade:

    mkdir -p TMP/alloydb15_bin TMP/alloydb15_share
podman cp ALLOYDB15_CONTAINER:/usr/lib/postgresql/15 TMP/alloydb15_bin
podman cp ALLOYDB15_CONTAINER:/usr/share/postgresql/15 TMP/alloydb15_share

  2. Create a new data directory for the AlloyDB Omni PostgreSQL 16 container where the upgraded data will be stored:

    mkdir -p DATA_PATH/16/data
chown 999 DATA_PATH/16/data

  3. Start the AlloyDB Omni PostgreSQL 16 running container with all the paths mounted in the same network as the previous AlloyDB Omni container. See the following example:

    podman run -d --name ALLOYDB16_CONTAINER \
  -e POSTGRES_PASSWORD=PASSWORD -e PGPORT=5433 \
  -v DATA_PATH/16/data:/var/lib/postgresql/data \
  -v DATA_PATH/15/data:/var/lib/postgresql/old_data \
  -v TMP/alloydb15_bin/15:/usr/lib/postgresql/15 \
  -v TMP/alloydb15_share/15:/usr/share/postgresql/15 \
  --network container:ALLOYDB15_CONTAINER \
  google/alloydbomni:16 /bin/sleep infinity

  4. Initialize the new data directory for the upgraded version of container.

    podman exec -u postgres ALLOYDB16_CONTAINER bash -c "
  cd /tmp;
  initdb -D /var/lib/postgresql/data --frozen-collations --encoding=UTF8 --locale=C --locale-provider=icu --icu-locale=und-x-icu

    If the old cluster had any special settings, for example, --data-checksum or --locale, then you must also pass those parameters to create the AlloyDB Omni 16 container.

  5. If you enabled the restart policy on the earlier version container, then you must disable the restart policy, as shown in the following example:

    podman update --restart=no ALLOYDB15_CONTAINER

  6. Run pg_upgrade --check to verify that the cluster is ready to be upgraded to AlloyDB Omni 16.

    podman exec -u postgres ALLOYDB16_CONTAINER bash -c "
 cd /tmp;

 pg_upgrade -p 5432 -P 5433 --check -v \
            -b /usr/lib/postgresql/15/bin \
            -B /usr/lib/postgresql/16/bin \
            -d /var/lib/postgresql/old_data \
            -D /var/lib/postgresql/data"

    After the pg_upgrade --check command completes, you see an output that ends with Clusters are compatible, which indicates that the cluster is ready to be upgraded. This command also checks and shuts down the AlloyDB Omni PostgreSQL 15 container. After pg_upgrade --check completes, applications are no longer able to connect to the database or execute any queries.

  7. Run pg_upgrade to copy the upgraded data onto the new data directory, and then verify that pg_upgrade completed successfully and that the AlloyDB Omni PostgreSQL 15 container exited:

    podman exec -u postgres ALLOYDB16_CONTAINER bash -c "
  cd /tmp;
  pg_upgrade -v --copy \
       -b /usr/lib/postgresql/15/bin \
       -B /usr/lib/postgresql/16/bin \
       -d /var/lib/postgresql/old_data \
       -D /var/lib/postgresql/data"

podman ps -a

  8. If pg_upgrade fails, roll back to the AlloyDB Omni PostgreSQL 15 container by starting the PostgreSQL 15 container:

    podman logs ALLOYDB16_CONTAINER
podman rm -f ALLOYDB15_CONTAINER ALLOYDB16_CONTAINER
podman run -d --name ALLOYDB15_CONTAINER -p 5432:5432 \
  -e POSTGRES_PASSWORD=postgres \
  -v DATA_PATH/15/data:/var/lib/postgresql/data \
  google/alloydbomni:15

    To determine the reasons for the upgrade failure, review the logs.

  9. If the upgrade is successful, clean up and then restart the AlloyDB Omni PostgreSQL 16 container:

    podman rm -f ALLOYDB16_CONTAINER ALLOYDB15_CONTAINER
podman run -d --name ALLOYDB16_CONTAINER -p 5432:5432 \
  -e POSTGRES_PASSWORD=postgres \
  -v DATA_PATH/16/data:/var/lib/postgresql/data \
  google/alloydbomni:16

Upgrade the AlloyDB Omni server on standby node

If your AlloyDB Omni server is deployed with an active and streaming replicated standby configuration, then you can't run pg_upgrade on the standby node. To upgrade the AlloyDB Omni server on a standby node, we recommend that, before you upgrade AlloyDB Omni on the active node, you ensure that there are no replication lags on the standby node.

To upgrade the standby AlloyDB Omni server, you follow these high-level steps:

  1. Stop the standby AlloyDB Omni container before you upgrade Active node.
  2. After the active node is upgraded, sync the upgraded data directory from the new active node to the standby node using rsync. For more information about upgrading a streaming replicated standby server, see pg_upgrade.
  3. Start the container using the AlloyDB for PostgreSQL PostgreSQL 16 image using the same data directory.

If you're using logical replication, see Upgrading Data via Replication.