pg_upgrade

Check clusters before upgrading

$ pg_upgrade [[-c|--check]] [[-b|--old-bindir]] [path/to/old_bin] [[-B|--new-bindir]] [path/to/new_bin] [[-d|--old-datadir]] [path/to/old_data] [[-D|--new-datadir]] [path/to/new_data]

$ pg_upgrade [[-b|--old-bindir]] [path/to/old_bin] [[-B|--new-bindir]] [path/to/new_bin] [[-d|--old-datadir]] [path/to/old_data] [[-D|--new-datadir]] [path/to/new_data]

$ pg_upgrade [[-j|--jobs]] [njobs] [[-b|--old-bindir]] [path/to/old_bin] [[-B|--new-bindir]] [path/to/new_bin] [[-d|--old-datadir]] [path/to/old_data] [[-D|--new-datadir]] [path/to/new_data]

$ pg_upgrade [[-p|--old-port]] [port] [[-P|--new-port]] [port] [[-b|--old-bindir]] [path/to/old_bin] [[-B|--new-bindir]] [path/to/new_bin] [[-d|--old-datadir]] [path/to/old_data] [[-D|--new-datadir]] [path/to/new_data]

$ pg_upgrade [[-k|--link]] [[-b|--old-bindir]] [path/to/old_bin] [[-B|--new-bindir]] [path/to/new_bin] [[-d|--old-datadir]] [path/to/old_data] [[-D|--new-datadir]] [path/to/new_data]

$ pg_upgrade [[-?|--help]]

pg_upgrade -b old_bindir -B new_bindir -d old_datadir -D new_datadir [options ...]

-b old_bindir, --old-bindir=old_bindir
    Old cluster's bindir containing executables like postgres.

-B new_bindir, --new-bindir=new_bindir
    New cluster's bindir.

-d old_datadir, --old-datadir=old_datadir
    Old cluster data directory.

-D new_datadir, --new-datadir=new_datadir
    New cluster data directory (must be empty).

-o old_port, --old-port=old_port
    Old cluster port (default 50432).

-O new_port, --new-port=new_port
    New cluster port (default 50433).

--check
    Check compatibility only, no changes.

-c
    Check configuration settings compatibility.

-l logfile
    Log output to file.

--link
    Link files instead of copying (faster, fewer writes).

--multi-thread=N
    Use N threads for copy/link operations.

-n
    Do not start/stop servers or create scripts.

-N
    Do not start/stop old server.

-r
    Retain old access privileges and SQL objects.

-U username
    Cluster superuser name (default postgres).

-v, --verbose
    Enable verbose logging.

--version
    Print version and exit.

-?, --help
    Show help.

pg_upgrade is a PostgreSQL utility for upgrading an existing data cluster from one major version to a newer major version. It performs an in-place upgrade by copying (or linking) data files and rewriting system catalogs, making it much faster than traditional dump/restore methods, especially for large databases.

The process involves shutting down the old cluster, initializing the new cluster if needed, upgrading the data files, and generating scripts to start both clusters for validation. After verifying the new cluster works correctly (e.g., via pg_dump), the old cluster can be discarded.

It supports check-only mode to validate compatibility without changes, link mode for speed (on supported filesystems), and multi-threading for file operations. Both old and new PostgreSQL installations must be present, and the upgrade requires the same operating system endianness and page size. Always back up data before use, as downtime is required and failures may leave clusters inconsistent.

Requires matching OS endianness/page size between versions. Run as database superuser. Backup data first. Downtime required. New datadir must not exist or be empty. Not for minor version upgrades.

Install both old/new PostgreSQL. Stop old cluster. Ensure pg_hba.conf allows connections on temp ports.

Run ANALYZE NEWDB.*; delete old cluster after validation; update postgresql.conf.

Use generated scripts to start both clusters; test queries and pg_dump.

Introduced in PostgreSQL 9.0 for binary upgrades. Link mode added in 9.1; configuration checks in 9.2; multi-threading in 9.4; improved Windows support in 10+. Now standard for major upgrades.

pg_ctl(1), initdb(1), pg_dump(1), postgres(1), pg_dumpall(1)