18.6. Upgrading a PostgreSQL cluster
This section discusses how to upgrade your database data from a PostgreSQL distribution to a newer distribution.
The current PostgreSQL version number consists of a major version number and a minor version number. For example, in the version number 10.1, 10 is the major version number and 1 is the minor version number, which means this will be the first minor version of the major version 10. For versions prior to PostgreSQL version 10.0, the version number consists of three numbers, such as 9.5.3. In these cases, the major version consists of the first two digit groups of the version number (for example 9.5), and the minor version is the third number, for example 3, which means this will be the third minor version of the major version 9.5.
Minor releases never change the internal storage format and are always forward and backward compatible with minor releases in 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 upgrade between compatible versions, you simply need to replace the executable file when the server is shut down and restart the server. The data directory remains the same-minor upgrades are as simple as that.
For the main release of PostgreSQL, the internal data storage format is often changed, which complicates the upgrade. The traditional method of moving data to a new major version is to dump and reload it into the database, but this can be slow. A faster way is pg_upgrade. As discussed below, the replication method can also be used for upgrades.
The new major version also usually introduces some user-visible incompatibility, so it may require changes in application programming. All user-visible changes are listed in the release notes (Appendix E), please pay special attention to the section marked "Migration". If you are upgrading across several major versions, be sure to read the release notes for each intermediate version.
Careful users will want to test their client application on the new version before switching over completely. Therefore, it is usually a good idea to create a coexisting installation of the old and new versions. When testing a major PostgreSQL upgrade, consider the following possible categories of changes:
Management
The functions for administrators to monitor and control the server are often changed and added in each major release.
SQL
usually includes new SQL command functions and no changes in behavior, unless specifically mentioned in the release notes.
The library API
usually adds new functions to libraries such as libpq, unless specifically mentioned in the release notes.
System catalog
System catalog changes usually only affect database management tools.
Server C-language API
This involves changes in the back-end function API, which is written in the C programming language. These changes affect the code that references the internal backend functions of the server.
18.6.1. Upgrading data via pg_dumpall
One upgrade method is to dump data from one major version of PostgreSQL and reload it into another major version-to do this, you must use a logical backup tool such as pg_dumpall, the file system level backup method will not Useful (this also prevents you from using a data directory with an incompatible version of PostgreSQL, so trying to start a wrong server version on a data directory will not cause much harm).
We recommend that you use the pg_dump and pg_dumpall programs from newer versions of PostgreSQL, so that you can take advantage of the possible improvements in these programs. The dump program currently released can read the data in any server with version 7.0 and above.
These instructions assume that your existing installation is in the /usr/local/pgsql directory and the data area is there /usr/local/pgsql/data. Please substitute your path appropriately.
- If you are creating a backup, make sure your database is not being updated. This will not affect the integrity of the backup, but of course those changes will not be included in the backup. If necessary, edit
/usr/local/pgsql/data/pg_hba.confthe permissions in the file (or an equivalent method) to not allow anyone but you to use the database. See Chapter 20 for additional information on access control.
To backup your database installation, type:
pg_dumpall > outputfile
To make a backup, you can use the pg_dumpall command of the version you are running, see Section 25.1.2 for details. However, to get the best results, try using the pg_dumpall command of PostgreSQL 11.2, because this version contains bug fixes and improvements to the old version. Although this suggestion may seem strange because you have not installed the new version yet, it is wise to follow this suggestion if you plan to install the new version in parallel. In this case, you can complete the installation normally and transfer data later. This will also reduce downtime.
- Shut down the old server:
pg_ctl stop
On systems that automatically start PostgreSQL, there may be a startup file that will accomplish the same thing. For example, in a Red Hat Linux system, we will find that this also works: /etc/rc.d/init.d/postgresql stopsee Chapter 18 for details on starting and stopping the server.
- If restoring from a backup, rename or delete the old installation directory (if it is not for a specific version). It is a good idea to rename the directory, not delete it, because if you run into a problem and need to return to it, it still exists. Remember that this directory may consume considerable disk space. To rename the directory, use a similar command:
mv /usr/local/pgsql /usr/local/pgsql.old(note that the directory is moved as a single unit so that the relative path can remain unchanged). - Install the new version of PostgreSQL in Section 16.4
- If necessary, create a new database cluster. Remember that you must execute these commands when logging in to a special database user account (if you are upgrading, you already have this account).
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data - Restore your previous pg_hba.conf and any postgresql.conf modifications.
- To start the database server, also use a special database user account:
/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data - Finally, use the new psql to restore your data from backup:
/usr/local/pgsql/bin/psql -d postgres -f outputfileinstall the new server in a different directory and run the old and new servers on different ports in parallel to achieve the lowest downtime. Then you can use it like this:pg_dumpall -p 5432 | psql -d postgres -p 5433to transfer your data.
18.6.2. Upgrading data via pg_upgrade
The pg_upgrade module allows an installation to be upgraded "in-place" from one major version of PostgreSQL to another major version. The upgrade can be performed within a few minutes, especially when using the –link mode. It requires similar steps to pg_dumpall above, such as starting/stopping the server and running initdb. The pg_upgrade documentation outlines the required steps.
18.6.3. Upgrade data by copying
You can also use the updated version of PostgreSQL logical replication to create a backup server. Logical replication supports replication between different major versions of PostgreSQL. The backup server can be on the same computer or on a different computer.
Once it is synchronized with the main server (running the old version of PostgreSQL), you can switch the host and use the backup server as the host, and then shut down the old database instance. Such a switch makes the downtime of an upgrade only a few seconds. This upgrade method can use built-in logical replication tools and external logical replication systems such as pglogical, Slony, Londiste, and Bucardo.