Adding upstream version 14.5.upstream/14.5upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 849 insertions, 0 deletions

diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
new file mode 100644
index 0000000..9866210
--- /dev/null
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -0,0 +1,849 @@
+<!--
+doc/src/sgml/ref/pgupgrade.sgml
+PostgreSQL documentation
+-->
+
+<refentry id="pgupgrade">
+ <indexterm zone="pgupgrade">
+  <primary>pg_upgrade</primary>
+ </indexterm>
+
+ <refmeta>
+  <refentrytitle><application>pg_upgrade</application></refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo>Application</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+  <refname>pg_upgrade</refname>
+  <refpurpose>upgrade a <productname>PostgreSQL</productname> server instance</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+  <cmdsynopsis>
+   <command>pg_upgrade</command>
+   <arg choice="plain"><option>-b</option></arg>
+   <arg choice="plain"><replaceable>oldbindir</replaceable></arg>
+   <arg choice="opt"><option>-B</option> <replaceable>newbindir</replaceable></arg>
+   <arg choice="plain"><option>-d</option></arg>
+   <arg choice="plain"><replaceable>oldconfigdir</replaceable></arg>
+   <arg choice="plain"><option>-D</option></arg>
+   <arg choice="plain"><replaceable>newconfigdir</replaceable></arg>
+   <arg rep="repeat"><replaceable>option</replaceable></arg>
+  </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+  <title>Description</title>
+
+ <para>
+  <application>pg_upgrade</application> (formerly called <application>pg_migrator</application>) allows data
+  stored in <productname>PostgreSQL</productname> data files to be upgraded to a later <productname>PostgreSQL</productname>
+  major version without the data dump/restore typically required for
+  major version upgrades, e.g., from 9.5.8 to 9.6.4 or from 10.7 to 11.2.
+  It is not required for minor version upgrades, e.g., from 9.6.2 to 9.6.3
+  or from 10.1 to 10.2.
+ </para>
+
+ <para>
+  Major PostgreSQL releases regularly add new features that often
+  change the layout of the system tables, but the internal data storage
+  format rarely changes.  <application>pg_upgrade</application> uses this fact
+  to perform rapid upgrades by creating new system tables and simply
+  reusing the old user data files.  If a future major release ever
+  changes the data storage format in a way that makes the old data
+  format unreadable, <application>pg_upgrade</application> will not be usable
+  for such upgrades.  (The community will attempt to avoid such
+  situations.)
+ </para>
+
+ <para>
+  <application>pg_upgrade</application> does its best to
+  make sure the old and new clusters are binary-compatible, e.g.,  by
+  checking for compatible compile-time settings, including 32/64-bit
+  binaries.  It is important that
+  any external modules are also binary compatible, though this cannot
+  be checked by <application>pg_upgrade</application>.
+ </para>
+
+  <para>
+   pg_upgrade supports upgrades from 8.4.X and later to the current
+   major release of <productname>PostgreSQL</productname>, including snapshot and beta releases.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Options</title>
+
+   <para>
+    <application>pg_upgrade</application> accepts the following command-line arguments:
+
+    <variablelist>
+
+     <varlistentry>
+      <term><option>-b</option> <replaceable>bindir</replaceable></term>
+      <term><option>--old-bindir=</option><replaceable>bindir</replaceable></term>
+      <listitem><para>the old PostgreSQL executable directory;
+      environment variable <envar>PGBINOLD</envar></para></listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-B</option> <replaceable>bindir</replaceable></term>
+      <term><option>--new-bindir=</option><replaceable>bindir</replaceable></term>
+      <listitem><para>the new PostgreSQL executable directory;
+      default is the directory where <application>pg_upgrade</application> resides;
+      environment variable <envar>PGBINNEW</envar></para></listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-c</option></term>
+      <term><option>--check</option></term>
+      <listitem><para>check clusters only, don't change any data</para></listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-d</option> <replaceable>configdir</replaceable></term>
+      <term><option>--old-datadir=</option><replaceable>configdir</replaceable></term>
+      <listitem><para>the old database cluster configuration directory; environment
+      variable <envar>PGDATAOLD</envar></para></listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-D</option> <replaceable>configdir</replaceable></term>
+      <term><option>--new-datadir=</option><replaceable>configdir</replaceable></term>
+      <listitem><para>the new database cluster configuration directory; environment
+      variable <envar>PGDATANEW</envar></para></listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-j <replaceable class="parameter">njobs</replaceable></option></term>
+      <term><option>--jobs=<replaceable class="parameter">njobs</replaceable></option></term>
+      <listitem><para>number of simultaneous processes or threads to use
+      </para></listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-k</option></term>
+      <term><option>--link</option></term>
+      <listitem><para>use hard links instead of copying files to the new
+      cluster</para></listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-o</option> <replaceable class="parameter">options</replaceable></term>
+      <term><option>--old-options</option> <replaceable class="parameter">options</replaceable></term>
+      <listitem><para>options to be passed directly to the
+      old <command>postgres</command> command;  multiple
+      option invocations are appended</para></listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-O</option> <replaceable class="parameter">options</replaceable></term>
+      <term><option>--new-options</option> <replaceable class="parameter">options</replaceable></term>
+      <listitem><para>options to be passed directly to the
+      new <command>postgres</command> command;  multiple
+      option invocations are appended</para></listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-p</option> <replaceable>port</replaceable></term>
+      <term><option>--old-port=</option><replaceable>port</replaceable></term>
+      <listitem><para>the old cluster port number; environment
+      variable <envar>PGPORTOLD</envar></para></listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-P</option> <replaceable>port</replaceable></term>
+      <term><option>--new-port=</option><replaceable>port</replaceable></term>
+      <listitem><para>the new cluster port number; environment
+      variable <envar>PGPORTNEW</envar></para></listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-r</option></term>
+      <term><option>--retain</option></term>
+      <listitem><para>retain SQL and log files even after successful completion
+      </para></listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-s</option> <replaceable>dir</replaceable></term>
+      <term><option>--socketdir=</option><replaceable>dir</replaceable></term>
+      <listitem><para>directory to use for postmaster sockets during upgrade;
+      default is current working directory; environment
+      variable <envar>PGSOCKETDIR</envar></para></listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-U</option> <replaceable>username</replaceable></term>
+      <term><option>--username=</option><replaceable>username</replaceable></term>
+      <listitem><para>cluster's install user name; environment
+      variable <envar>PGUSER</envar></para></listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-v</option></term>
+      <term><option>--verbose</option></term>
+      <listitem><para>enable verbose internal logging</para></listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-V</option></term>
+      <term><option>--version</option></term>
+      <listitem><para>display version information, then exit</para></listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>--clone</option></term>
+      <listitem>
+       <para>
+        Use efficient file cloning (also known as <quote>reflinks</quote> on
+        some systems) instead of copying files to the new cluster.  This can
+        result in near-instantaneous copying of the data files, giving the
+        speed advantages of <option>-k</option>/<option>--link</option> while
+        leaving the old cluster untouched.
+       </para>
+
+       <para>
+        File cloning is only supported on some operating systems and file
+        systems.  If it is selected but not supported, the
+        <application>pg_upgrade</application> run will error.  At present, it
+        is supported on Linux (kernel 4.5 or later) with Btrfs and XFS (on
+        file systems created with reflink support), and on macOS with APFS.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-?</option></term>
+      <term><option>--help</option></term>
+      <listitem><para>show help, then exit</para></listitem>
+     </varlistentry>
+
+    </variablelist>
+   </para>
+
+ </refsect1>
+
+ <refsect1>
+  <title>Usage</title>
+
+  <para>
+   These are the steps to perform an upgrade
+   with <application>pg_upgrade</application>:
+  </para>
+
+  <procedure>
+   <step performance="optional">
+    <title>Optionally move the old cluster</title>
+
+    <para>
+     If you are using a version-specific installation directory, e.g.,
+     <filename>/opt/PostgreSQL/&majorversion;</filename>, you do not need to move the old cluster. The
+     graphical installers all use version-specific installation directories.
+    </para>
+
+    <para>
+     If your installation directory is not version-specific, e.g.,
+     <filename>/usr/local/pgsql</filename>, it is necessary to move the current PostgreSQL install
+     directory so it does not interfere with the new <productname>PostgreSQL</productname> installation.
+     Once the current <productname>PostgreSQL</productname> server is shut down, it is safe to rename the
+     PostgreSQL installation directory; assuming the old directory is
+     <filename>/usr/local/pgsql</filename>, you can do:
+
+<programlisting>
+mv /usr/local/pgsql /usr/local/pgsql.old
+</programlisting>
+     to rename the directory.
+    </para>
+   </step>
+
+   <step>
+    <title>For source installs, build the new version</title>
+
+    <para>
+     Build the new PostgreSQL source with <command>configure</command> flags that are compatible
+     with the old cluster. <application>pg_upgrade</application> will check <command>pg_controldata</command> to make
+     sure all settings are compatible before starting the upgrade.
+    </para>
+   </step>
+
+   <step>
+    <title>Install the new PostgreSQL binaries</title>
+
+    <para>
+     Install the new server's binaries and support
+     files.  <application>pg_upgrade</application> is included in a default installation.
+    </para>
+
+    <para>
+     For source installs, if you wish to install the new server in a custom
+     location, use the <literal>prefix</literal> variable:
+
+<programlisting>
+make prefix=/usr/local/pgsql.new install
+</programlisting></para>
+   </step>
+
+   <step>
+    <title>Initialize the new PostgreSQL cluster</title>
+
+    <para>
+     Initialize the new cluster using <command>initdb</command>.
+     Again, use compatible <command>initdb</command>
+     flags that match the old cluster. Many
+     prebuilt installers do this step automatically. There is no need to
+     start the new cluster.
+    </para>
+   </step>
+
+   <step>
+    <title>Install extension shared object files</title>
+
+    <para>
+     Many extensions and custom modules, whether from
+     <filename>contrib</filename> or another source, use shared object
+     files (or DLLs), e.g., <filename>pgcrypto.so</filename>.  If the old
+     cluster used these, shared object files matching the new server binary
+     must be installed in the new cluster, usually via operating system
+     commands.  Do not load the schema definitions, e.g., <command>CREATE
+     EXTENSION pgcrypto</command>, because these will be duplicated from
+     the old cluster.  If extension updates are available,
+     <application>pg_upgrade</application> will report this and create
+     a script that can be run later to update them.
+    </para>
+   </step>
+
+   <step>
+    <title>Copy custom full-text search files</title>
+
+    <para>
+     Copy any custom full text search files (dictionary, synonym,
+     thesaurus, stop words) from the old to the new cluster.
+    </para>
+   </step>
+
+   <step>
+    <title>Adjust authentication</title>
+
+    <para>
+     <command>pg_upgrade</command> will connect to the old and new servers several
+     times, so you might want to set authentication to <literal>peer</literal>
+     in <filename>pg_hba.conf</filename> or use a <filename>~/.pgpass</filename> file
+     (see <xref linkend="libpq-pgpass"/>).
+    </para>
+   </step>
+
+   <step>
+    <title>Stop both servers</title>
+
+    <para>
+     Make sure both database servers are stopped using, on Unix, e.g.:
+
+<programlisting>
+pg_ctl -D /opt/PostgreSQL/9.6 stop
+pg_ctl -D /opt/PostgreSQL/&majorversion; stop
+</programlisting>
+
+     or on Windows, using the proper service names:
+
+<programlisting>
+NET STOP postgresql-9.6
+NET STOP postgresql-&majorversion;
+</programlisting>
+    </para>
+
+    <para>
+     Streaming replication and log-shipping standby servers can
+     remain running until a later step.
+    </para>
+   </step>
+
+   <step>
+    <title>Prepare for standby server upgrades</title>
+
+    <para>
+     If you are upgrading standby servers using methods outlined in section <xref
+     linkend="pgupgrade-step-replicas"/>, verify that the old standby
+     servers are caught up by running <application>pg_controldata</application>
+     against the old primary and standby clusters.  Verify that the
+     <quote>Latest checkpoint location</quote> values match in all clusters.
+     (There will be a mismatch if old standby servers were shut down
+     before the old primary or if the old standby servers are still running.)
+     Also, make sure <varname>wal_level</varname> is not set to
+     <literal>minimal</literal> in the <filename>postgresql.conf</filename> file on the
+     new primary cluster.
+    </para>
+   </step>
+
+   <step>
+    <title>Run <application>pg_upgrade</application></title>
+
+    <para>
+     Always run the <application>pg_upgrade</application> binary of the new server, not the old one.
+     <application>pg_upgrade</application> requires the specification of the old and new cluster's
+     data and executable (<filename>bin</filename>) directories. You can also specify
+     user and port values, and whether you want the data files linked or cloned
+     instead of the default copy behavior.
+    </para>
+
+    <para>
+     If you use link mode, the upgrade will be much faster (no file
+     copying) and use less disk space, but you will not be able to access
+     your old cluster
+     once you start the new cluster after the upgrade.  Link mode also
+     requires that the old and new cluster data directories be in the
+     same file system.  (Tablespaces and <filename>pg_wal</filename> can be on
+     different file systems.)
+     Clone mode provides the same speed and disk space advantages but
+     does not cause the old cluster to be unusable once the new cluster
+     is started.  Clone mode also requires that the old and new data
+     directories be in the same file system.  This mode is only available
+     on certain operating systems and file systems.
+    </para>
+
+    <para>
+     The <option>--jobs</option> option allows multiple CPU cores to be used
+     for copying/linking of files and to dump and restore database schemas
+     in parallel;  a good place to start is the maximum of the number of
+     CPU cores and tablespaces.  This option can dramatically reduce the
+     time to upgrade a multi-database server running on a multiprocessor
+     machine.
+    </para>
+
+    <para>
+     For Windows users, you must be logged into an administrative account, and
+     then start a shell as the <literal>postgres</literal> user and set the proper path:
+
+<programlisting>
+RUNAS /USER:postgres "CMD.EXE"
+SET PATH=%PATH%;C:\Program Files\PostgreSQL\&majorversion;\bin;
+</programlisting>
+
+     and then run <application>pg_upgrade</application> with quoted directories, e.g.:
+
+<programlisting>
+pg_upgrade.exe
+        --old-datadir "C:/Program Files/PostgreSQL/9.6/data"
+        --new-datadir "C:/Program Files/PostgreSQL/&majorversion;/data"
+        --old-bindir "C:/Program Files/PostgreSQL/9.6/bin"
+        --new-bindir "C:/Program Files/PostgreSQL/&majorversion;/bin"
+</programlisting>
+
+     Once started, <command>pg_upgrade</command> will verify the two clusters are compatible
+     and then do the upgrade. You can use <command>pg_upgrade --check</command>
+     to perform only the checks, even if the old server is still
+     running. <command>pg_upgrade --check</command> will also outline any
+     manual adjustments you will need to make after the upgrade.  If you
+     are going to be using link or clone mode, you should use the option
+     <option>--link</option> or <option>--clone</option> with
+     <option>--check</option> to enable mode-specific checks.
+     <command>pg_upgrade</command> requires write permission in the current directory.
+    </para>
+
+    <para>
+     Obviously, no one should be accessing the clusters during the
+     upgrade.  <application>pg_upgrade</application> defaults to running servers
+     on port 50432 to avoid unintended client connections.
+     You can use the same port number for both clusters when doing an
+     upgrade because the old and new clusters will not be running at the
+     same time.  However, when checking an old running server, the old
+     and new port numbers must be different.
+    </para>
+
+    <para>
+     If an error occurs while restoring the database schema, <command>pg_upgrade</command> will
+     exit and you will have to revert to the old cluster as outlined in <xref linkend="pgupgrade-step-revert"/>
+     below. To try <command>pg_upgrade</command> again, you will need to modify the old
+     cluster so the pg_upgrade schema restore succeeds. If the problem is a
+     <filename>contrib</filename> module, you might need to uninstall the <filename>contrib</filename> module from
+     the old cluster and install it in the new cluster after the upgrade,
+     assuming the module is not being used to store user data.
+    </para>
+   </step>
+
+   <step id="pgupgrade-step-replicas">
+    <title>Upgrade streaming replication and log-shipping standby servers</title>
+
+    <para>
+     If you used link mode and have Streaming Replication (see <xref
+     linkend="streaming-replication"/>) or Log-Shipping (see <xref
+     linkend="warm-standby"/>) standby servers, you can follow these steps to
+     quickly upgrade them.  You will not be running <application>pg_upgrade</application> on
+     the standby servers, but rather <application>rsync</application> on the primary.
+     Do not start any servers yet.
+    </para>
+
+    <para>
+     If you did <emphasis>not</emphasis> use link mode, do not have or do not
+     want to use <application>rsync</application>, or want an easier solution, skip
+     the instructions in this section and simply recreate the standby
+     servers once <application>pg_upgrade</application> completes and the new primary
+     is running.
+    </para>
+
+    <substeps>
+
+     <step>
+      <title>Install the new PostgreSQL binaries on standby servers</title>
+
+      <para>
+       Make sure the new binaries and support files are installed on all
+       standby servers.
+      </para>
+     </step>
+
+     <step>
+      <title>Make sure the new standby data directories do <emphasis>not</emphasis> exist</title>
+
+      <para>
+       Make sure the new standby data directories do <emphasis>not</emphasis>
+       exist or are empty.  If <application>initdb</application> was run, delete
+       the standby servers' new data directories.
+      </para>
+     </step>
+
+     <step>
+      <title>Install extension shared object files</title>
+
+      <para>
+       Install the same extension shared object files on the new standbys
+       that you installed in the new primary cluster.
+      </para>
+     </step>
+
+     <step>
+      <title>Stop standby servers</title>
+
+      <para>
+       If the standby servers are still running, stop them now using the
+       above instructions.
+      </para>
+     </step>
+
+     <step>
+      <title>Save configuration files</title>
+
+      <para>
+       Save any configuration files from the old standbys' configuration
+       directories you need to keep, e.g.,  <filename>postgresql.conf</filename>
+       (and any files included by it), <filename>postgresql.auto.conf</filename>,
+       <literal>pg_hba.conf</literal>, because these will be overwritten
+       or removed in the next step.
+      </para>
+     </step>
+
+     <step>
+      <title>Run <application>rsync</application></title>
+
+      <para>
+       When using link mode, standby servers can be quickly upgraded using
+       <application>rsync</application>.  To accomplish this, from a directory on
+       the primary server that is above the old and new database cluster
+       directories, run this on the <emphasis>primary</emphasis> for each standby
+       server:
+
+<programlisting>
+rsync --archive --delete --hard-links --size-only --no-inc-recursive old_cluster new_cluster remote_dir
+</programlisting>
+
+       where <option>old_cluster</option> and <option>new_cluster</option> are relative
+       to the current directory on the primary, and <option>remote_dir</option>
+       is <emphasis>above</emphasis> the old and new cluster directories
+       on the standby.  The directory structure under the specified
+       directories on the primary and standbys must match.  Consult the
+       <application>rsync</application> manual page for details on specifying the
+       remote directory, e.g.,
+
+<programlisting>
+rsync --archive --delete --hard-links --size-only --no-inc-recursive /opt/PostgreSQL/9.5 \
+      /opt/PostgreSQL/9.6 standby.example.com:/opt/PostgreSQL
+</programlisting>
+
+       You can verify what the command will do using
+       <application>rsync</application>'s <option>--dry-run</option> option.  While
+       <application>rsync</application> must be run on the primary for at least one
+       standby, it is possible to run <application>rsync</application> on an upgraded
+       standby to upgrade other standbys, as long as the upgraded standby
+       has not been started.
+      </para>
+
+      <para>
+       What this does is to record the links created by
+       <application>pg_upgrade</application>'s link mode that connect files in the
+       old and new clusters on the primary server.  It then finds matching
+       files in the standby's old cluster and creates links for them in the
+       standby's new cluster.  Files that were not linked on the primary
+       are copied from the primary to the standby.  (They are usually
+       small.)  This provides rapid standby upgrades.  Unfortunately,
+       <application>rsync</application> needlessly copies files associated with
+       temporary and unlogged tables because these files don't normally
+       exist on standby servers.
+      </para>
+
+      <para>
+       If you have tablespaces, you will need to run a similar
+       <application>rsync</application> command for each tablespace directory, e.g.:
+
+<programlisting>
+rsync --archive --delete --hard-links --size-only --no-inc-recursive /vol1/pg_tblsp/PG_9.5_201510051 \
+      /vol1/pg_tblsp/PG_9.6_201608131 standby.example.com:/vol1/pg_tblsp
+</programlisting>
+
+       If you have relocated <filename>pg_wal</filename> outside the data
+       directories, <application>rsync</application> must be run on those directories
+       too.
+      </para>
+     </step>
+
+     <step>
+      <title>Configure streaming replication and log-shipping standby servers</title>
+
+      <para>
+       Configure the servers for log shipping.  (You do not need to run
+       <function>pg_start_backup()</function> and <function>pg_stop_backup()</function>
+       or take a file system backup as the standbys are still synchronized
+       with the primary.)  Replication slots are not copied and must
+       be recreated.
+      </para>
+     </step>
+
+    </substeps>
+
+   </step>
+
+   <step>
+    <title>Restore <filename>pg_hba.conf</filename></title>
+
+    <para>
+     If you modified <filename>pg_hba.conf</filename>, restore its original settings.
+     It might also be necessary to adjust other configuration files in the new
+     cluster to match the old cluster, e.g., <filename>postgresql.conf</filename>
+     (and any files included by it), <filename>postgresql.auto.conf</filename>.
+    </para>
+   </step>
+
+   <step>
+    <title>Start the new server</title>
+
+    <para>
+     The new server can now be safely started, and then any
+     <application>rsync</application>'ed standby servers.
+    </para>
+   </step>
+
+   <step>
+    <title>Post-upgrade processing</title>
+
+    <para>
+     If any post-upgrade processing is required, pg_upgrade will issue
+     warnings as it completes. It will also generate script files that must
+     be run by the administrator. The script files will connect to each
+     database that needs post-upgrade processing. Each script should be
+     run using:
+
+<programlisting>
+psql --username=postgres --file=script.sql postgres
+</programlisting>
+
+     The scripts can be run in any order and can be deleted once they have
+     been run.
+    </para>
+
+    <caution>
+    <para>
+     In general it is unsafe to access tables referenced in rebuild scripts
+     until the rebuild scripts have run to completion; doing so could yield
+     incorrect results or poor performance. Tables not referenced in rebuild
+     scripts can be accessed immediately.
+    </para>
+    </caution>
+   </step>
+
+   <step>
+    <title>Statistics</title>
+
+    <para>
+     Because optimizer statistics are not transferred by <command>pg_upgrade</command>, you will
+     be instructed to run a command to regenerate that information at the end
+     of the upgrade.  You might need to set connection parameters to
+     match your new cluster.
+    </para>
+   </step>
+
+   <step>
+    <title>Delete old cluster</title>
+
+    <para>
+     Once you are satisfied with the upgrade, you can delete the old
+     cluster's data directories by running the script mentioned when
+     <command>pg_upgrade</command> completes. (Automatic deletion is not
+     possible if you have user-defined tablespaces inside the old data
+     directory.)  You can also delete the old installation directories
+     (e.g., <filename>bin</filename>, <filename>share</filename>).
+    </para>
+   </step>
+
+   <step id="pgupgrade-step-revert" performance="optional">
+    <title>Reverting to old cluster</title>
+
+    <para>
+     If, after running <command>pg_upgrade</command>, you wish to revert to the old cluster,
+     there are several options:
+
+     <itemizedlist>
+      <listitem>
+       <para>
+        If the <option>--check</option> option was used, the old cluster
+        was unmodified;  it can be restarted.
+       </para>
+      </listitem>
+
+      <listitem>
+       <para>
+        If the <option>--link</option> option was <emphasis>not</emphasis>
+        used, the old cluster was unmodified;  it can be restarted.
+       </para>
+      </listitem>
+
+      <listitem>
+       <para>
+        If the <option>--link</option> option was used, the data
+        files might be shared between the old and new cluster:
+
+        <itemizedlist>
+         <listitem>
+          <para>
+           If <command>pg_upgrade</command> aborted before linking started,
+           the old cluster was unmodified;  it can be restarted.
+          </para>
+         </listitem>
+
+         <listitem>
+          <para>
+           If you did <emphasis>not</emphasis> start the new cluster, the old
+           cluster was unmodified except that, when linking started, a
+           <literal>.old</literal> suffix was appended to
+           <filename>$PGDATA/global/pg_control</filename>.  To reuse the old
+           cluster, remove the <filename>.old</filename> suffix from
+           <filename>$PGDATA/global/pg_control</filename>; you can then restart
+           the old cluster.
+          </para>
+         </listitem>
+
+         <listitem>
+          <para>
+           If you did start the new cluster, it has written to shared files
+           and it is unsafe to use the old cluster.  The old cluster will
+           need to be restored from backup in this case.
+          </para>
+         </listitem>
+
+        </itemizedlist></para>
+      </listitem>
+     </itemizedlist></para>
+   </step>
+  </procedure>
+
+ </refsect1>
+
+ <refsect1>
+  <title>Notes</title>
+
+  <para>
+   <application>pg_upgrade</application> creates various working files, such
+   as schema dumps, in the current working directory.  For security, be sure
+   that that directory is not readable or writable by any other users.
+  </para>
+
+  <para>
+   <application>pg_upgrade</application> launches short-lived postmasters in
+   the old and new data directories.  Temporary Unix socket files for
+   communication with these postmasters are, by default, made in the current
+   working directory.  In some situations the path name for the current
+   directory might be too long to be a valid socket name.  In that case you
+   can use the <option>-s</option> option to put the socket files in some
+   directory with a shorter path name.  For security, be sure that that
+   directory is not readable or writable by any other users.
+   (This is not supported on Windows.)
+  </para>
+
+  <para>
+   All failure, rebuild, and reindex cases will be reported by
+   <application>pg_upgrade</application> if they affect your installation;
+   post-upgrade scripts to rebuild tables and indexes will be
+   generated automatically.  If you are trying to automate the upgrade
+   of many clusters, you should find that clusters with identical database
+   schemas require the same post-upgrade steps for all cluster upgrades;
+   this is because the post-upgrade steps are based on the database
+   schemas, and not user data.
+  </para>
+
+  <para>
+   For deployment testing, create a schema-only copy of the old cluster,
+   insert dummy data, and upgrade that.
+  </para>
+
+  <para>
+   <application>pg_upgrade</application> does not support upgrading of databases
+   containing table columns using these <type>reg*</type> OID-referencing system data types:
+   <simplelist>
+    <member><type>regcollation</type></member>
+    <member><type>regconfig</type></member>
+    <member><type>regdictionary</type></member>
+    <member><type>regnamespace</type></member>
+    <member><type>regoper</type></member>
+    <member><type>regoperator</type></member>
+    <member><type>regproc</type></member>
+    <member><type>regprocedure</type></member>
+   </simplelist>
+   (<type>regclass</type>, <type>regrole</type>, and <type>regtype</type> can be upgraded.)
+  </para>
+
+  <para>
+   If you are upgrading a pre-<productname>PostgreSQL</productname> 9.2 cluster
+   that uses a configuration-file-only directory, you must pass the
+   real data directory location to <application>pg_upgrade</application>, and
+   pass the configuration directory location to the server, e.g.,
+   <literal>-d /real-data-directory -o '-D /configuration-directory'</literal>.
+  </para>
+
+  <para>
+   If using a pre-9.1 old server that is using a non-default Unix-domain
+   socket directory or a default that differs from the default of the
+   new cluster, set <envar>PGHOST</envar> to point to the old server's socket
+   location.  (This is not relevant on Windows.)
+  </para>
+
+  <para>
+   If you want to use link mode and you do not want your old cluster
+   to be modified when the new cluster is started, consider using the clone mode.
+   If that is not available, make a copy of the
+   old cluster and upgrade that in link mode. To make a valid copy
+   of the old cluster, use <command>rsync</command> to create a dirty
+   copy of the old cluster while the server is running, then shut down
+   the old server and run <command>rsync --checksum</command> again to update the
+   copy with any changes to make it consistent.  (<option>--checksum</option>
+   is necessary because <command>rsync</command> only has file modification-time
+   granularity of one second.)  You might want to exclude some
+   files, e.g., <filename>postmaster.pid</filename>, as documented in <xref
+   linkend="backup-lowlevel-base-backup"/>.  If your file system supports
+   file system snapshots or copy-on-write file copies, you can use that
+   to make a backup of the old cluster and tablespaces, though the snapshot
+   and copies must be created simultaneously or while the database server
+   is down.
+  </para>
+
+ </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="app-initdb"/></member>
+   <member><xref linkend="app-pg-ctl"/></member>
+   <member><xref linkend="app-pgdump"/></member>
+   <member><xref linkend="app-postgres"/></member>
+  </simplelist>
+ </refsect1>
+</refentry>