99 lines
3.6 KiB
Groff
99 lines
3.6 KiB
Groff
.\"
|
|
.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)
|