18.6. Upgrading a PostgreSQL Cluster
This section discusses how to upgrade your database data from one PostgreSQL release to a newer one.
Current PostgreSQL version numbers consist of a major and a minor version number. For example, in the version number 10.1, the 10 is the major version number and the 1 is the minor version number, meaning this would be the first minor release of the major release 10. For releases before PostgreSQL version 10.0, version numbers consist of three numbers, for example, 9.5.3. In those cases, the major version consists of the first two digit groups of the version number, e.g., 9.5, and the minor version is the third number, e.g., 3, meaning this would be the third minor release of the major release 9.5.
Minor releases never change the internal storage format and are always compatible with earlier and later minor releases of the same major version number. For example, version 10.1 is compatible with version 10.0 and version 10.6. Similarly, for example, 9.5.3 is compatible with 9.5.0, 9.5.1, and 9.5.6. To update between compatible versions, you simply replace the executables while the server is down and restart the server. The data directory remains unchanged - minor upgrades are that simple.
For major releases of PostgreSQL , the internal data storage format is subject to change, thus complicating upgrades. The traditional method for moving data to a new major version is to dump and restore the database, though this can be slow. A faster method is pg_upgrade . Replication methods are also available, as discussed below. (If you are using a pre-packaged version of PostgreSQL , it may provide scripts to assist with major version upgrades. Consult the package-level documentation for details.)
New major versions also typically introduce some user-visible incompatibilities, so application programming changes might be required. All user-visible changes are listed in the release notes ( Appendix E ); pay particular attention to the section labeled "Migration". Though you can upgrade from one major version to another without upgrading to intervening versions, you should read the major release notes of all intervening versions.
Cautious users will want to test their client applications on the new version before switching over fully; therefore, it's often a good idea to set up concurrent installations of old and new versions. When testing a PostgreSQL major upgrade, consider the following categories of possible changes:
- Administration
-
The capabilities available for administrators to monitor and control the server often change and improve in each major release.
- SQL
-
Typically this includes new SQL command capabilities and not changes in behavior, unless specifically mentioned in the release notes.
- Library API
-
Typically libraries like libpq only add new functionality, again unless mentioned in the release notes.
- System Catalogs
-
System catalog changes usually only affect database management tools.
- Server C-language API
-
This involves changes in the backend function API, which is written in the C programming language. Such changes affect code that references backend functions deep inside the server.
18.6.1. Upgrading Data via pg_dumpall #
One upgrade method is to dump data from one major version of PostgreSQL and restore it in another - to do this, you must use a logical backup tool like pg_dumpall ; file system level backup methods will not work. (There are checks in place that prevent you from using a data directory with an incompatible version of PostgreSQL , so no great harm can be done by trying to start the wrong server version on a data directory.)
It is recommended that you use the pg_dump and pg_dumpall programs from the newer version of PostgreSQL , to take advantage of enhancements that might have been made in these programs. Current releases of the dump programs can read data from any server version back to 9.2.
These instructions assume that your existing installation is under the
/usr/local/pgsql
directory, and that the data area is in
/usr/local/pgsql/data
. Substitute your paths
appropriately.
-
If making a backup, make sure that your database is not being updated. This does not affect the integrity of the backup, but the changed data would of course not be included. If necessary, edit the permissions in the file
/usr/local/pgsql/data/pg_hba.conf(or equivalent) to disallow access from everyone except you. See Chapter 20 for additional information on access control.To back up your database installation, type:
pg_dumpall >outputfileTo make the backup, you can use the pg_dumpall command from the version you are currently running; see Section 25.1.2 for more details. For best results, however, try to use the pg_dumpall command from PostgreSQL 17.2, since this version contains bug fixes and improvements over older versions. While this advice might seem idiosyncratic since you haven't installed the new version yet, it is advisable to follow it if you plan to install the new version in parallel with the old version. In that case you can complete the installation normally and transfer the data later. This will also decrease the downtime.
-
Shut down the old server:
pg_ctl stopOn systems that have PostgreSQL started at boot time, there is probably a start-up file that will accomplish the same thing. For example, on a Red Hat Linux system one might find that this works:
/etc/rc.d/init.d/postgresql stopSee Chapter 18 for details about starting and stopping the server.
-
If restoring from backup, rename or delete the old installation directory if it is not version-specific. It is a good idea to rename the directory, rather than delete it, in case you have trouble and need to revert to it. Keep in mind the directory might consume significant disk space. To rename the directory, use a command like this:
mv /usr/local/pgsql /usr/local/pgsql.old(Be sure to move the directory as a single unit so relative paths remain unchanged.)
-
Install the new version of PostgreSQL as outlined in Chapter 17 .
-
Create a new database cluster if needed. Remember that you must execute these commands while logged in to the special database user account (which you already have if you are upgrading).
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data -
Restore your previous
pg_hba.confand anypostgresql.confmodifications. -
Start the database server, again using the special database user account:
/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data -
Finally, restore your data from backup with:
/usr/local/pgsql/bin/psql -d postgres -foutputfileusing the new psql .
The least downtime can be achieved by installing the new server in a different directory and running both the old and the new servers in parallel, on different ports. Then you can use something like:
pg_dumpall -p 5432 | psql -d postgres -p 5433
to transfer your data.
18.6.2. Upgrading Data via pg_upgrade #
The
pg_upgrade
module allows an installation to
be migrated in-place from one major
PostgreSQL
version to another. Upgrades can be performed in minutes,
particularly with
--link
mode. It requires steps similar to
pg_dumpall
above, e.g., starting/stopping the server,
running
initdb
. The
pg_upgrade
documentation
outlines the necessary steps.
18.6.3. Upgrading Data via Replication #
It is also possible to use logical replication methods to create a standby server with the updated version of PostgreSQL . This is possible because logical replication supports replication between different major versions of PostgreSQL . The standby can be on the same computer or a different computer. Once it has synced up with the primary server (running the older version of PostgreSQL ), you can switch primaries and make the standby the primary and shut down the older database instance. Such a switch-over results in only several seconds of downtime for an upgrade.
This method of upgrading can be performed using the built-in logical replication facilities as well as using external logical replication systems such as pglogical , Slony , Londiste , and Bucardo .