docs: improve pg_upgrade rsync instructions

This explains how rsync accomplishes updating standby servers and
clarifies the instructions.

Reported-by: Andreas Joseph Krogh
Discussion: https://postgr.es/m/VisenaEmail.10.2b4049e43870bd16.15d898d696f@tc7-visena

Backpatch-through: 9.5

diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index b4f775ff8e4d20f25db2d271cdaa7ed8b33e58b9..f497eda4b8aa0cca7a8046ec10aebf17e32e7ee2 100644 (file)
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -332,7 +332,7 @@ NET STOP postgresql-9.0
     
      Also, if upgrading standby servers, change wal_level
      to replica in the postgresql.conf file on
-     the new master cluster.
+     the new primary cluster.
     
    
 
@@ -425,8 +425,8 @@ pg_upgrade.exe
      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.  Do not
-     start any servers yet.
+     on the standby servers, but rather rsync on the
+     primary.  Do not start any servers yet.
     
 
     
@@ -455,7 +455,7 @@ pg_upgrade.exe
 
       
        Install the same custom shared object files on the new standbys
-       that you installed in the new master cluster.
+       that you installed in the new primary cluster.
       
      
 
@@ -482,25 +482,33 @@ pg_upgrade.exe
       Run <application>rsync</>
 
       
-       From a directory that is above the old and new database cluster
-       directories, run this for each slave:
+       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
 
 
        where old_pgdata and new_pgdata are relative
-       to the current directory, and remote_dir is
-       above the old and new cluster directories on
-       the standby server.  The old and new relative cluster paths
-       must match on the master and standby server.  Consult the
+       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
        rsync manual page for details on specifying the
        remote directory, e.g. standbyhost:/opt/PostgreSQL/.
-       rsync will be fast when pg_upgrade's
-       --link mode is used because it will create hard links
-       on the remote server rather than transferring user data.
-       Unfortunately, rsync needlessly copies the
-       files associated with temporary and unlogged tables.
+      
+
+      
+       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.
       
 
       
@@ -517,8 +525,8 @@ rsync --archive --delete --hard-links --size-only old_pgdata new_pgdata remote_d
       
        Configure the servers for log shipping.  (You do not need to run
        pg_start_backup() and pg_stop_backup()
-       or take a file system backup as the slaves are still synchronized
-       with the master.)
+       or take a file system backup as the standbys are still synchronized
+       with the primary.)