Add mention of recovery using pg_upgrade.

Author: bmomjian

contrib/pg_upgrade/README

@@ -7,7 +7,7 @@ PostgreSQL lists.
 
 Read the manual page for more information.  To view it:
 
-	nroff -man pg_upgrade.1 | $PAGER
+	nroff -man pg_upgrade.1 | more
 
 Bruce Momjian
 

contrib/pg_upgrade/pg_upgrade

@@ -3,7 +3,7 @@
 # pg_upgrade: update a database without needing a full dump/reload cycle.
 # CAUTION: Read the manual page before trying to use this!
 
-# $Header: /cvsroot/pgsql/contrib/pg_upgrade/Attic/pg_upgrade,v 1.10 2002/01/18 04:38:46 momjian Exp $
+# $Header: /cvsroot/pgsql/contrib/pg_upgrade/Attic/pg_upgrade,v 1.11 2002/01/31 19:13:53 momjian Exp $
 #
 # To migrate this to newer versions of PostgreSQL:  
 #	1)  Update the version numbers at the top of the file
@@ -184,7 +184,7 @@ then
 		exit 1
 	fi
 
-	# Start server, if needed, so we can do some work.
+	# If server is down, start it so we can do some work.
 	if ! pg_ctl status | sed -n '1p' | grep "is running" > /dev/null 2>&1
 	then	pg_ctl -w start
 		if [ $? -ne 0 ]
@@ -245,7 +245,8 @@ then
 	make_dbobjoidmap > "$INFODIR"/dbobjoidmap || exit "$?"
 
 	# Generate setval() script for 7.1 because it has int4 sequences
-	# Sequence XIDs changed from 7.2beta4 to beta5;  we have to recreate them.
+	# Sequence XIDs changed from 7.2beta4 to beta5 so we have to recreate them too.
+	# Not required for 7.2beta5 and later, but it can't hurt.
 	if [ "$SRC_VERSION" = "7.1" -o \
 	     "$SRC_VERSION" = "7.2" ]
 	then
@@ -427,7 +428,7 @@ then	echo "There were errors during VACUUM.  Exiting." 1>&2
 	exit 1
 fi
 
-# Generate mappings for database
+# Generate mappings for new database
 make_dboidmap > /tmp/$$.dboidmap || exit "$?"
 make_dbobjoidmap > /tmp/$$.dbobjoidmap || exit "$?"
 

contrib/pg_upgrade/pg_upgrade.1

@@ -5,29 +5,29 @@ 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. Not all PostgreSQL releases can use
-this utility.  Check the release notes for details about your
-version.
-.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.
+\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
+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.
+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
+You may use \fI-D\fP to specify the data directory. By default it uses
 the environment variable \fIPGDATA.\fP
 .LP
 4) Do:
@@ -51,9 +51,9 @@ to install the \fIpg_resetxlog\fP utility, which is needed during phase
 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.)
+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
@@ -69,15 +69,30 @@ subdirectories.
 needed to allow user logins.
 .sp
 .LP
-10)  Carefully examine the contents of the upgraded databases.  If you
+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.
+\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.
+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
-as a data recovery tool.
+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)