How to Upgrade PostgreSQL 17 to PostgreSQL 18

PostgreSQL 18 is the current stable major release, while PostgreSQL 17 remains supported through November 2029. An upgrade is optional while version 17 meets your needs and support requirements. If you choose to move to 18, use a major-version migration method such as pg_upgrade, dump and restore, or logical replication; installing new server packages alone does not upgrade an existing cluster. See the PostgreSQL versioning policy and major-version migration overview.

This guide covers a single cluster upgraded with pg_upgrade. Replication topologies, managed database services, and migrations to a different operating system or architecture need their own vendor or topology-specific procedure.

1. Record the source cluster and its extensions

Connect to the existing cluster and record its exact version and data directory:

SELECT version();
SHOW data_directory;

Record installed extensions as well:

SELECT extname, extversion
FROM pg_extension
ORDER BY extname;

Install PostgreSQL 18 binaries alongside version 17 so both executable directories are available. Install the PostgreSQL 18 build of every extension and custom module used by the old cluster. pg_upgrade can check whether extension binaries exist, but it cannot confirm that third-party modules are compatible with the new major version.

2. Check the PostgreSQL 18 compatibility changes

Read the PostgreSQL 18 migration notes and the relevant extension release notes. PostgreSQL 18 enables data checksums by default when initializing a new cluster. pg_upgrade requires the old and new clusters to use compatible checksum settings. If the old cluster has checksums disabled, initialize the new cluster with initdb --no-data-checksums; do not change checksum mode casually after the cluster has been created.

Merge settings from the old postgresql.conf, postgresql.auto.conf, and pg_hba.conf into the new cluster deliberately. Do not blindly copy configuration files that may contain removed settings, old paths, or values that should change for the new version.

3. Take and verify a backup

Create a backup appropriate for the cluster and recovery plan, including databases, roles, tablespaces, and configuration that must be retained. Restore it to an isolated server or confirm the recovery procedure on a disposable copy before scheduling downtime. See PostgreSQL’s backup and restore documentation.

Rehearse the upgrade on a clone using the same PostgreSQL 17 and 18 builds, extensions, data-checksum settings, configuration, and application versions as production. Test representative application queries and review database and application logs before proceeding.

4. Run pg_upgrade in check mode

Run the pg_upgrade binary from the new PostgreSQL 18 installation. Replace the example paths with the actual binary and cluster directories for your operating system:

/path/to/postgresql/18/bin/pg_upgrade --check \
  --old-bindir=/path/to/postgresql/17/bin \
  --new-bindir=/path/to/postgresql/18/bin \
  --old-datadir=/path/to/postgresql/17/data \
  --new-datadir=/path/to/postgresql/18/data

Check mode does not change cluster data. Resolve reported errors, install missing extension binaries, and repeat the check until it succeeds. Review the manual adjustments it reports as well. Check the temporary old/new server ports if another cluster is already running; when checking a running old cluster, the old and new ports must differ. See the official pg_upgrade documentation for package-specific directory layouts and options.

5. Perform the upgrade during a maintenance window

Stop application writes and follow the rehearsed plan to stop both PostgreSQL servers. Run the same pg_upgrade command without --check. By default, pg_upgrade copies files to the new cluster. Avoid --link for a first production upgrade unless you have explicitly planned for its rollback behavior: after the new cluster starts, the old cluster may no longer be safe to use because files can be shared.

pg_upgrade can generate SQL scripts for post-upgrade work. Run the scripts it reports before normal application traffic resumes. Keep the PostgreSQL 17 cluster and verified backup until the new cluster and applications pass acceptance checks.

6. Verify the new cluster and refresh statistics

Check the running version and data directory:

SELECT version();
SHOW data_directory;

Verify extensions, roles, database access, scheduled jobs, application connections, and replication or backup processes if used. Inspect the PostgreSQL log and application logs before reopening traffic.

PostgreSQL 18 can preserve most optimizer statistics during pg_upgrade, but not every kind. Follow the pg_upgrade output and run the recommended vacuumdb analysis commands so the planner and cumulative statistics are refreshed. The official pg_upgrade post-upgrade steps describe these commands.

If the upgrade does not pass acceptance checks, use the rehearsed recovery plan. The default copy mode leaves the old cluster data intact, but any writes accepted by the new cluster after cutover must also be accounted for before reverting traffic. Do not delete the old cluster until the new one is verified and the retention window has passed.