| PostgreSQL 9.0.23 Documentation | ||||
|---|---|---|---|---|
| Prev | Up | Chapter 24. Backup and Restore | Next | |
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 15.
PostgreSQL major versions are represented by the first two digit groups of the version number, e.g., 8.4. PostgreSQL minor versions are represented by the third group of version digits, e.g., 8.4.2 is the second minor release of 8.4. Minor releases never change the internal storage format and are always compatible with earlier and later minor releases of the same major version number, e.g., 8.4.2 is compatible with 8.4, 8.4.1 and 8.4.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 reload the database. Other, less-well-tested possibilities are available, as discussed below.
New major versions also typically introduce some user-visible incompatibilities, so application programming changes may be required. 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:
The capabilities available for administrators to monitor and control the server often change and improve in each major release.
Typically this includes new SQL command capabilities and not changes in behavior, unless specifically mentioned in the release notes.
Typically libraries like libpq only add new functionality, again unless mentioned in the release notes.
System catalog changes usually only affect database management tools.
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.
To dump data from one major version of PostgreSQL and reload it in another, you must use pg_dump; 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 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 you can use an intermediate file if you wish. Then you can shut down the old server and start the new server using the port the old one was running on. You should make sure that the old database is not updated after you begin to run pg_dumpall, otherwise you will lose those updates. See Chapter 19 for information on how to prohibit access.
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 old server, move the old version out of the way, install the new version, start the new server, and restore the data. For example:
pg_dumpall > backup pg_ctl stop mv /usr/local/pgsql /usr/local/pgsql.old # Rename any tablespace directories as well cd ~/postgresql-9.0.23 gmake install initdb -D /usr/local/pgsql/data postgres -D /usr/local/pgsql/data psql -f backup postgres
See Chapter 17 about ways to start and stop the server and other details. The installation instructions will advise you of strategic places to perform these steps.
Note: When you "move the old installation out of the way" it might no longer be perfectly usable. Some of the executable programs contain absolute paths to various installed programs and data files. This is usually not a big problem, but if you plan on using two installations in parallel for a while you should assign them different installation directories at build time. (This problem is rectified in PostgreSQL version 8.0 and later, so long as you move all subdirectories containing installed files together; for example if /usr/local/postgres/bin/ goes to /usr/local/postgres.old/bin/, then /usr/local/postgres/share/ must go to /usr/local/postgres.old/share/. In pre-8.0 releases moving an installation like this will not work.)
The contrib program pg_upgrade allows an installation to be migrated in-place from one major PostgreSQL version to the next. Keep in mind that this method does not provide any scope for running old and new versions concurrently. Also, pg_upgrade is much less battle-tested than pg_dump, so having an up-to-date backup is strongly recommended in case something goes wrong.
It is also possible to use certain replication methods, such as Slony, to create a standby server with the updated version of PostgreSQL. The standby can be on the same computer or a different computer. Once it has synced up with the master server (running the older version of PostgreSQL), you can switch masters and make the standby the master and shut down the older database instance. Such a switch-over results in only several seconds of downtime for an upgrade.