As discussed in [1] our low-level backup documentation does not quite
match the actual behavior of the functions on primary vs. standby.
Since it appears we have decided that the remaining behavioral
differences after 52f8a59dd953c68 are bugs in the documentation, the
attached is a first pass at bringing the documentation up to date.
The biggest change is to recognize that exclusive backups can only be
run on a primary and to adjust the text accordingly. Also, I did not
mention the wait_for_archive param in the exclusive instructions since
they are deprecated.
This patch should be sufficient for 10/11 but will need some minor
changes for 9.6 to remove the reference to wait_for_archive. Note that
this patch ignores Michael's patch [2] to create WAL history files on a
standby as this will likely only be applied to master.
In addition, I have formatted the text to produce minimal diffs for
review, but it could be tightened up before commit.
--
-David
da...@pgmasters.net
[1]
https://www.postgresql.org/message-id/20170814152816.GF4628%40tamriel.snowman.net
[2]
https://www.postgresql.org/message-id/CAB7nPqQvVpMsqJExSVXHUwpXFRwojsb-jb4BYnxEQbjJLfw-yQ%40mail.gmail.com
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 0e7c6e2051..cfffea3919 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -890,7 +890,10 @@ SELECT pg_start_backup('label', false, false);
SELECT * FROM pg_stop_backup(false, true);
</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
+ the next WAL segment when run on a primary. On a standby you can call
+ <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,9 +911,12 @@ SELECT * FROM pg_stop_backup(false, true);
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 and
the
+ <literal>wait_for_archive</> parameter is <literal>true</>,
<function>pg_stop_backup</> does not return until the last segment has
been archived.
+ On a standby, <varname>archive_mode</> must be <literal>always</> in order
+ for <function>pg_stop_backup</> to wait.
Archiving of these files happens automatically since you have
already configured <varname>archive_command</>. In most cases this
happens quickly, but you are advised to monitor your archive
@@ -940,11 +946,12 @@ SELECT * FROM pg_stop_backup(false, true);
</para>
</sect3>
<sect3 id="backup-lowlevel-base-backup-exclusive">
- <title>Making an exclusive low level backup</title>
+ <title>Making an exclusive low level backup on a primary</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
+ more than one concurrent backup to run, must be run on a primary, and
there
+ can be some issues on
the server if it crashes during the backup. Prior to 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.
@@ -1012,15 +1019,10 @@ SELECT pg_start_backup('label', true);
<programlisting>
SELECT pg_stop_backup();
</programlisting>
- This function, when called on a primary, terminates the backup mode and
+ This function terminates the backup mode and
performs an automatic switch to the next WAL segment. The reason for the
switch is to arrange for the last WAL segment written during the backup
- interval to be ready to archive. When called on a standby, this function
- only terminates backup mode. A subsequent WAL segment switch will be
- needed in order to ensure that all WAL files needed to restore the backup
- can be archived; if the primary does not have sufficient write activity
- to trigger one, <function>pg_switch_wal</function> should be executed on
- the primary.
+ interval to be ready to archive.
</para>
</listitem>
<listitem>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index b43ec30a4e..28eda97273 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -18606,7 +18606,8 @@ postgres=# select pg_start_backup('label_goes_here');
</para>
<para>
- The function also creates a backup history file in the write-ahead 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 write-ahead 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
