Doc patch: pg_upgrade page and checkpoint location consistency with replicas

Hello,

Please find below a submission of a patch to the PostgreSQL documentation.

You can also find the patch in this git commit:
https://gitlab.com/paulrbr/postgresql/commit/024d3870450df6dcdc69bddbe2de46084b73e3a2.diff

============
commit 024d3870450df6dcdc69bddbe2de46084b73e3a2
Author: Paul B <paul(dot)bonaud(at)capitainetrain(dot)com>
Date: Thu Aug 16 18:25:22 2018 +0200

doc: Update pg_upgrade page while checking checkpoint locations

At the end of the previous step 7. you already stopped the primary
server. Which led PostgreSQL to issue a CHECKPOINT command.
Aksi the end of the step 7. also states that "standby servers can
remain running until a later step".

However if you keep your standby server running at this point and
compare the <quote>Latest checkpoint location</quote> with your
stopped primary you will never end up with matching values.

I found it confusing during my pg_upgrade tests as I tried multiple
times to end up with the same latest checkpoint location value between
my primary and standby nodes until I realised PostgreSQL was issuing a
CHECKPOINT during shutdown which would obviously prevent that.

I reckon some clarification should be added to the documentation for
that and that is why I propose this patch.

Please let me know if you want to phrase it differently or if I am
missing something out.

Thank you!

diff --git a/doc/src/sgml/ref/pgupgrade.sgml
b/doc/src/sgml/ref/pgupgrade.sgml
index 6dafb404a11..d51146d641d 100644
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -326,7 +326,8 @@ NET STOP postgresql-&majorversion;
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.) Also, change <varname>wal_level</varname> to
+ before the old primary or if the old standby servers are still
running.)
+ Also, change <varname>wal_level</varname> to
<literal>replica</literal> in the
<filename>postgresql.conf</filename> file on the
new primary cluster.
</para>
============

---
Paul Bonaud