23.5. Migration Between Releases

This section discusses how to migrate your database data from one PostgreSQL release to a newer one. The software installation procedure per se is not the subject of this section; those details are in Chapter 14.

As a general rule, the internal data storage format is subject to change between major releases of PostgreSQL (where the number after the first dot changes). This does not apply to different minor releases under the same major release (where the number after the second dot changes); these always have compatible storage formats. For example, releases 7.2.1, 7.3.2, and 7.4 are not compatible, whereas 7.2.1 and 7.2.2 are. When you update between compatible versions, you can simply replace the executables and reuse the data directory on disk. Otherwise you need to back up your data and restore it on the new server. This has to be done using pg_dump; file system level backup methods obviously won't 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 any enhancements that may have been made in these programs. Current releases of the dump programs can read data from any server version back to 7.0.

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 6543

to transfer your data. Or use an intermediate file if you want. Then you can shut down the old server and start the new server at the port the old one was running at. You should make sure that the old database is not updated after you run pg_dumpall, otherwise you will obviously lose that data. See Chapter 20 for information on how to prohibit access.

In practice you probably want to test your client applications on the new setup before switching over completely. This is another reason for setting up concurrent installations of old and new versions.

If you cannot or do not want to run two servers in parallel you can do the backup step before installing the new version, bring down the server, move the old version out of the way, install the new version, start the new server, restore the data. For example:

pg_dumpall > backup
pg_ctl stop
mv /usr/local/pgsql /usr/local/pgsql.old
cd ~/postgresql-8.2.5
gmake install
initdb -D /usr/local/pgsql/data
postgres -D /usr/local/pgsql/data
psql -f backup postgres

See Chapter 16 about ways to start and stop the server and other details. The installation instructions will advise you of strategic places to perform these steps.