docs: Fix pg_upgrade standby server upgrade docs

It was unsafe to instruct users to start/stop the server after
pg_upgrade was run but before the standby servers were rsync'ed.  The
new instructions avoid this.

RELEASE NOTES:  This fix should be mentioned in the minor release notes.

Reported-by: Dmitriy Sarafannikov and Sergey Burladyan
Discussion: https://postgr.es/m/[email protected]

Backpatch-through: 9.5, where standby server upgrade instructions first appeared

diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index 40c978730c8c2d0ff725e25ece77a7777b7f6ad5..5b32b75bd7f1372aa3d841a99b2b7ddd64dd6e0f 100644 (file)
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -317,15 +317,22 @@ NET STOP postgresql-&majorversion;
    
 
    
-    <span class="marked">Verify standby server</span>s
+    <span class="marked">Prepare for standby server upgrade</span>s
 
     
-     If you are upgrading Streaming Replication and Log-Shipping standby
-     servers, 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.)
+     If you are upgrading standby servers (as 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 master cluster.
     
    
 
@@ -410,7 +417,7 @@ pg_upgrade.exe
     
    
 
-   
+    id="pgupgrade-step-replicas">
     Upgrade Streaming Replication and Log-Shipping standby servers
 
     
@@ -471,16 +478,6 @@ pg_upgrade.exe
       
      
 
-     
-      Start and stop the new master cluster
-
-      
-       In the new master cluster, change wal_level to
-       replica in the postgresql.conf file
-       and then start and stop the cluster.
-      
-     
-
      
       Run <application>rsync</>