Add manual page to /contrib. SGML from docs.

contrib/pg_upgrade/pg_upgrade.man

@@ -0,0 +1,75 @@
+.TH PG_UPGRADE 1 "PG_UPGRADE(1)" "14 Jan 2002" "PostgreSQL Client Applications" ""
+.SH NAME
+pg_upgrade \- upgrade tool
+.SH SYNOPSIS
+Allows upgrading from a previous release without reloading data
+.SH DESCRIPTION
+pg_upgrade is a utility for upgrading from a previous PostgreSQL release
+without reloading all the data. Not all PostgreSQL releases can be
+handled this way.  Check the release notes for details about your
+version.
+.LP
+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.
+.SH Upgrading PostgreSQL with pg_upgrade
+.LP
+1) Back up your existing data directory, preferably by making a complete
+dump with pg_dumpall.
+.LP
+2) Copy the program pgsql/contrib/pg_upgrade/pg_upgrade from the current
+PostgreSQL distribution into somewhere in your path.
+.LP
+3)  Change your working directory to the  pgsql main directory, and type:
+.LP
+.B $ pg_upgrade -1
+.sp
+to collect information about the old database needed for the upgrade.
+.LP
+4) Do:
+.LP
+.B $ make install
+.sp
+to install the new binaries.
+.LP
+5)  Do:
+.LP
+.B $ cd pgsql/contrib/pg_resetxlog
+.br
+.B $ make install
+.sp
+to install the pg_resetxlog utility which is needed by
+pg_upgrade.
+.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 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 and/or alter pg_hba.conf temporarily.)
+.LP
+8)  Change your working directory to the  pgsql main directory, and type: 
+.LP
+.B $ pg_upgrade -2
+.sp
+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.
+.LP
+9)  Restore your old pg_hba.conf 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
+pg_dump backup. You can delete the pg_upgrade_info/ directory when you
+are satisfied.
+.LP
+The upgraded databases will be in an un-vacuumed state.  You will
+probably want to run a VACUUM ANALYZE before beginning production work.
+.SH SEE ALSO
+initdb(1), postmaster(1), pg_dump(1), pg_dumpall(1), vacuumdb(1)