Thread: Doc patch: pg_upgrade page and checkpoint location consistency withreplicas

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.bonaud@capitainetrain.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

I shared the pach in plain textin the email body and figured out that
all other patches are submitted as an attachement. Sorry for that, here
is the patch attached to this email.

Thanks!
Paul

On 17/08/18 01:21, Paul Bonaud wrote:
> 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.bonaud@capitainetrain.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
>

On Fri, Aug 17, 2018 at 09:57:08AM +0200, Paul Bonaud wrote:
> I shared the pach in plain textin the email body and figured out that
> all other patches are submitted as an attachement. Sorry for that, here
> is the patch attached to this email.

Patch applied through 9.5, where the "match" text first appeared. 
Thanks for the report and patch.

-- 
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +