Upgrade PostgreSQL

Upgrading a PostgreSQL cluster to a new major version on Debian/Ubuntu systems uses the pg_upgradecluster wrapper from the postgresql-common package. The old cluster is preserved (not deleted) so the upgrade can be verified before committing.

Procedure

# 1. Drop any existing (empty) new-version cluster
sudo -u postgres pg_dropcluster --stop $NEW_VER main
 
# 2. Upgrade the old cluster to the new version
sudo -u postgres pg_upgradecluster $OLD_VER main
 
# 3. Verify the new cluster works, then drop the old one
sudo -u postgres pg_dropcluster --stop $OLD_VER main

Replace $OLD_VER and $NEW_VER with major version numbers (e.g., 13 and 14).

What pg_upgradecluster does

• Copies the old cluster’s configuration files to the new cluster and adjusts them for the new version
• Moves the old cluster to a previously unused port; the new cluster takes the original port
• Sets the old cluster to “manual” startup mode (won’t auto-start on boot)
• Uses pg_dump/pg_restore by default; pass -m upgrade to use pg_upgrade instead (faster for large databases)
• Supports --link for hard-link-based upgrades (near-instant, but destructive to the old cluster’s data directory)

Key options

Option	Purpose
-v VERSION	Target version (default: latest installed)
-m dump|upgrade|link|clone	Upgrade method (default: dump)
-k / --link	Use hard links instead of copying (with -m upgrade)
--keep-port	Don’t swap ports between old and new clusters
--[no-]start	Control whether the new cluster starts after upgrade

Verification checklist

After upgrading, before dropping the old cluster:

1. Connect to the new cluster and confirm databases exist: \l
2. Check table counts and spot-check data integrity
3. Verify application connectivity (the new cluster is on the original port)
4. Confirm extensions (e.g., PostGIS) loaded correctly — some need hook scripts
5. Run ANALYZE on all databases (statistics don’t carry over)

Sources

• pg_upgradecluster(1) — Debian Manpages (bookworm)
• pg_upgrade - PostgreSQL Documentation

See also

• enumerate-database-schemas — verify schema integrity post-upgrade
• sql-injection-attacks — PostgreSQL-specific SQLi techniques
• database-fingerprinting — confirm PostgreSQL version