Upgrade the major version
Move a database to a newer PostgreSQL major in place, after a full backup, with a few minutes of downtime.
A database can move to any newer offered major, skipping majors if you like (15 → 18). You ask for it; it is never automatic. Replace ewdb-0123456789ab with your database's id.
Warning
There is no downgrade in place. To go back, restore the pre-upgrade backup into a new database.
Prerequisites
- Permission for
rds:ModifyDBInstance. - The database is Available; otherwise the request is refused with
409. - On a cluster, no readers: remove them first (otherwise
409) and add them again afterwards. - In the console, also
rds:DescribeDBInstancesto open the database's page (without it the page is not found).
Upgrade
- Open the database, then choose Maintenance.
- Under Major version upgrade, choose Upgrade to PostgreSQL version.
- Confirm.
dcloud rds instances upgrade ewdb-0123456789ab --engine-version 18POST /rds/api/instances/ewdb-0123456789ab/upgrade
{ "engineVersion": "18" }An exact minor such as "18.7" works too. The answer is 202.
Not available in Terraform. An upgrade is an action; changing `engine_version` replaces the database.
What happens on a single node
Each step is on Activity (phase upgrade):
- A full backup, which the upgrade waits for. If backups are off, Activity warns and the upgrade goes ahead without one.
- The new version's server and extension packages are installed beside the old ones. The data is
upgraded in place with
pg_upgrade --link, keeping the old cluster's encoding, collation and checksum setting.pg_upgrade --checkruns first. If anything fails up to this point, the old server is started again and nothing has changed. - The machine is rebuilt on the new version, on the same data volume and address. The new server adopts the upgraded data, updates extensions to their newest version, and rebuilds planner statistics in the background (queries can be slower for the first minutes). It then takes the new version's first backup.
The database is unavailable from step 2 until the rebuilt machine serves, usually a few minutes.
What happens on a cluster
The same request upgrades all three nodes:
- A full backup.
- Patroni stops on the replicas, so none takes over.
- The leader's data is upgraded with
pg_upgrade --link, and the leader's machine is rebuilt on the new version. Patroni there takes the upgraded data as the cluster. - Each replica's machine is rebuilt in turn, starts empty on the new version, and copies the data from the leader.
The database is unavailable from step 2 until the leader serves again, usually a few minutes (measured on 2026-11-12: 2 min 7 s on a 21 GB cluster under write load, with no commit lost). It then serves while the replicas are rebuilt; they are back after roughly a copy of the database each. If something fails before the leader's data is touched, Patroni is started again everywhere and nothing has changed.
Result
Data, logins, ALTER SYSTEM settings, extensions and their objects (vector indexes, PostGIS
data, pg_cron jobs) come through. Point-in-time restore covers the new version from its first
backup on. Earlier moments are restored from the backups taken before the upgrade, into a new
database on the old version.