Hi Michael,
Thanks for reviewing!
On 8/29/17 9:44 PM, Michael Paquier wrote:
> On Tue, Aug 29, 2017 at 10:59 PM, David Steele <da...@pgmasters.net> wrote:
>>
>> Attached is the 9.6 patch. It required a bit more work in func.sgml
>> than I was expecting so have a close look at that. The rest was mostly
>> removing irrelevant hunks.
>
> + switch to the next WAL segment. On a standby, it is not possible to
> + automatically switch WAL segments, so you may wish to run
> + <function>pg_switch_wal</function> on the primary to perform a manual
> + switch. The reason for the switch is to arrange for
> [...]
> + WAL segments have been archived. If write activity on the primary
> is low, it
> + may be useful to run <function>pg_switch_wal</> on the primary in order
> to
> + trigger an immediate segment switch of the last required WAL
> It seems to me that both portions are wrong. There is no archiving
> wait on standbys for 9.6, and
I think its clearly stated here that pg_stop_backup() does not wait for
WAL to archive on a standby. Even, it is very important for the backup
routine to make sure that all the WAL *is* archived.
> pg_stop_backup triggers by itself the
> segment switch, so saying that enforcing pg_switch_wal on the primary
> is moot.
pg_stop_backup() does not perform a WAL switch on the standby which is
what this sentence is referring to. I have separated this section out
into a new paragraph to (hopefully) make it clearer.
> pg_switch_xlog has been renamed to pg_switch_wal in PG10, so
> the former name applies.
Whoops!
New patch is attached.
Thanks,
--
-David
da...@pgmasters.net
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 03c0dbf1cd..fd696c38db 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -889,8 +889,11 @@ SELECT pg_start_backup('label', false, false);
<programlisting>
SELECT * FROM pg_stop_backup(false);
</programlisting>
- This terminates the backup mode and performs an automatic switch to
- the next WAL segment. The reason for the switch is to arrange for
+ This terminates backup mode. On a primary, it also performs an automatic
+ switch to the next WAL segment. On a standby, it is not possible to
+ automatically switch WAL segments, so you may wish to run
+ <function>pg_switch_xlog</function> on the primary to perform a manual
+ switch. The reason for the switch is to arrange for
the last WAL segment file written during the backup interval to be
ready to archive.
</para>
@@ -908,7 +911,7 @@ SELECT * FROM pg_stop_backup(false);
Once the WAL segment files active during the backup are archived, you are
done. The file identified by <function>pg_stop_backup</>'s first return
value is the last segment that is required to form a complete set of
- backup files. If <varname>archive_mode</> is enabled,
+ backup files. On a primary, if <varname>archive_mode</> is enabled,
<function>pg_stop_backup</> does not return until the last segment has
been archived.
Archiving of these files happens automatically since you have
@@ -924,6 +927,13 @@ SELECT * FROM pg_stop_backup(false);
<function>pg_stop_backup</> terminates because of this your backup
may not be valid.
</para>
+
+ <para>
+ Note that on a standby <function>pg_stop_backup</> does not wait for
+ WAL segments to be archived so the backup process must ensure that all WAL
+ segments required for the backup are successfully archived.
+ </para>
+
</listitem>
</orderedlist>
</para>
@@ -932,9 +942,9 @@ SELECT * FROM pg_stop_backup(false);
<title>Making an exclusive low level backup</title>
<para>
The process for an exclusive backup is mostly the same as for a
- non-exclusive one, but it differs in a few key steps. It does not allow
- more than one concurrent backup to run, and there can be some issues on
- the server if it crashes during the backup. Prior to PostgreSQL 9.6, this
+ non-exclusive one, but it differs in a few key steps. This type of backup
+ can only be taken on a primary and does not allow concurrent backups.
+ Prior to <productname>PostgreSQL</> 9.6, this
was the only low-level method available, but it is now recommended that
all users upgrade their scripts to use non-exclusive backups if possible.
</para>
@@ -992,6 +1002,11 @@ SELECT pg_start_backup('label', true);
<xref linkend="backup-lowlevel-base-backup-data"> for things to
consider during this backup.
</para>
+ <para>
+ Note that if the server crashes during the backup it may not be
+ possible to restart until the <literal>backup_label</> file has been
+ manually deleted from the <envar>PGDATA</envar> directory.
+ </para>
</listitem>
<listitem>
<para>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 8482601294..01ebfb8d90 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -18070,11 +18070,22 @@ postgres=# select pg_start_backup('label_goes_here');
<function>pg_start_backup</>. In a non-exclusive backup, the contents of
the <filename>backup_label</> and <filename>tablespace_map</> are returned
in the result of the function, and should be written to files in the
- backup (and not in the data directory).
+ backup (and not in the data directory). When executed on a primary
+ <function>pg_stop_backup</> will wait for WAL to be archived when archiving
+ is enabled.
</para>
<para>
- The function also creates a backup history file in the transaction log
+ On a standby <function>pg_stop_backup</> will return immediately without
+ waiting so it's important to verify that all required WAL segments have
been
+ archived. If write activity on the primary is low, it may be useful to run
+ <function>pg_switch_xlog</> on the primary in order to trigger an immediate
+ segment switch of the last required WAL.
+ </para>
+
+ <para>
+ When executed on a primary, the function also creates a backup history file
+ in the write-ahead log
archive area. The history file includes the label given to
<function>pg_start_backup</>, the starting and ending transaction log
locations for
the backup, and the starting and ending times of the backup. The return
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
