Upgrade the major version

Move a database to a newer PostgreSQL major in place, after a full backup, with a few minutes of downtime.

Last updated 18 November 2026View as Markdown

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:DescribeDBInstances to open the database's page (without it the page is not found).

Upgrade

  1. Open the database, then choose Maintenance.
  2. Under Major version upgrade, choose Upgrade to PostgreSQL version.
  3. Confirm.

What happens on a single node

Each step is on Activity (phase upgrade):

  1. A full backup, which the upgrade waits for. If backups are off, Activity warns and the upgrade goes ahead without one.
  2. 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 --check runs first. If anything fails up to this point, the old server is started again and nothing has changed.
  3. 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:

  1. A full backup.
  2. Patroni stops on the replicas, so none takes over.
  3. 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.
  4. 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.

Did this page help you?