.\"
.TH PG_UPGRADE 1 "PG_UPGRADE(1)" "14 Jan 2002" "PostgreSQL Client Applications" ""
.SH NAME
pg_upgrade \- upgrading from a previous release without reloading
.SH SYNOPSIS
pg_upgrade [-D \fIdata_dir\fP] -1 | -2
.SH DESCRIPTION
\fBpg_upgrade\fP is a utility for upgrading from a previous PostgreSQL
release without reloading all the data. It can also be used as a data
recovery tool.
.LP
\fBpg_upgrade\fP must be run in two stages. In phase one you must run
\fBpg_upgrade\fP with your old database installation in place. In phase
two, \fBpg_upgrade\fP must be run on a freshly \fBinitdb\fP'ed server.
In both phases, the same newly installed \fBpg_upgrade\fP script must be
used.
.SH Upgrading PostgreSQL with pg_upgrade
.LP
1) Back up your existing data directory, preferably using
\fBpg_dumpall.\fP
.LP
2) Copy the program \fIpgsql/contrib/pg_upgrade/pg_upgrade\fP from the
current PostgreSQL distribution somewhere into your path.
.LP
3)  Run phase one of \fBpg_upgrade:\fP
.LP
.B $ pg_upgrade -1
.sp
to collect information about the old database needed for the upgrade.
You may use \fI-D\fP to specify the data directory. By default it uses
the environment variable \fIPGDATA.\fP
.LP
4) Do:
.LP
.B $ cd pgsql/src
.br
.B $ make install
.sp
to install the PostgreSQL binaries for the new release.
.LP
5)  Do:
.LP
.B $ cd pgsql/contrib/pg_resetxlog
.br
.B $ make install
.sp
to install the \fIpg_resetxlog\fP utility, which is needed during phase
2 of \fBpg_upgrade\fP.
.LP
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.
.LP
7) Start the new \fIpostmaster.\fP (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.)
.LP
8)  Run phase two of \fBpg_upgrade:\fP
.LP
.B $ pg_upgrade -2
.sp
The program will do some checking to make sure everything is properly
configured, and will then recreate all your databases and tables,
but with no data.  It will then physically move the data files
containing non-system tables and indexes into the proper 
subdirectories.
.LP
9)  Restore your old \fIpostmaster\fP flags or \fIpg_hba.conf\fP if
needed to allow user logins.
.sp
.LP
10) Carefully examine the contents of the upgraded databases. If you
detect problems, you'll need to recover by restoring from your full
\fBpg_dumpall\fP backup. You can delete the \fIpg_upgrade_info/\fP
directory when you are satisfied.
.LP
The upgraded databases will be in an un-vacuumed state. You will
probably want to run a \fIVACUUM ANALYZE\fP before beginning production
work.
.SH NOTES
While \fBpg_upgrade\fP is primarly an upgrade tool, it can also be used
for data recovery. During phase 1, \fBpg_upgrade\fP creates database
name / oid and database name / table name / oid mapping files in
\fIpg_upgrade_info/.\fP These files are tab-delimited. If your system is
too damaged, you may need to manually pull this information out of
\fBpg_database\fP and \fBpg_class\fP and create the files manually.
(Keep in mind most tables have \fBpg_toast_OID\fP and
\fBpg_toast_OID_idx\fP files that store very long values. These must be
recorded as well.) It also creates a schema-only \fBpg_dumpall.\fP In a
damaged installation, you may be able to make one of these from a recent
full \fBpg_dumpall.\fP
.LP
Phase 2 rebuilds each database with the schema from the old
installation. It then moves the physical data files from the old
installation and makes some modifications so the old data files work
properly in the new installation.
.SH SEE ALSO
initdb(1), postmaster(1), pg_dump(1), pg_dumpall(1), vacuumdb(1)