Assorted improvements to backup/restore documentation, per Thom Brown.

doc/src/sgml/backup.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.156 2010/06/07 02:01:08 itagaki Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.157 2010/08/15 23:04:49 tgl Exp $ -->
 
 <chapter id="backup">
  <title>Backup and Restore</title>
@@ -20,7 +20,8 @@
    <listitem><para>File system level backup</para></listitem>
    <listitem><para>Continuous archiving</para></listitem>
   </itemizedlist>
-  Each has its own strengths and weaknesses; each is discussed in turn below.
+  Each has its own strengths and weaknesses; each is discussed in turn
+  in the following sections.
  </para>
 
  <sect1 id="backup-dump">
@@ -73,6 +74,16 @@ pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable cl
    linkend="client-authentication">).
   </para>
 
+  <para>
+   An important advantage of <application>pg_dump</> over the other backup
+   methods described later is that <application>pg_dump</>'s output can
+   generally be re-loaded into newer versions of <productname>PostgreSQL</>,
+   whereas file-level backups and continuous archiving are both extremely
+   server-version-specific.  <application>pg_dump</> is also the only method
+   that will work when transferring a database to a different machine
+   architecture, such as going from a 32-bit to a 64-bit server.
+  </para>
+
   <para>
    Dumps created by <application>pg_dump</> are internally consistent,
    meaning, the dump represents a snapshot of the database at the time
@@ -490,7 +501,7 @@ tar -cf backup.tar /usr/local/pgsql/data
     <application>pg_dumpall</application> do not produce file-system-level
     backups and cannot be used as part of a continuous-archiving solution.
     Such dumps are <emphasis>logical</> and do not contain enough
-    information to used by WAL reply.
+    information to be used by WAL replay.
    </para>
   </note>
 
@@ -1373,12 +1384,12 @@ archive_command = 'local_backup_script.sh'
 
   <para>
    <productname>PostgreSQL</> major versions are represented by the
-   first two digit groups of the version number, e.g. 8.4.
+   first two digit groups of the version number, e.g., 8.4.
    <productname>PostgreSQL</> minor versions are represented by the
-   the third group of version digits, i.e., 8.4.2 is the second minor
+   third group of version digits, e.g., 8.4.2 is the second minor
    release of 8.4.  Minor releases never change the internal storage
    format and are always compatible with earlier and later minor
-   releases of the same major version number, i.e. 8.4.2 is compatible
+   releases of the same major version number, e.g., 8.4.2 is compatible
    with 8.4, 8.4.1 and 8.4.6.  To update between compatible versions,
    you simply replace the executables while the server is down and
    restart the server.  The data directory remains unchanged &mdash;
@@ -1387,14 +1398,86 @@ archive_command = 'local_backup_script.sh'
 
   <para>
    For <emphasis>major</> releases of <productname>PostgreSQL</>, the
-   internal data storage format is subject to change.  When migrating
-   data from one major version of <productname>PostgreSQL</> to another,
-   you need to back up your data and restore it on the new server.
-   This must be done using <application>pg_dump</>; file system level
-   backup methods will not work. There are checks in place that prevent
+   internal data storage format is subject to change, thus complicating
+   upgrades.  The traditional method for moving data to a new major version
+   is to dump and reload the database.  Other, less-well-tested possibilities
+   are available, as discussed below.
+  </para>
+
+  <para>
+   New major versions also typically introduce some user-visible
+   incompatibilities, so application programming changes may be required.
+   Cautious users will want to test their client applications on the new
+   version before switching over fully; therefore, it's often a good idea to
+   set up concurrent installations of old and new versions.  When
+   testing a <productname>PostgreSQL</> major upgrade, consider the
+   following categories of possible changes:
+  </para>
+
+  <variablelist>
+
+   <varlistentry>
+    <term>Administration</term>
+    <listitem>
+     <para>
+      The capabilities available for administrators to monitor and control
+      the server often change and improve in each major release.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term>SQL</term>
+    <listitem>
+     <para>
+      Typically this includes new SQL command capabilities and not changes
+      in behavior, unless specifically mentioned in the release notes.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term>Library API</term>
+    <listitem>
+     <para>
+      Typically libraries like <application>libpq</> only add new
+      functionality, again unless mentioned in the release notes.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term>System Catalogs</term>
+    <listitem>
+     <para>
+      System catalog changes usually only affect database management tools.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term>Server C-language API</term>
+    <listitem>
+     <para>
+      This involves changes in the backend function API, which is written
+      in the C programming language.  Such changes affect code that
+      references backend functions deep inside the server.
+     </para>
+    </listitem>
+   </varlistentry>
+
+  </variablelist>
+
+  <sect2 id="migration-methods-pgdump">
+   <title>Migrating data via <application>pg_dump</></title>
+
+  <para>
+   To dump data from one major version of <productname>PostgreSQL</> and
+   reload it in another, you must use <application>pg_dump</>; file system
+   level backup methods will not work. (There are checks in place that prevent
    you from using a data directory with an incompatible version of
-   <productname>PostgreSQL</productname>, so no great harm can be done
-   by trying to start the wrong server version on a data directory.
+   <productname>PostgreSQL</productname>, so no great harm can be done by
+   trying to start the wrong server version on a data directory.)
   </para>
 
   <para>
@@ -1414,26 +1497,15 @@ archive_command = 'local_backup_script.sh'
 pg_dumpall -p 5432 | psql -d postgres -p 6543
 </programlisting>
 
-   to transfer your data.  Or use an intermediate file if you wish.
+   to transfer your data.  Or you can use an intermediate file if you wish.
    Then you can shut down the old server and start the new server using
    the port the old one was running on. You should make sure that the
    old database is not updated after you begin to run
-   <application>pg_dumpall</>, otherwise you will lose that data. See <xref
-   linkend="client-authentication"> for information on how to prohibit
+   <application>pg_dumpall</>, otherwise you will lose those updates. See
+   <xref linkend="client-authentication"> for information on how to prohibit
    access.
   </para>
 
-  <para>
-   It is also possible to use replication methods, such as
-   <productname>Slony</>, to create a standby server with the updated version of
-   <productname>PostgreSQL</>.  The standby can be on the same computer or
-   a different computer.  Once it has synced up with the master server
-   (running the older version of <productname>PostgreSQL</>), you can
-   switch masters and make the standby the master and shut down the older
-   database instance.  Such a switch-over results in only several seconds
-   of downtime for an upgrade.
-  </para>
-
   <para>
    If you cannot or do not want to run two servers in parallel, you can
    do the backup step before installing the new version, bring down
@@ -1474,68 +1546,33 @@ psql -f backup postgres
     moving an installation like this will not work.)
    </para>
   </note>
+  </sect2>
+
+  <sect2 id="migration-methods-other">
+   <title>Other data migration methods</title>
 
   <para>
-   In practice you probably want to test your client applications on the
-   new version before switching over completely.  This is another reason
-   for setting up concurrent installations of old and new versions.  When
-   testing a <productname>PostgreSQL</> major upgrade, consider the
-   following categories of possible changes:
+   The <filename>contrib</> program
+   <link linkend="pgupgrade"><application>pg_upgrade</application></link>
+   allows an installation to be migrated in-place from one major
+   <productname>PostgreSQL</> version to the next.  Keep in mind that this
+   method does not provide any scope for running old and new versions
+   concurrently.  Also, <application>pg_upgrade</application> is much less
+   battle-tested than <application>pg_dump</application>, so having an
+   up-to-date backup is strongly recommended in case something goes wrong.
   </para>
 
-  <variablelist>
-
-   <varlistentry>
-    <term>Administration</term>
-    <listitem>
-     <para>
-      The capabilities available for administrators to monitor and control
-      the server often change and improve in each major release.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>SQL</term>
-    <listitem>
-     <para>
-      Typically this includes new SQL command capabilities and not changes
-      in behavior, unless specifically mentioned in the release notes.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>Library API</term>
-    <listitem>
-     <para>
-      Typically libraries like <application>libpq</> only add new
-      functionality, again unless mentioned in the release notes.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>System Catalogs</term>
-    <listitem>
-     <para>
-      System catalog changes usually only affect database management tools.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>Server C-language API</term>
-    <listitem>
-     <para>
-      This involved changes in the backend function API, which is written
-      in the C programming language.  Such changes effect code that
-      references backend functions deep inside the server.
-     </para>
-    </listitem>
-   </varlistentry>
-
-  </variablelist>
+  <para>
+   It is also possible to use certain replication methods, such as
+   <productname>Slony</>, to create a standby server with the updated version of
+   <productname>PostgreSQL</>.  The standby can be on the same computer or
+   a different computer.  Once it has synced up with the master server
+   (running the older version of <productname>PostgreSQL</>), you can
+   switch masters and make the standby the master and shut down the older
+   database instance.  Such a switch-over results in only several seconds
+   of downtime for an upgrade.
+  </para>
 
+  </sect2>
  </sect1>
 </chapter>