database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-30 11:03:19 +03:00
Code Activity

Improve low-level backup documentation.

Browse Source 
Our documentation hasn't really caught up with the fact that
non-exclusive backups can now be taken using pg_start_backup and
pg_stop_backup even on standbys.  Update.

David Steele, reviewed by Robert Haas and Michael Paquier

Discussion: http://postgr.es/m/f349b834-1443-ebf0-3c2a-965f944004d7@pgmasters.net
This commit is contained in:
Robert Haas
2017-08-31 15:56:21 -04:00
parent 941e47fc43
commit 9b1d48506a
2 changed files with 34 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
doc/src/sgml/backup.sgml
View File

@ -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>

15
doc/src/sgml/func.sgml
View File

@ -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, provided that
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 a
segment switch.
</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