A server utility for performing a binary upgrade of a PostgreSQL database cluster

pg_upgrade is a server utility for performing a binary upgrade of a PostgreSQL database cluster.

pg_upgrade was added in PostgreSQL 9.0, initially as a contrib module based on pg_migrator.

Change history

  • PostgreSQL 13
    • default new bindir is now the same location as the pg_upgrade binary being executed, removing the need to explicitly specify -B newbindir in most cases (commit 959f6d6a)
  • PostgreSQL 12
    • --clone option added (commit 3a769d82)
    • --socketdir option added (commit 2d34ad84)
  • PostgreSQL 10
    • hash indexes from older PostgreSQL versions will be invalidated and a script generated for recreating them (commit a95410e2)
  • PostgreSQL 9.5
  • PostgreSQL 9.4
    • -u/--user options renamed to -U/--username for consistency with other utilties (commit 457d6cf0)
    • memory consumption significantly reduced (commit 2a2e40aa)
  • PostgreSQL 9.3
    • --jobs option added to enable parallel schema dump/restore of databases, as well as parallel copy/link of data files (commit 6f1b9e4e and commit a89c46f9)
    • improvements to status display (commit 6dd95845)
    • performance improvement for databases with large numbers of tables (commit 29add0de)
    • properly detect the location of non-default socket directories (commit f763b771)
  • PostgreSQL 9.2
    • environment variables specific to pg_upgrade renamed to start with PG; PGPORT now ignored and replaced by PGPORTOLD/PGPORTNEW (commit a88f4496)
    • uses port 50432 by default (commit a88f4496)
    • general logging improvements (commit 717f6d60)
    • old cluster will only be locked if link mode used (commit 2127aac6)
    • script to incrementally generate more accurate statistics added (commit faec2815)
    • -g/-G/-l logging options removed (commit 717f6d60)
    • -o/-O options added (commit 0dc3f57b)
    • -r/--retain option added (commit 717f6d60)
    • -v/--verbose behaviour improved (commit 717f6d60)
    • support upgrading clusters without a postgres database (commit a50d860a)
  • PostgreSQL 9.0

Note that an earlier version of pg_upgrade was originally added as a contrib module in PostgreSQL 7.2 (commit 92a8bc96) and removed in PostgreSQL 8.1 (commit d20763db).

Source code

pg_upgrade source code is located at src/bin/pg_upgrade/.

See src/bin/pg_upgrade/IMPLEMENTATION for a technical description of the implementation.


Server utility, Upgrading