Application compatibility

Test your chosen upgrade path on a representative staging deployment before production. For an IPMVU rehearsal, restore a recent backup to the source PostgreSQL version, then upgrade it to your intended target. Check application queries, background jobs, drivers, extensions, and connection pools, and record performance for comparison afterward. Review the target version's release notes and role-privilege changes.

Extensions and replication objects

Complete the applicable preparation below before upgrading. Plan for any application dependencies on objects that you remove.

DROP EXTENSION pg_repack;

CREATE EXTENSION pg_repack;

SELECT postgis_extensions_upgrade();

SELECT postgis_full_version();

Availability during an upgrade

Compatibility checks run while the deployment is online. Database upgrade then requires a read-only period and temporary unavailability. Writes can resume before the task finishes, but further connection interruptions can occur during the remaining work.

Applications must handle connection failures and read-only errors, reconnect, and retry interrupted transactions only when safe. Connection pooling does not remove these requirements. Application access is not proof that the upgrade task completed.

Backups and recovery

Create and verify a recent on-demand backup before IPMVU; the service does not automatically take a pre-upgrade data backup. Recovery might require restoring that backup into a new deployment. Account for changes made since the backup.

The service queues a backup of the upgraded deployment to run separately after the upgrade task completes. Its duration does not extend the upgrade task. It might not start immediately. Check its status in Backups and restore.

Recovery of post-upgrade changes requires a successful backup of the upgraded deployment. Point-in-time recovery (PITR) also requires the corresponding transaction logs. PITR cannot replay transactions across the major version upgrade. Pre-upgrade backups and recovery points belong to the earlier version and remain subject to retention limits. See PITR.

If the queued backup fails, take an on-demand backup. Contact support if failures continue. A backup failure does not roll back the upgrade.

Before you begin

Apply these requirements to both staging and production:

• Complete the application, extension, and replication preparation and backup preparation.

• Confirm that all data members are healthy and replication is caught up. Let maintenance and other deployment changes finish.

• Keep at least 10% of allocated disk space free on each data member. Resolve sustained CPU, memory, or disk I/O pressure. Scale up your deployment as needed before starting IPMVU.

• Promote attached read-only replicas that you need to retain; delete only those no longer needed. IPMVU cannot run on a read-only replica deployment or with external replication consumers connected. Built-in high-availability members are upgraded with the source. See Read-only replicas and IPMVU.

• Have the owning application or transaction manager resolve prepared transactions. Do not commit or roll them back solely to clear a precheck.

• Choose a target from your deployment's capabilities. Availability for new deployments does not guarantee an IPMVU transition:

  ibmcloud cdb deployment-capability-show <NAME|CRN> versions
  

Service prechecks cover deployment health, resources, replication, database compatibility, and transaction-log archiving before writes are interrupted. Passing prechecks does not guarantee application compatibility or prevent every later failure.

Planning the upgrade window

Use your staging rehearsal to estimate a maintenance window. Database size, object counts, workload, replication health, and additional data copying affect duration. Allow for the whole upgrade task and delays.

Expiration sets the latest time a queued upgrade can start; it does not stop a running upgrade. For example, a queued request expires at 22:30 UTC. A task started at 22:25 UTC can continue past that time.

After the upgrade

After the upgrade task completes successfully:

1. Confirm the expected PostgreSQL version.
2. Restore extensions and masking as described in preparation. Recreate required logical replication slots and read-only replicas, reconnect consumers, and complete any required data resynchronization before resuming dependent applications.
3. Review optimizer statistics after the upgrade. PostgreSQL 14 through 17 do not transfer optimizer statistics during a major version upgrade, whereas PostgreSQL 18 transfers most optimizer statistics. Follow the PostgreSQL 17 or PostgreSQL 18 post-upgrade instructions for your target.
4. Compare application behavior and performance with your staging results.
5. Verify the post-upgrade backup.

Troubleshooting

For a precheck failure, use the reported error and monitoring metrics to identify the unmet prerequisite, resolve it, and retry. Do not delete database objects or transaction logs just to bypass a check.

If you cannot resolve a precheck error, the upgrade fails, or the deployment remains unavailable, contact support before making further deployment changes. Include the task ID, target version, and relevant task, database, or application errors.

Dry running the promotion and upgrade

A dry run validates the promotion and upgrade process without performing the actual conversion. Review the results through log integration. A successful check does not guarantee that the actual upgrade will succeed.

Specify the target version, dry_run: true and skip_initial_backup: false:

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