docs: clarify pg_upgrade docs regarding standbys and rsync

Document that rsync is an _optional_ way to upgrade standbys, suggest
rsync option --dry-run, and mention a way of upgrading one standby from
another using rsync.  Also clarify some instructions by specifying if
they operate on the old or new clusters.

Reported-by: Stephen Frost, Magnus Hagander
Discussion: https://postgr.es/m/20170914191250[email protected]

Backpatch-through: 9.5

diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index 60011d8167a180dc91292f29d5b495b04872b912..146b3af6203bc300b28133195be190fb53d1ec94 100644 (file)
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -320,20 +320,14 @@ NET STOP postgresql-&majorversion;
     Prepare for standby server upgrades
 
     
-     If you are upgrading standby servers (as outlined in section 
-     linkend="pgupgrade-step-replicas">), verify that the old standby
+     If you are upgrading standby servers using methods outlined in section 
+     linkend="pgupgrade-step-replicas">, verify that the old standby
      servers are caught up by running pg_controldata
      against the old primary and standby clusters.  Verify that the
      Latest checkpoint location values match in all clusters.
      (There will be a mismatch if old standby servers were shut down
      before the old primary.)
     
-
-    
-     Also, if upgrading standby servers, change wal_level
-     to replica in the postgresql.conf file on
-     the new primary cluster.
-    
    
 
    
@@ -423,12 +417,18 @@ pg_upgrade.exe
     
      If you used link mode and 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
+     linkend="warm-standby">) standby servers, you can follow these steps to
+     quickly 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.
+     Do not start any servers yet.
+    
+
+    
+     If you did not use link mode, do not have or do not
+     want to use rsync, or want an easier solution, skip
+     the instructions in this section and simply recreate the standby
+     servers once pg_upgrade completes and the new primary
+     is running.
     
 
     
@@ -448,7 +448,7 @@ pg_upgrade.exe
       
        Make sure the new standby data directories do not
        exist or are empty.  If initdb was run, delete
-       the standby server data directories.
+       the standby servers' new data directories.
       
      
 
@@ -474,9 +474,10 @@ pg_upgrade.exe
       Save configuration files
 
       
-       Save any configuration files from the standbys you need to keep,
-       e.g.  postgresql.conf, recovery.conf,
-       as these will be overwritten or removed in the next step.
+       Save any configuration files from the old standbys' data
+       directories you need to keep, e.g.  postgresql.conf,
+       recovery.conf, because these will be overwritten or
+       removed in the next step.
       
      
 
@@ -507,6 +508,12 @@ rsync --archive --delete --hard-links --size-only /opt/PostgreSQL/9.5/data \
       /opt/PostgreSQL/9.6/data standby.example.com:/opt/PostgreSQL
 
 
+       You can verify what the command will do using
+       rsync's --dry-run option.  While
+       rsync must be run on the primary for at least one
+       standby, it is possible to run rsync on an upgraded
+       standby to upgrade other standbys, as long as the upgraded standby
+       has not been started.
       
 
       




This is the main PostgreSQL git repository.
RSS
Atom



window.onload = function () {
	var tz_cookie = { name: 'gitweb_tz', expires: 14, path: '/' };
	onloadTZSetup('local', tz_cookie, 'datetime');
};