docs: improve pg_upgrade standby instructions

This makes it clear that pg_upgrade standby upgrade instructions should
only be used in link mode, adds examples, and explains how rsync works
with links.

Reported-by: Andreas Joseph Krogh
Discussion: https://postgr.es/m/VisenaEmail.6c.c0e592c5af4ef0a2.15e785dcb61@tc7-visena

Backpatch-through: 9.5

diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index f497eda4b8aa0cca7a8046ec10aebf17e32e7ee2..40563cfbda3193e399d732270df297f47acf348b 100644 (file)
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -423,10 +423,12 @@ pg_upgrade.exe
     
      If you have Streaming Replication (see 
      linkend="streaming-replication">) or Log-Shipping (see 
-     linkend="warm-standby">) standby servers, follow these steps to
-     upgrade them.  You will not be running pg_upgrade
-     on the standby servers, but rather rsync on the
-     primary.  Do not start any servers yet.
+     linkend="warm-standby">) standby servers, and used link mode,
+     follow these steps to upgrade them.  You will not be running
+     pg_upgrade on the standby servers, but rather
+     rsync on the primary.  Do not start any servers yet.
+     If you did not use link mode, skip the instructions in
+     this section and simply recreate the standby servers.
     
 
     
@@ -482,9 +484,11 @@ pg_upgrade.exe
       Run <application>rsync</>
 
       
-       From a directory on the primary server that is above the old and
-       new database cluster directories, run this on the
-       primary for each standby server:
+       When using link mode, standby servers can be quickly upgraded using
+       rsync.  To accomplish this, from a directory on
+       the primary server that is above the old and new database cluster
+       directories, run this on the primary for each standby
+       server:
 
 
 rsync --archive --delete --hard-links --size-only old_pgdata new_pgdata remote_dir
@@ -492,30 +496,44 @@ rsync --archive --delete --hard-links --size-only old_pgdata new_pgdata remote_d
 
        where old_pgdata and new_pgdata are relative
        to the current directory on the primary, and remote_dir
-       is above the old and new cluster directories on
-       the standby.  The old and new relative cluster paths
-       must match on the primary and standby server.  Consult the
+       is above 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
        rsync manual page for details on specifying the
-       remote directory, e.g. standbyhost:/opt/PostgreSQL/.
+       remote directory, e.g.
+
+
+rsync --archive --delete --hard-links --size-only /opt/PostgreSQL/9.5/data \
+      /opt/PostgreSQL/9.6/data standby.example.com:/opt/PostgreSQL
+
+
       
 
       
-       What rsync does is to copy files from the
-       primary to the standby, and, if pg_upgrade's
-       --link mode was used, link files from the old to
-       new clusters on the standby.  It links the same files that
-       pg_upgrade linked in the primary old and new
-       clusters.  (Of course, linking speeds up rsync.)
-       Unfortunately, rsync needlessly copies files
-       associated with temporary and unlogged tables because these files
-       don't normally exist on standby servers.
+       What this does is to record the links created by
+       pg_upgrade'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,
+       rsync needlessly copies files associated with
+       temporary and unlogged tables because these files don't normally
+       exist on standby servers.
       
 
       
        If you have tablespaces, you will need to run a similar
-       rsync command for each tablespace directory.  If you
-       have relocated pg_xlog outside the data directories,
-       rsync must be run on those directories too.
+       rsync command for each tablespace directory, e.g.:
+
+
+rsync --archive --delete --hard-links --size-only /vol1/pg_tblsp/PG_9.5_201510051 \
+      /vol1/pg_tblsp/PG_9.6_201608131 standby.example.com:/vol1/pg_tblsp
+
+
+       If you have relocated pg_xlog outside the data
+       directories, rsync must be run on those directories
+       too.