Skip to content

Commit

Permalink
Remove exclusive backup mode
Browse files Browse the repository at this point in the history 
Exclusive-mode backups have been deprecated since 9.6 (when
non-exclusive backups were introduced) due to the issues
they can cause should the system crash while one is running and
generally because non-exclusive provides a much better interface.
Further, exclusive backup mode wasn't really being tested (nor was most
of the related code- like being able to log in just to stop an exclusive
backup and the bits of the state machine related to that) and having to
possibly deal with an exclusive backup and the backup_label file
existing during pg_basebackup, pg_rewind, etc, added other complexities
that we are better off without.

This patch removes the exclusive backup mode, the various special cases
for dealing with it, and greatly simplifies the online backup code and
documentation.

Authors: David Steele, Nathan Bossart
Reviewed-by: Chapman Flack
Discussion: https://postgr.es/m/[email protected]
https://postgr.es/m/CAHg+QDfiM+WU61tF6=nPZocMZvHDzCK47Kneyb0ZRULYzV5sKQ@mail.gmail.com
  • Loading branch information
@sfrost
sfrost committed Apr 6, 2022
1 parent 14d3f24 commit 39969e2
Show file tree
Hide file tree
Showing 24 changed files with 247 additions and 1,200 deletions.
241 changes: 27 additions & 214 deletions doc/src/sgml/backup.sgml
View file

Large diffs are not rendered by default.

111 changes: 24 additions & 87 deletions doc/src/sgml/func.sgml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25618,9 +25618,8 @@ LOG: Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560
The functions shown in <xref
linkend="functions-admin-backup-table"/> assist in making on-line backups.
These functions cannot be executed during recovery (except
non-exclusive <function>pg_start_backup</function>,
non-exclusive <function>pg_stop_backup</function>,
<function>pg_is_in_backup</function>, <function>pg_backup_start_time</function>
<function>pg_backup_start</function>,
<function>pg_backup_stop</function>,
and <function>pg_wal_lsn_diff</function>).
</para>

Expand Down Expand Up @@ -25709,13 +25708,12 @@ LOG: Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_start_backup</primary>
<primary>pg_backup_start</primary>
</indexterm>
<function>pg_start_backup</function> (
<function>pg_backup_start</function> (
<parameter>label</parameter> <type>text</type>
<optional>, <parameter>fast</parameter> <type>boolean</type>
<optional>, <parameter>exclusive</parameter> <type>boolean</type>
</optional></optional> )
</optional> )
<returnvalue>pg_lsn</returnvalue>
</para>
<para>
Expand All @@ -25724,23 +25722,9 @@ LOG: Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560
(Typically this would be the name under which the backup dump file
will be stored.)
If the optional second parameter is given as <literal>true</literal>,
it specifies executing <function>pg_start_backup</function> as quickly
it specifies executing <function>pg_backup_start</function> as quickly
as possible. This forces an immediate checkpoint which will cause a
spike in I/O operations, slowing any concurrently executing queries.
The optional third parameter specifies whether to perform an exclusive
or non-exclusive backup (default is exclusive).
</para>
<para>
When used in exclusive mode, this function writes a backup label file
(<filename>backup_label</filename>) and, if there are any links in
the <filename>pg_tblspc/</filename> directory, a tablespace map file
(<filename>tablespace_map</filename>) into the database cluster's data
directory, then performs a checkpoint, and then returns the backup's
starting write-ahead log location. (The user can ignore this
result value, but it is provided in case it is useful.) When used in
non-exclusive mode, the contents of these files are instead returned
by the <function>pg_stop_backup</function> function, and should be
copied to the backup area by the user.
</para>
<para>
This function is restricted to superusers by default, but other users
Expand All @@ -25751,36 +25735,32 @@ LOG: Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_stop_backup</primary>
<primary>pg_backup_stop</primary>
</indexterm>
<function>pg_stop_backup</function> (
<parameter>exclusive</parameter> <type>boolean</type>
<optional>, <parameter>wait_for_archive</parameter> <type>boolean</type>
<function>pg_backup_stop</function> (
<optional><parameter>wait_for_archive</parameter> <type>boolean</type>
</optional> )
<returnvalue>record</returnvalue>
( <parameter>lsn</parameter> <type>pg_lsn</type>,
<parameter>labelfile</parameter> <type>text</type>,
<parameter>spcmapfile</parameter> <type>text</type> )
</para>
<para>
Finishes performing an exclusive or non-exclusive on-line backup.
The <parameter>exclusive</parameter> parameter must match the
previous <function>pg_start_backup</function> call.
In an exclusive backup, <function>pg_stop_backup</function> removes
the backup label file and, if it exists, the tablespace map file
created by <function>pg_start_backup</function>. In a non-exclusive
backup, the desired contents of these files are returned as part of
the result of the function, and should be written to files in the
backup area (not in the data directory).
Finishes performing an on-line backup. The desired contents of the
backup label file and the tablespace map file are returned as part of
the result of the function and must be written to files in the
backup area. These files must not be written to the live data directory
(doing so will cause PostgreSQL to fail to restart in the event of a
crash).
</para>
<para>
There is an optional second parameter of type <type>boolean</type>.
There is an optional parameter of type <type>boolean</type>.
If false, the function will return immediately after the backup is
completed, without waiting for WAL to be archived. This behavior is
only useful with backup software that independently monitors WAL
archiving. Otherwise, WAL required to make the backup consistent might
be missing and make the backup useless. By default or when this
parameter is true, <function>pg_stop_backup</function> will wait for
parameter is true, <function>pg_backup_stop</function> will wait for
WAL to be archived when archiving is enabled. (On a standby, this
means that it will wait only when <varname>archive_mode</varname> =
<literal>always</literal>. If write activity on the primary is low,
Expand All @@ -25790,7 +25770,7 @@ LOG: Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560
<para>
When executed on a primary, this 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</function>, the
includes the label given to <function>pg_backup_start</function>, the
starting and ending write-ahead log locations for the backup, and the
starting and ending times of the backup. After recording the ending
location, the current write-ahead log insertion point is automatically
Expand All @@ -25801,61 +25781,18 @@ LOG: Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560
<para>
The result of the function is a single record.
The <parameter>lsn</parameter> column holds the backup's ending
write-ahead log location (which again can be ignored). The second and
third columns are <literal>NULL</literal> when ending an exclusive
backup; after a non-exclusive backup they hold the desired contents of
the label and tablespace map files.
</para>
<para>
This function is restricted to superusers by default, but other users
can be granted EXECUTE to run the function.
</para></entry>
</row>

<row>
<entry role="func_table_entry"><para role="func_signature">
<function>pg_stop_backup</function> ()
<returnvalue>pg_lsn</returnvalue>
</para>
<para>
Finishes performing an exclusive on-line backup. This simplified
version is equivalent to <literal>pg_stop_backup(true,
true)</literal>, except that it only returns the <type>pg_lsn</type>
result.
write-ahead log location (which again can be ignored). The second
column returns the contents of the backup label file, and the third
column returns the contents of the tablespace map file. These must be
stored as part of the backup and are required as part of the restore
process.
</para>
<para>
This function is restricted to superusers by default, but other users
can be granted EXECUTE to run the function.
</para></entry>
</row>

<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_is_in_backup</primary>
</indexterm>
<function>pg_is_in_backup</function> ()
<returnvalue>boolean</returnvalue>
</para>
<para>
Returns true if an on-line exclusive backup is in progress.
</para></entry>
</row>

<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_backup_start_time</primary>
</indexterm>
<function>pg_backup_start_time</function> ()
<returnvalue>timestamp with time zone</returnvalue>
</para>
<para>
Returns the start time of the current on-line exclusive backup if one
is in progress, otherwise <literal>NULL</literal>.
</para></entry>
</row>

<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
Expand Down Expand Up @@ -25953,7 +25890,7 @@ LOG: Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560
corresponding write-ahead log file name and byte offset from
a <type>pg_lsn</type> value. For example:
<programlisting>
postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
postgres=# SELECT * FROM pg_walfile_name_offset((pg_backup_stop()).lsn);
file_name | file_offset
--------------------------+-------------
00000001000000000000000D | 4039624
Expand Down
6 changes: 3 additions & 3 deletions doc/src/sgml/high-availability.sgml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1361,8 +1361,8 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)'

<para>
If you need to re-create a standby server while transactions are
waiting, make sure that the commands pg_start_backup() and
pg_stop_backup() are run in a session with
waiting, make sure that the commands pg_backup_start() and
pg_backup_stop() are run in a session with
<varname>synchronous_commit</varname> = <literal>off</literal>, otherwise those
requests will wait forever for the standby to appear.
</para>
Expand Down Expand Up @@ -2159,7 +2159,7 @@ HINT: You can then restart the server after making the necessary configuration

<para>
WAL file control commands will not work during recovery,
e.g., <function>pg_start_backup</function>, <function>pg_switch_wal</function> etc.
e.g., <function>pg_backup_start</function>, <function>pg_switch_wal</function> etc.
</para>

<para>
Expand Down
4 changes: 2 additions & 2 deletions doc/src/sgml/monitoring.sgml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6674,7 +6674,7 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
<entry><literal>waiting for checkpoint to finish</literal></entry>
<entry>
The WAL sender process is currently performing
<function>pg_start_backup</function> to prepare to
<function>pg_backup_start</function> to prepare to
take a base backup, and waiting for the start-of-backup
checkpoint to finish.
</entry>
Expand All @@ -6697,7 +6697,7 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
<entry><literal>waiting for wal archiving to finish</literal></entry>
<entry>
The WAL sender process is currently performing
<function>pg_stop_backup</function> to finish the backup,
<function>pg_backup_stop</function> to finish the backup,
and waiting for all the WAL files required for the base backup
to be successfully archived.
If either <literal>--wal-method=none</literal> or
Expand Down
6 changes: 3 additions & 3 deletions doc/src/sgml/ref/pg_ctl-ref.sgml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -186,11 +186,11 @@ PostgreSQL documentation
the specified data directory. Three different
shutdown methods can be selected with the <option>-m</option>
option. <quote>Smart</quote> mode disallows new connections, then waits
for all existing clients to disconnect and any online backup to finish.
for all existing clients to disconnect.
If the server is in hot standby, recovery and streaming replication
will be terminated once all clients have disconnected.
<quote>Fast</quote> mode (the default) does not wait for clients to disconnect and
will terminate an online backup in progress. All active transactions are
<quote>Fast</quote> mode (the default) does not wait for clients to disconnect.
All active transactions are
rolled back and clients are forcibly disconnected, then the
server is shut down. <quote>Immediate</quote> mode will abort
all server processes immediately, without a clean shutdown. This choice
Expand Down
2 changes: 1 addition & 1 deletion doc/src/sgml/ref/pgupgrade.sgml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -618,7 +618,7 @@ rsync --archive --delete --hard-links --size-only --no-inc-recursive /vol1/pg_tb

<para>
Configure the servers for log shipping. (You do not need to run
<function>pg_start_backup()</function> and <function>pg_stop_backup()</function>
<function>pg_backup_start()</function> and <function>pg_backup_stop()</function>
or take a file system backup as the standbys are still synchronized
with the primary.)
</para>
Expand Down
8 changes: 1 addition & 7 deletions doc/src/sgml/runtime.sgml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1552,11 +1552,7 @@ $ <userinput>cat /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages</userinp
After receiving <systemitem>SIGTERM</systemitem>, the server
disallows new connections, but lets existing sessions end their
work normally. It shuts down only after all of the sessions terminate.
If the server is in online backup mode, it additionally waits
until online backup mode is no longer active. While backup mode is
active, new connections will still be allowed, but only to superusers
(this exception allows a superuser to connect to terminate
online backup mode). If the server is in recovery when a smart
If the server is in recovery when a smart
shutdown is requested, recovery and streaming replication will be
stopped only after all regular sessions have terminated.
</para>
Expand All @@ -1572,8 +1568,6 @@ $ <userinput>cat /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages</userinp
server processes <systemitem>SIGTERM</systemitem>, which will cause them
to abort their current transactions and exit promptly. It then
waits for all server processes to exit and finally shuts down.
If the server is in online backup mode, backup mode will be
terminated, rendering the backup useless.
</para>
</listitem>
</varlistentry>
Expand Down
Loading

0 comments on commit 39969e2

Please sign in to comment.