Upgrading to a new major version

Extensions and logical replication objects to review

Review the following items before the upgrade:

Extensions

• pg_repack
• old_snapshot
• wal2json
• anon
• PostGIS

Replication slots

• Logical replication slots

Application dependencies If you remove extensions or replication objects that your applications depend on, validate your data flows and application behavior before you proceed with the upgrade. Also consider the possible disruptions in your application logic that depends on specific PostgreSQL features.

pg_repack

Drop pg_repack before the upgrade and re-create it after the upgrade. pg_repack uses a version-specific extension and client/server components that must match the PostgreSQL major version.

DROP EXTENSION pg_repack;

Re-create the extension after the upgrade only if your workload still requires it.

CREATE EXTENSION pg_repack;

old_snapshot

Drop old_snapshot before the upgrade. Do not re-create it after upgrading to PostgreSQL 18 because it is no longer supported.

DROP EXTENSION old_snapshot;

wal2json replication slots

If you use wal2json for logical decoding, you must drop all associated replication slots before the upgrade. The pg_upgrade utility strictly forbids major version upgrades while replication slots exist and will throw a critical error and halt the upgrade.

Before upgrading:

1. Ensure all pending WAL data has been consumed.
2. Stop your application that uses the replication slot.
3. Drop the replication slot(s):

SELECT pg_drop_replication_slot('your_slot_name');

After the upgrade, you can recreate the replication slots as needed. Note that wal2json is not installed via CREATE EXTENSION but is configured through database parameters (wal_level, max_replication_slots, max_wal_senders) and table permissions, which do not prevent upgrades.

anon

Remove the anon extension before the upgrade and re-enable it after the upgrade if you still need it. Additional steps are required before you drop anon.

If the anon extension is installed, follow the steps below and execute the commands as the admin user before performing the upgrade.

1. Remove all masking rules (if enabled).

   SELECT anon.remove_masks_for_all_columns();
   

2. Disable masking roles (the upgrade might fail if any roles are marked as masked).

   SECURITY LABEL FOR anon ON ROLE <role_name> IS NULL;
   

3. Drop the anon extension with the cascade option.

   DROP EXTENSION anon CASCADE;
   

4. If the anon extension is installed in multiple databases within an instance, follow the outlined steps for each database.

5. After the upgrade is complete, re-enable the anon extension and reapply masking rules as required.

It is strongly recommended to validate the data both before and after dropping the extension to ensure masking consistency prior to performing the upgrade.

PostGIS

If you are using PostGIS, first upgrade PostGIS before you upgrade PostgreSQL.

SELECT postgis_extensions_upgrade();

Use the following query to validate the PostGIS extension upgrade.

SELECT postgis_full_version();

Logical replication slots

Drop all logical replication slots before the upgrade and re-create them after the upgrade. Logical slots are tied to the source server state and should be re-created cleanly on the upgraded instance.

SELECT pg_drop_replication_slot('<slot_name>');

Logical replication slots

Drop all logical replication slots before the upgrade, and re-create them afterward. Logical replication slots are tied to the source server state and must be re-created on the upgraded instance.

SELECT pg_drop_replication_slot('<slot_name>');

Before you begin

Review the following before you start the upgrade:

• Verify that version upgrades are supported for your deployment by using the UI, API, CLI, or Terraform.

  Example (CLI):

  ibmcloud cdb capability-show versions postgresql
  

• Review precheck requirements. The upgrade runs on the source deployment and is blocked if risks are detected. Ensure that:

  • The deployment is healthy
  • At least 10% free disk space is available
  • I/O utilization is below 90%
  • Schema size and object counts are within supported limits
  • Required extension and logical replication slot cleanup is complete

• Review the https://www.postgresql.org/docs/release/ for compatibility changes that might affect your applications.

• Downgrading to an earlier version is not supported.

• An in-place upgrade cannot be canceled after it starts.

• Ensure that a recent backup is available before you upgrade.

Gen2 starts with PostgreSQL 18. Upgrade paths to newer versions are added as they become supported. For earlier versions (14–17), see the /docs/databases-for-postgresql?topic=databases-for-postgresql-upgrading.

After the upgrade completes, your deployment runs a new PostgreSQL major version. Backups and PITR points from before the upgrade belong to the earlier version timeline and cannot be restored into the upgraded version.

To maintain restore and PITR capabilities for the new version, take a backup immediately after the upgrade. This backup becomes the baseline for future recovery operations.

If the upgrade fails, backups from before the upgrade can still be used with PITR to restore the earlier version into a new deployment.

Troubleshooting

If issues occur after a successful upgrade and you need to return to the previous version, contact IBM Cloud® support for guidance. Avoid performing PITR or restores without guidance, as this can complicate recovery.

Upgrades run only after all prechecks pass. If the upgrade is blocked, verify:

• Cluster health (Patroni state is stable)
• Sufficient free disk space
• Acceptable disk I/O utilization
• Schema size and object count limits

Large schemas and high object counts can increase upgrade duration.

If upgrade attempts continue to fail, open a support ticket through https://cloud.ibm.com/login?redirect=%2Funifiedsupport%2Fsupportcenter.

Dry running the promotion and upgrade

To evaluate the effects of major version upgrades, trigger a dry run. A dry run simulates the promotion and upgrade, with the results printed to the database logs. Access and view your database logs through the Log analysis integration. This ensures the version that you are currently running with its extensions can be successfully upgraded to your intended version.

The dry run must be run with skip_initial_backup set to false, and version defined.

The command looks like:

curl -X POST \
  https://api.{region}.databases.cloud.ibm.com/v5/ibm/deployments/{id}/remotes/promotion \
  -H 'Authorization: Bearer <>'  \
 -H 'Content-Type: application/json' \
 -d '{
    "promotion": {
        "version": "14",
        "skip_initial_backup": false,
        "dry_run": true
    }
}' \