Upgrading PostgreSQL with `pg_upgrade`

Published: December 10th 2025 (week 50 of 2025)

Upgrading PostgreSQL from one major version to another requires some extra steps. Here is how I upgraded the database for my Dendrite installation on Arch Linux.

Whenever the regular user prompt—]$—is used the displayed command is assumed to be run under the postgres user (unless stated otherwise).

Stop the PostgreSQL service before you do anything else.

You will have to install the postgresql-old-upgrade package. It contains binaries from the previous PostgreSQL version that you will need to be able to use pg_upgrade.

]# pacman -S postgresql-old-upgrade

Move the old data directory to another place. It does not matter where you move the data, just keep it available. The important part is to make the current data directory "free" to be able to create a new database in its place.

Move the current data directory somewhere else

]$ mv ~/data ~/data.17

Initialise the new database

]$ initdb --locale=C.UTF-8 --encoding=UTF-8 -D /home/postgres/data --no-data-checksums

Why did I use the --no-data-checksums flag? Because my old database did not use them, the new database also must not do so. I will enable checksums later, once the database is restored.

Run the upgrade

# I used --clone to get faster copies on btrfs
]$ pg_upgrade -b /opt/pgsql-17/bin -B /usr/bin -d ~/data.17 -D ~/data --clone

Enable data checksums

]$ pg_checksums -D ~/data --enable --progress

Start the PostgreSQL service again. You are done.

Tags