Re: Stale description for pg_basebackup - Mailing list pgsql-hackers

From Kyotaro Horiguchi
Subject Re: Stale description for pg_basebackup
Date
Msg-id 20210421.104330.407572102839098756.horikyota.ntt@gmail.com
Whole thread Raw
In response to Stale description for pg_basebackup  (Kyotaro Horiguchi <horikyota.ntt@gmail.com>)
Responses Re: Stale description for pg_basebackup
List pgsql-hackers
At Tue, 20 Apr 2021 13:32:35 +0900 (JST), Kyotaro Horiguchi <horikyota.ntt@gmail.com> wrote in 
> Hello.
> 
> It seems to me that there's a stale description in the documentation
> of pg_basebackup.
> 
> https://www.postgresql.org/docs/13/app-pgbasebackup.html
> 
> > Note that there are some limitations in taking a backup from a standby:
> ...
> > If you are using -X none, there is no guarantee that all WAL files
> > required for the backup are archived at the end of backup.
> 
> Actually, pg_basebackup waits for the all required files to be
> archived, which is an established behavior by commit
> 52f8a59dd9@PG10. However, the same commit seems to have forgot to
> change the doc for pg_basebackup. (The current description is
> introduced by 9a4d51077c@PG10)
> 
> The attached is a proposal to rewrite it as the following.
> 
> + If you are using -X none, pg_basebackup may wait for a long time for
> + all the required WAL files to be archived. In that case, You may need
> + to call pg_switch_wal() on the primary to complete it sooner.

I forgot to preserve the description about *primary*. It should be as
the following instead.

+ If you are using -X none, there is no guarantee on the primary that
+ all WAL files required for the backup are archived at the end of
+ backup. When the standby is configured as archive_mode=always,
+ pg_basebackup may wait for a long time for all the required WAL files
+ to be archived. In that case, You may need to call pg_switch_wal() on
+ the primary to complete it sooner.

Attached.

regards.

-- 
Kyotaro Horiguchi
NTT Open Source Software Center
diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml
index a3e292d44a..35d7fb605f 100644
--- a/doc/src/sgml/ref/pg_basebackup.sgml
+++ b/doc/src/sgml/ref/pg_basebackup.sgml
@@ -83,8 +83,13 @@ PostgreSQL documentation
     </listitem>
     <listitem>
      <para>
-      If you are using <literal>-X none</literal>, there is no guarantee that all
-      WAL files required for the backup are archived at the end of backup.
+       If you are using <literal>-X none</literal>, there is no guarantee on
+       the primary that all WAL files required for the backup are archived at
+       the end of backup. When the standby is configured as
+       archive_mode=always, pg_basebackup may wait for a long time for all the
+       required WAL files to be archived.  In that case, You may need to
+       call <function>pg_switch_wal()</function> on the primary to complete it
+       sooner.
      </para>
     </listitem>
     <listitem>

pgsql-hackers by date:

Previous
From: Bharath Rupireddy
Date:
Subject: Re: Tiny update to pg_stat_statements documentation
Next
From: Julien Rouhaud
Date:
Subject: Re: Tiny update to pg_stat_statements documentation