From: Liudmila Mantrova <l.mantrova@postgrespro.ru>
Subject: suspicious wording in pg_rewind docs
To: pgsql-docs@lists.postgresql.org
Message-ID: <ad6ac5bb-6689-ddb0-dc60-c5fc197d728e@postgrespro.ru>
Date: Fri, 26 Jul 2019 21:08:47 +0300
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101
 Thunderbird/60.8.0
MIME-Version: 1.0
Content-Type: multipart/mixed;
 boundary="------------E907D42B2BC749E8254CE4EB"
Content-Language: en-US
Precedence: bulk

This is a multi-part message in MIME format.
--------------E907D42B2BC749E8254CE4EB
Content-Type: multipart/alternative;
 boundary="------------CE2DA2A48ADD88704D730F6A"


--------------CE2DA2A48ADD88704D730F6A
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 7bit

Hi everyone,

While reviewing docs for [1] I came across a phrase in pg_rewind.sgml 
that seems confusing:

"... The point of divergence can be found either on the target timeline, 
the source timeline, or their common ancestor. In the typical failover 
scenario where the target cluster was shut down soon after the 
divergence, this is not a problem, but if the target cluster ran for a 
long time after the divergence, the old WAL files might no longer be 
present. In that case, they can be manually copied from the WAL archive 
to the |pg_wal| directory, or fetched on startup by configuring 
primary_conninfo 
<https://www.postgresql.org/docs/12/runtime-config-replication.html#GUC-PRIMARY-CONNINFO> 
or restore_command 
<https://www.postgresql.org/docs/12/runtime-config-wal.html#GUC-RESTORE-COMMAND>. 
"

While beginning of this paragraph talks about scanning target cluster 
WALs, the "or fetched on startup" part suggests that we are applying the 
source cluster WALs already, so I would simply remove it from here. To 
avoid source/target confusion, we could also add another hint that it's 
target WALs we are talking about.

Please consider the attached fix.

[1] 
https://www.postgresql.org/message-id/a3acff50-5a0d-9a2c-b3b2-ee36168955c1%40postgrespro.ru


-- 
Liudmila Mantrova
Technical writer at Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company


--------------CE2DA2A48ADD88704D730F6A
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: 7bit

<html>
  <head>

    <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  </head>
  <body text="#000000" bgcolor="#FFFFFF">
    <p>Hi everyone,</p>
    <p>While reviewing docs for [1] I came across a phrase in
      pg_rewind.sgml that seems confusing:<br>
    </p>
    <p>"... The point of divergence can be found either on the target
      timeline, the source timeline, or their common ancestor. In the
      typical failover scenario where the target cluster was shut down
      soon after the divergence, this is not a problem, but if the
      target cluster ran for a long time after the divergence, the old
      WAL files might no longer be present. In that case, they can be
      manually copied from the WAL archive to the <code
        class="filename">pg_wal</code> directory, or fetched on startup
      by configuring <a class="xref"
href="https://www.postgresql.org/docs/12/runtime-config-replication.html#GUC-PRIMARY-CONNINFO">primary_conninfo</a>
      or <a class="xref"
href="https://www.postgresql.org/docs/12/runtime-config-wal.html#GUC-RESTORE-COMMAND">restore_command</a>.
      "<br>
    </p>
    <p>While beginning of this paragraph talks about scanning target
      cluster WALs, the "or fetched on startup" part suggests that we
      are applying the source cluster WALs already, so I would simply
      remove it from here. To avoid source/target confusion, we could
      also add another hint that it's target WALs we are talking about.
      <br>
    </p>
    <p>Please consider the attached fix.<br>
    </p>
    <p>[1]
<a class="moz-txt-link-freetext" href="https://www.postgresql.org/message-id/a3acff50-5a0d-9a2c-b3b2-ee36168955c1%40postgrespro.ru">https://www.postgresql.org/message-id/a3acff50-5a0d-9a2c-b3b2-ee36168955c1%40postgrespro.ru</a></p>
    <p><br>
    </p>
    <pre class="moz-signature" cols="72">-- 
Liudmila Mantrova
Technical writer at Postgres Professional: <a class="moz-txt-link-freetext" href="http://www.postgrespro.com">http://www.postgrespro.com</a>
The Russian Postgres Company </pre>
  </body>
</html>

--------------CE2DA2A48ADD88704D730F6A--

--------------E907D42B2BC749E8254CE4EB
Content-Type: text/x-patch;
 name="pg-rewind-doc-fix.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
 filename="pg-rewind-doc-fix.patch"

diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml
index 52a1caa..a7e1705 100644
--- a/doc/src/sgml/ref/pg_rewind.sgml
+++ b/doc/src/sgml/ref/pg_rewind.sgml
@@ -66,14 +66,12 @@ PostgreSQL documentation
    can be found either on the target timeline, the source timeline, or their common
    ancestor. In the typical failover scenario where the target cluster was
    shut down soon after the divergence, this is not a problem, but if the
-   target cluster ran for a long time after the divergence, the old WAL
+   target cluster ran for a long time after the divergence, its old WAL
    files might no longer be present. In that case, they can be manually
-   copied from the WAL archive to the <filename>pg_wal</filename> directory, or
-   fetched on startup by configuring <xref linkend="guc-primary-conninfo"/> or
-   <xref linkend="guc-restore-command"/>.  The use of
-   <application>pg_rewind</application> is not limited to failover, e.g.  a standby
-   server can be promoted, run some write transactions, and then rewinded
-   to become a standby again.
+   copied from the WAL archive to the <filename>pg_wal</filename> directory.
+   The use of <application>pg_rewind</application> is not limited to failover,
+   e.g. a standby server can be promoted, run some write transactions, and then
+   get rewound to become a standby again.
   </para>
 
   <para>

--------------E907D42B2BC749E8254CE4EB--