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.
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 8.1.1, 8.2.3, and 8.3 are
not compatible, whereas 8.2.3 and 8.2.4 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 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 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 begin to run
pg_dumpall, otherwise you will lose that data. See Chapter 19 for information on how to prohibit
It is also possible to use replication methods, such as
Slony, to create a slave server with the updated version of
PostgreSQL. The slave 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 slave the master and shut down the older
database instance. Such a switch-over results in only several seconds
of downtime for an upgrade.
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, and restore the data. For example:
pg_dumpall > backup
mv /usr/local/pgsql /usr/local/pgsql.old
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 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/share/ must go to
/usr/local/postgres.old/share/. In pre-8.0 releases
moving an installation like this will not work.)
In practice you probably want to test your client applications on the
new version before switching over completely. This is another reason
for setting 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.
- 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 involved changes in the backend function API, which is written
in the C programming language. Such changes effect code that
references backend functions deep inside the server.