How to Upgrade PostgreSQL 14 to PostgreSQL 18

PostgreSQL 14 reaches end of support on November 12, 2026. If you still run PostgreSQL 14, plan a major-version upgrade to a supported release before then. PostgreSQL 18 is the current stable major series. The project supports upgrading directly from PostgreSQL 14 to 18; you do not need to install versions 15, 16, and 17 in between. Read the migration notes for each intervening major release before upgrading. See the PostgreSQL versioning policy and PostgreSQL 18 upgrade documentation.

This guide covers one self-managed cluster. A package update alone does not convert a PostgreSQL 14 data directory to version 18. Managed database services and replication topologies need their provider-specific or topology-specific upgrade procedure.

1. Record the source cluster and extensions

Connect to PostgreSQL 14 and record its exact version, data directory, checksum setting, and installed extensions:

SELECT version();
SHOW data_directory;
SHOW data_checksums;

SELECT extname, extversion
FROM pg_extension
ORDER BY extname;

Check that the target operating system and architecture support PostgreSQL 18. Install the PostgreSQL 18 binaries and a compatible build of every extension or custom module used by the old cluster. pg_upgrade checks some binary compatibility details, but it cannot verify third-party extension behavior or application compatibility.

2. Review changes from versions 15 through 18

Read the migration section of the release notes for PostgreSQL 15, 16, 17, and 18, along with the release notes for extensions you use. Check for changes to SQL behavior, reserved words, configuration parameters, collations, and extension interfaces that affect your applications or operations.

PostgreSQL 18 enables data checksums by default when initdb creates a new cluster. pg_upgrade requires the old and new clusters to have matching checksum settings. If PostgreSQL 14 reports checksums off, initialize the new version 18 cluster with initdb --no-data-checksums; do not switch checksum modes casually as part of an upgrade. See the PostgreSQL 18 migration notes and initdb checksum option.

3. Create and restore-test a backup

Create a backup that covers databases, roles, tablespaces, and configuration needed for recovery. Restore it to an isolated server or disposable copy and verify that the databases and application data are usable. A backup that has not been restore-tested is not a verified rollback plan. See PostgreSQL’s backup documentation.

Rehearse the full upgrade on a clone using the same PostgreSQL 14 and 18 builds, extensions, checksum settings, configuration, and application versions as the source. Test representative queries and transactions, scheduled jobs, connections, and backup procedures before scheduling production downtime.

4. Check pg_upgrade before changing the cluster

Install the PostgreSQL 18 binaries alongside version 14 and initialize a new PostgreSQL 18 cluster with compatible settings. Keep the old cluster intact. Run pg_upgrade from the new PostgreSQL 18 installation in check mode, replacing the paths with those used by your operating system:

/path/to/postgresql/18/bin/pg_upgrade --check \
  --old-bindir=/path/to/postgresql/14/bin \
  --new-bindir=/path/to/postgresql/18/bin \
  --old-datadir=/path/to/postgresql/14/data \
  --new-datadir=/path/to/postgresql/18/data \
  --old-port=50432 \
  --new-port=50433

The example uses different temporary ports; replace them if either port is already in use. pg_upgrade --check can run while the old server is running, but the old and new ports must differ in that case. Resolve every reported error, install missing extension binaries, and review manual adjustments before repeating the check. Check mode does not modify the cluster data. PostgreSQL’s pg_upgrade manual documents directory layout, compatibility requirements, and supported options.

If the check passes on the rehearsal copy, repeat the command without --check during the maintenance window. Stop both PostgreSQL clusters and all application writes first. The default mode copies files and leaves the old cluster data intact. Avoid --link for a first production upgrade unless its rollback limitations are part of the recovery plan: after PostgreSQL 18 starts, the old cluster may no longer be safe to use because files can be shared.

5. Verify PostgreSQL 18 and restore normal traffic

Run the post-upgrade scripts reported by pg_upgrade, install and update extensions, and verify the new server version:

SELECT version();
SHOW data_directory;

Check application logins, roles, database access, migrations, scheduled jobs, replication, and backup tooling. Review the PostgreSQL and application logs before reopening normal traffic. PostgreSQL 18 can preserve most optimizer statistics during pg_upgrade, but not all; follow the utility’s output and run the recommended vacuumdb analysis commands.

An in-place downgrade from PostgreSQL 18 to 14 is not the rollback path. If the new cluster fails acceptance checks, follow the rehearsed recovery procedure and restore the verified pre-upgrade backup or snapshot. For an existing PostgreSQL 17 cluster, see the separate PostgreSQL 17 to 18 upgrade guide.