PG_UPGRADE(1)

NAME
pg_upgrade - upgrading from a previous release without reloading

SYNOPSIS
pg_upgrade [-D data_dir] -1 | -2

DESCRIPTION
pg_upgrade is a utility for upgrading from a previous PostgreSQL release without reloading all the data. Not all PostgreSQL releases can use this utility. Check the release notes for details about your version.

pg_upgrade must be run in two stages. In phase one you must run pg_upgrade with your old database installation in place. In phase two, pg_upgrade must be run on a freshly initdb'ed current install. In both phases, the same pg_upgrade script matching the newly installed version must be used.

Upgrading PostgreSQL with pg_upgrade

1) Back up your existing data directory, preferably by making a complete dump with pg_dumpall.

2) Copy the program pgsql/contrib/pg_upgrade/pg_upgrade from the current PostgreSQL distribution somewhere into your path.

3) Change your working directory to the pgsql main directory, and type:

$ pg_upgrade -1

to collect information about the old database needed for the upgrade. You may use -D to specify the data directory, or use PGDATA.

4) Do:

$ make install

to install the new binaries.

5) Do:

$ cd pgsql/contrib/pg_resetxlog
$ make install

to install the pg_resetxlog utility which is needed by pg_upgrade.

6) Run initdb to create a new template1 database containing the system tables for the new release. Make sure you use settings similar to those used in your previous version.

7) Start the new postmaster. (Note: it is critical that no users connect to the server until the upgrade is complete. You may wish to start the postmaster without -i or alter pg_hba.conf temporarily.)

8) Change your working directory to the pgsql main directory again, and type:

$ pg_upgrade -2

The program will do some checking to make sure everything is properly configured, and will then recreate all the databases and tables you had, but with no data. It will then physically move the data files containing non-system tables and indexes into the proper subdirectories.

9) Restore your old pg_hba.conf if needed to allow user logins.

10) Carefully examine the contents of the upgraded databases. If you detect problems, you'll need to recover by restoring from your full pg_dumpall backup. You can delete the pg_upgrade_info/ directory when you are satisfied.

The upgraded databases will be in an un-vacuumed state. You will probably want to run a VACUUM ANALYZE before beginning production work.

SEE ALSO
initdb(1), postmaster(1), pg_dump(1), pg_dumpall(1), vacuumdb(1)