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

## Upgrade

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

**CLI**
```sh
dcloud rds instances upgrade ewdb-0123456789ab --engine-version 18
```

**API**
```http
POST /rds/api/instances/ewdb-0123456789ab/upgrade
{ "engineVersion": "18" }
```

An exact minor such as `"18.7"` works too. The answer is `202`.

**Terraform:** not available. An upgrade is an action; changing `engine_version` replaces the database.

## 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.

## Related

- [Versions and maintenance](versions-and-maintenance.md)
- [Restore a database](restore-a-database.md)
- `rds.instances.upgrade` · `dcloud rds instances upgrade`
