Move upgrade instructions into its own section under "Server Setup and

Operation", merged from upgrade sections in "Installation from Source
Code" and "Backup and Restore".  This now gives a single place for all
upgrade information.

3 files changed, 304 insertions, 367 deletions

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 8b79b8f82f7..a461b0ac46a 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -1377,216 +1377,4 @@ archive_command = 'local_backup_script.sh'
   </sect2>
  </sect1>
 
- <sect1 id="migration">
-  <title>Migration Between Releases</title>
-
-  <indexterm zone="migration">
-   <primary>upgrading</primary>
-  </indexterm>
-
-  <indexterm zone="migration">
-   <primary>version</primary>
-   <secondary>compatibility</secondary>
-  </indexterm>
-
-  <para>
-   This section discusses how to migrate your database data from one
-   <productname>PostgreSQL</> release to a newer one.
-   The software installation procedure <foreignphrase>per se</> is not the
-   subject of this section; those details are in <xref linkend="installation">.
-  </para>
-
-  <para>
-   <productname>PostgreSQL</> major versions are represented by the
-   first two digit groups of the version number, e.g., 8.4.
-   <productname>PostgreSQL</> minor versions are represented by the
-   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, 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;
-   minor upgrades are that simple.
-  </para>
-
-  <para>
-   For <emphasis>major</> releases of <productname>PostgreSQL</>, the
-   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.)
-  </para>
-
-  <para>
-   It is recommended that you use the <application>pg_dump</> and
-   <application>pg_dumpall</> programs from the newer version of
-   <productname>PostgreSQL</>, to take advantage of enhancements
-   that might have been made in these programs.  Current releases of the
-   dump programs can read data from any server version back to 7.0.
-  </para>
-
-  <para>
-   The least downtime can be achieved by installing the new server in
-   a different directory and running both the old and the new servers
-   in parallel, on different ports. Then you can use something like:
-
-<programlisting>
-pg_dumpall -p 5432 | psql -d postgres -p 6543
-</programlisting>
-
-   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 those updates. See
-   <xref linkend="client-authentication"> for information on how to prohibit
-   access.
-  </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
-   the old server, move the old version out of the way, install the new
-   version, start the new server, and restore the data. For example:
-
-<programlisting>
-pg_dumpall &gt; backup
-pg_ctl stop
-mv /usr/local/pgsql /usr/local/pgsql.old
-# Rename any tablespace directories as well
-cd ~/postgresql-&version;
-gmake install
-initdb -D /usr/local/pgsql/data
-postgres -D /usr/local/pgsql/data
-psql -f backup postgres
-</programlisting>
-
-   See <xref linkend="runtime"> about ways to start and stop the
-   server and other details. The installation instructions will advise
-   you of strategic places to perform these steps.
-  </para>
-
-  <note>
-   <para>
-    When you <quote>move the old installation out of the way</quote>
-    it might no longer be perfectly usable. Some of the executable programs
-    contain absolute paths to various installed programs and data files.
-    This is usually not a big problem, but if you plan on using two
-    installations in parallel for a while you should assign them
-    different installation directories at build time.  (This problem
-    is rectified in <productname>PostgreSQL</> version 8.0 and later, so long
-    as you move all subdirectories containing installed files together;
-    for example if <filename>/usr/local/postgres/bin/</> goes to
-    <filename>/usr/local/postgres.old/bin/</>, then
-    <filename>/usr/local/postgres/share/</> must go to
-    <filename>/usr/local/postgres.old/share/</>.  In pre-8.0 releases
-    moving an installation like this will not work.)
-   </para>
-  </note>
-  </sect2>
-
-  <sect2 id="migration-methods-other">
-   <title>Other Data Migration Methods</title>
-
-  <para>
-   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>
-
-  <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>
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index b86581f2abb..0258eecda43 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -370,157 +370,6 @@ su - postgres
  </sect1>
 ]]>
 
- <sect1 id="install-upgrading">
-  <title>Upgrading</title>
-
-  <indexterm zone="install-upgrading">
-   <primary>upgrading</primary>
-  </indexterm>
-
-  <para>
-   These instructions assume that your existing installation is under the
-   <filename>/usr/local/pgsql</> directory, and that the data area is in
-   <filename>/usr/local/pgsql/data</>.  Substitute your paths
-   appropriately.
-  </para>
-
-  <para>
-   The internal data storage format typically changes in every major
-   release of <productname>PostgreSQL</>. Therefore, if you are upgrading
-   an existing installation that does not have a version number of
-   <quote>&majorversion;.x</quote>, you must back up and restore your
-   data.  If you are upgrading from <productname>PostgreSQL</>
-   <quote>&majorversion;.x</quote>, the new version can use your current
-   data files so you should skip the backup and restore steps below because
-   they are unnecessary.
-  </para>
-
-  <procedure>
-   <step>
-    <para>
-     If making a backup, make sure that your database is not being updated.
-     This does not affect the integrity of the backup, but the changed
-     data would of course not be included. If necessary, edit the
-     permissions in the file <filename>/usr/local/pgsql/data/pg_hba.conf</>
-     (or equivalent) to disallow access from everyone except you.
-    </para>
-
-    <para>
-     <indexterm>
-      <primary>pg_dumpall</primary>
-      <secondary>use during upgrade</secondary>
-     </indexterm>
-
-     To back up your database installation, type:
-<screen>
-<userinput>pg_dumpall &gt; <replaceable>outputfile</></userinput>
-</screen>
-     If you need to preserve OIDs (such as when using them as
-     foreign keys), then use the <option>-o</option> option when running
-     <application>pg_dumpall</>.
-    </para>
-
-    <para>
-     To make the backup, you can use the <application>pg_dumpall</application>
-     command from the version you are currently running.  For best
-     results, however, try to use the <application>pg_dumpall</application>
-     command from <productname>PostgreSQL</productname> &version;,
-     since this version contains bug fixes and improvements over older
-     versions.  While this advice might seem idiosyncratic since you
-     haven't installed the new version yet, it is advisable to follow
-     it if you plan to install the new version in parallel with the
-     old version.  In that case you can complete the installation
-     normally and transfer the data later.  This will also decrease
-     the downtime.
-    </para>
-   </step>
-
-   <step>
-    <para>
-     Shut down the old server:
-<screen>
-<userinput>pg_ctl stop</>
-</screen>
-     On systems that have <productname>PostgreSQL</> started at boot time,
-     there is probably a start-up file that will accomplish the same thing. For
-     example, on a <systemitem class="osname">Red Hat Linux</> system one
-     might find that this works:
-<screen>
-<userinput>/etc/rc.d/init.d/postgresql stop</userinput>
-</screen>
-    </para>
-   </step>
-
-   <step>
-    <para>
-     If restoring from backup, rename or delete the old installation
-     directory.  It is a good idea to rename the directory, rather than
-     delete it, in case you have trouble and need to revert to it.  Keep
-     in mind the directory might consume significant disk space.  To rename
-     the directory, use a command like this:
-<screen>
-<userinput>mv /usr/local/pgsql /usr/local/pgsql.old</>
-</screen>
-    </para>
-   </step>
-
-   <step>
-    <para>
-     Install the new version of <productname>PostgreSQL</productname> as
-     outlined in <![%standalone-include[the next section.]]>
-     <![%standalone-ignore[<xref linkend="install-procedure">.]]>
-    </para>
-   </step>
-
-   <step>
-    <para>
-     Create a new database cluster if needed.  Remember that you must
-     execute these commands while logged in to the special database user
-     account (which you already have if you are upgrading).
-<programlisting>
-<userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</>
-</programlisting>
-    </para>
-   </step>
-
-   <step>
-    <para>
-     Restore your previous <filename>pg_hba.conf</> and any
-     <filename>postgresql.conf</> modifications.
-    </para>
-   </step>
-
-   <step>
-    <para>
-     Start the database server, again using the special database user
-     account:
-<programlisting>
-<userinput>/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data</>
-</programlisting>
-    </para>
-   </step>
-
-   <step>
-    <para>
-     Finally, restore your data from backup with:
-<screen>
-<userinput>/usr/local/pgsql/bin/psql -d postgres -f <replaceable>outputfile</></userinput>
-</screen>
-     using the <emphasis>new</> <application>psql</>.
-    </para>
-   </step>
-  </procedure>
-
-  <para>
-   Further discussion appears in
-   <![%standalone-include[the documentation,]]>
-   <![%standalone-ignore[<xref linkend="migration">,]]>
-   including instructions on how the previous installation can continue
-   running while the new installation is installed.
-  </para>
- </sect1>
-
-
  <sect1 id="install-procedure">
   <title>Installation Procedure</title>
 
@@ -1618,10 +1467,9 @@ PostgreSQL, contrib and HTML documentation successfully made. Ready to install.
 
    <note>
     <para>
-     If you are upgrading an existing system and are going to install
-     the new files over the old ones, be sure to back up
-     your data and shut down the old server before proceeding, as explained in
-     <xref linkend="install-upgrading"> above.
+     If you are upgrading an existing system be sure to read <xref
+     linkend="upgrading"> which has instructions about upgrading a
+     cluster.
     </para>
    </note>
 
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index be409c20d46..42a2950aa61 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1418,6 +1418,307 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
   </para>
  </sect1>
 
+ <sect1 id="upgrading">
+  <title>Upgrading a <productname>PostgreSQL</> Cluster</title>
+
+  <indexterm zone="upgrading">
+   <primary>upgrading</primary>
+  </indexterm>
+
+  <indexterm zone="upgrading">
+   <primary>version</primary>
+   <secondary>compatibility</secondary>
+  </indexterm>
+
+  <para>
+   This section discusses how to upgrade your database data from one
+   <productname>PostgreSQL</> release to a newer one.
+  </para>
+
+  <para>
+   <productname>PostgreSQL</> major versions are represented by the
+   first two digit groups of the version number, e.g., 8.4.
+   <productname>PostgreSQL</> minor versions are represented by the
+   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, 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;
+   minor upgrades are that simple.
+  </para>
+
+  <para>
+   For <emphasis>major</> releases of <productname>PostgreSQL</>, the
+   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 methods are available,
+   as discussed below.
+  </para>
+
+  <para>
+   New major versions also typically introduce some user-visible
+   incompatibilities, so application programming changes might be required.
+   All user-visible changes are listed in the release notes (<xref
+   linkend="release">);  pay particular attention to the section
+   labeled "Migration".  If you are upgrading across several major
+   versions, be sure to read the release notes for each intervening
+   version.
+  </para>
+
+  <para>
+   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="upgrade-methods-pgdump">
+   <title>Upgrading 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.)
+   </para>
+
+   <para>
+    It is recommended that you use the <application>pg_dump</> and
+    <application>pg_dumpall</> programs from the newer version of
+    <productname>PostgreSQL</>, to take advantage of enhancements
+    that might have been made in these programs.  Current releases of the
+    dump programs can read data from any server version back to 7.0.
+   </para>
+
+   <para>
+    These instructions assume that your existing installation is under the
+    <filename>/usr/local/pgsql</> directory, and that the data area is in
+    <filename>/usr/local/pgsql/data</>.  Substitute your paths
+    appropriately.
+   </para>
+
+   <procedure>
+    <step>
+     <para>
+      If making a backup, make sure that your database is not being updated.
+      This does not affect the integrity of the backup, but the changed
+      data would of course not be included. If necessary, edit the
+      permissions in the file <filename>/usr/local/pgsql/data/pg_hba.conf</>
+      (or equivalent) to disallow access from everyone except you.
+      See <xref linkend="client-authentication"> for additional information on
+      access control.
+     </para>
+
+     <para>
+      <indexterm>
+       <primary>pg_dumpall</primary>
+       <secondary>use during upgrade</secondary>
+      </indexterm>
+
+      To back up your database installation, type:
+<screen>
+<userinput>pg_dumpall &gt; <replaceable>outputfile</></userinput>
+</screen>
+      If you need to preserve OIDs (such as when using them as
+      foreign keys), then use the <option>-o</option> option when running
+      <application>pg_dumpall</>.
+     </para>
+
+     <para>
+      To make the backup, you can use the <application>pg_dumpall</application>
+      command from the version you are currently running.  For best
+      results, however, try to use the <application>pg_dumpall</application>
+      command from <productname>PostgreSQL</productname> &version;,
+      since this version contains bug fixes and improvements over older
+      versions.  While this advice might seem idiosyncratic since you
+      haven't installed the new version yet, it is advisable to follow
+      it if you plan to install the new version in parallel with the
+      old version.  In that case you can complete the installation
+      normally and transfer the data later.  This will also decrease
+      the downtime.
+     </para>
+    </step>
+
+    <step>
+     <para>
+      Shut down the old server:
+<screen>
+<userinput>pg_ctl stop</>
+</screen>
+      On systems that have <productname>PostgreSQL</> started at boot time,
+      there is probably a start-up file that will accomplish the same thing. For
+      example, on a <systemitem class="osname">Red Hat Linux</> system one
+      might find that this works:
+<screen>
+<userinput>/etc/rc.d/init.d/postgresql stop</userinput>
+</screen>
+     </para>
+      See <xref linkend="runtime"> for details about starting and
+      stoping the server.
+    </step>
+
+    <step>
+     <para>
+      If restoring from backup, rename or delete the old installation
+      directory.  It is a good idea to rename the directory, rather than
+      delete it, in case you have trouble and need to revert to it.  Keep
+      in mind the directory might consume significant disk space.  To rename
+      the directory, use a command like this:
+<screen>
+<userinput>mv /usr/local/pgsql /usr/local/pgsql.old</>
+</screen>
+     (Be sure to move the directory as a single unit so relative paths
+     remain unchanged.)
+     </para>
+    </step>
+
+    <step>
+     <para>
+      Install the new version of <productname>PostgreSQL</productname> as
+      outlined in <![%standalone-include[the next section.]]>
+      <![%standalone-ignore[<xref linkend="install-procedure">.]]>
+     </para>
+    </step>
+
+    <step>
+     <para>
+      Create a new database cluster if needed.  Remember that you must
+      execute these commands while logged in to the special database user
+      account (which you already have if you are upgrading).
+<programlisting>
+<userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</>
+</programlisting>
+     </para>
+    </step>
+
+    <step>
+     <para>
+      Restore your previous <filename>pg_hba.conf</> and any
+      <filename>postgresql.conf</> modifications.
+     </para>
+    </step>
+
+    <step>
+     <para>
+      Start the database server, again using the special database user
+      account:
+<programlisting>
+<userinput>/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data</>
+</programlisting>
+     </para>
+    </step>
+
+    <step>
+     <para>
+      Finally, restore your data from backup with:
+<screen>
+<userinput>/usr/local/pgsql/bin/psql -d postgres -f <replaceable>outputfile</></userinput>
+</screen>
+      using the <emphasis>new</> <application>psql</>.
+     </para>
+    </step>
+   </procedure>
+
+   <para>
+    The least downtime can be achieved by installing the new server in
+    a different directory and running both the old and the new servers
+    in parallel, on different ports. Then you can use something like:
+
+<programlisting>
+pg_dumpall -p 5432 | psql -d postgres -p 5433
+</programlisting>
+    to transfer your data.
+   </para>
+
+  </sect2>
+
+  <sect2 id="upgrading-methods-other">
+   <title>Other data migration methods</title>
+
+   <para>
+    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>
+
+   <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>
+
  <sect1 id="preventing-server-spoofing">
   <title>Preventing Server Spoofing</title>