Hi Robert,
On 8/25/17 4:03 PM, David Steele wrote:
> On 8/25/17 3:26 PM, Robert Haas wrote:
>> On Fri, Aug 25, 2017 at 3:21 PM, David Steele <da...@pgmasters.net>
>> wrote:
>>> No problem. I'll base it on your commit to capture any changes you
>>> made.
>>
>> Thanks, but you incorporated everything I wanted in response to my
>> first review -- so I didn't tweak it any further.
>
> Thank you for committing that. I'll get the 9.6 patch to you early next
> week.
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.
Thanks,
--
-David
da...@pgmasters.net
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 03c0dbf1cd..456f6f2c98 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_wal</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..a803e747b2 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -18070,11 +18070,18 @@ 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. 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_wal</> on the primary in order to
+ trigger an immediate segment switch of the last required WAL.
</para>
<para>
- The function also creates a backup history file in the transaction log
+ 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
