Upgrade RDS PostgreSQL major version with zero downtime - ApsaraDB RDS

Zero-downtime major version upgrade lets you upgrade an RDS PostgreSQL instance to a higher major engine version without service interruption. The upgrade uses logical replication to sync data from the source instance to the target instance, then switches traffic with a brief read-only window.

How it works

The upgrade runs in three phases:

Pre-upgrade check — Validate the instance configuration and confirm compatibility with zero-downtime upgrade mode.
Upgrade task — Create the target instance, establish logical replication, and sync data.
Instance switch — Sync sequences and switch traffic to the target instance.

Upgrade impacts

Phase	Impact	Duration
DDL restriction	All DDL operations are blocked from the start of the upgrade until the switch completes.	Entire upgrade process
WAL log accumulation	A replication slot is created before the upgrade starts, causing Write-Ahead Logging (WAL) logs to accumulate on the source instance. Disk usage rises temporarily, then drops after logical replication is established.	From replication slot creation until the subscriber on the target starts
Logical replication sync	Logical replication generates additional load on the source instance. The impact scales with the number of databases and write traffic. Monitor `wal_sender` resource usage to evaluate the load.	From logical replication established until switch completes
Switch (read-only)	The instance enters read-only mode while sequences are synchronized.	Proportional to the number of sequences

Note To find the WAL log accumulation window, open Upgrade History and check the upgrade log. WAL logs start accumulating at the creating replication slots and publications on the source event and stop accumulating when the subscriber on the destination starts and establishes the logical replication relationship.

Prerequisites

Before you begin, ensure that you have:

An RDS PostgreSQL instance with Major Version Upgrade visible in the left-side navigation pane
Removed any read-only instances attached to the primary instance, or updated your application to connect directly to the primary instance endpoint

Note If Major Version Upgrade is not visible in the console, check the version and series configuration of your instance. See Upgrade the major engine version for requirements.

Note If read-only instances exist, update your application's endpoint configuration to point to the primary instance during off-peak hours before deleting the read-only instances.

Step 1: Run the pre-upgrade check

Zero-downtime upgrade uses logical replication, which has specific compatibility requirements. The pre-upgrade check validates your instance against these requirements and flags anything that would block the upgrade.

Log on to the ApsaraDB RDS console and go to the Instances page. In the top navigation bar, select the region where your instance resides, then click the instance ID.
In the left-side navigation pane, click Major Version Upgrade.
On the Upgrade Check tab, click Create Upgrade Check Report.
Select the target version under Select The Upgrade Version, set Upgrade Mode to Zero Downtime, and click OK.
Review the results in the Upgrade Check Log section.

Important

Proceed to Step 2 only if Check Result shows successful. If the check fails, click View Information to see the detailed report. For help interpreting errors, see Interpreting the RDS PostgreSQL major version upgrade check report.
If plugins are created on the target instance after the check passes, run the check again before proceeding.

Step 2: Create the upgrade task

Click the Upgrade Instance tab, read the warning, select the target version under Select The Upgrade Version, and click Create Upgrade Task.
In the confirmation dialog, click OK.
In the Create Major Version Upgrade Task section, set Upgrade Mode to Zero-downtime.
Click Create Now.

The instance status changes to Migrating when the upgrade task starts. Track progress on the Upgrade History tab.

Monitor instance load during the upgrade

Monitor the instance load and disk usage throughout the upgrade:

Disk usage: Rises during WAL log accumulation, then drops once logical replication is established.
CPU and network load: Increases during the logical replication sync phase. Check wal_sender under each resource category to evaluate the impact.

Step 3: Verify and switch to the target instance

Verify the target instance

When the instance status changes from Migrating to Migrating Data, logical replication is established. At this point, connect to the target instance to verify the upgraded data.

Go to the Upgrade History tab.
Copy the Higher Version Verification Address from the target upgrade record.
Connect to the target instance and verify that the data meets your expectations.

Note The target instance is in read-only mode during verification.

Switch traffic to the target instance

After confirming the data is correct and Upgrade Result shows Synchronizing:

In the Upgrade Log column, click Change.
Set the Tolerable Write Suspension Time (in seconds) and click OK.

During the switch, sequences are synchronized and the instance enters read-only mode (Upgrade Result changes to Read Only). If the sequence synchronization exceeds the tolerable write suspension time, the system returns to the Synchronizing state and removes the read-only restriction — the switch does not proceed, and you can retry.

Check the switch result:
- Migrating — The switch is in progress. To cancel, click Break in the Upgrade Log column.
- The Instance Is Running. — The switch is complete. Verify the current engine version on the instance Basic Information page.

Note If Upgrade Result shows a status other than Synchronizing, see Upgrade result statuses for guidance. To abandon the upgrade entirely, click Cancel in the Upgrade Log column. This deletes the replication slot, removes the logical replication load from the source instance, and re-enables DDL operations.

Rollback

Before the switch, the system automatically backs up the lower-version instance. If you need to roll back after switching:

Clone a new instance from the last backup of the lower-version instance taken before the switch.
Update the endpoint of the cloned instance to match the endpoint of the original instance.

Upgrade result statuses

The Upgrade History tab shows the following statuses in the Upgrade Result column:

Status	Meaning	Available actions
Running	The upgrade task is running.	None
Synchronizing	Logical replication is healthy.	Change: Switch to the target instance. Cancel: Abandon this upgrade.
Replication Interrupted	Logical replication is abnormal.	View the upgrade log to identify the cause. Cancel: Abandon this upgrade.
Read Only	Switch is in progress. The instance is in read-only mode while sequences are synchronized.	Break: Cancel this switch operation.
Switch	Sequence synchronization is complete; final tasks are running.	None
Canceled	The upgrade task was canceled.	None
Success	The upgrade is complete.	None