database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-08-28 18:48:04 +03:00
Code Activity

Flexible options for BASE_BACKUP.

Browse Source 
Previously, BASE_BACKUP used an entirely hard-coded syntax, but that's
hard to extend. Instead, adopt the same kind of syntax we've used for
SQL commands such as VACUUM, ANALYZE, COPY, and EXPLAIN, where it's
not necessary for all of the option names to be parser keywords.

In the new syntax, most of the options now take an optional Boolean
argument. To match our practice in other in places, the options which
the old syntax called NOWAIT and NOVERIFY_CHECKSUMS options are in the
new syntax called WAIT and VERIFY_CHECKUMS, and the default value is
false. In the new syntax, the FAST option has been replaced by a
CHECKSUM option whose value may be 'fast' or 'spread'.

This commit does not remove support for the old syntax. It just adds
the new one as an additional option, and makes pg_basebackup prefer
the new syntax when the server is new enough to support it.

Patch by me, reviewed and tested by Fabien Coelho, Sergei Kornilov,
Fujii Masao, and Tushar Ahuja.

Discussion: http://postgr.es/m/CA+TgmobAczXDRO_Gr2euo_TxgzaH1JxbNxvFx=HYvBinefNH8Q@mail.gmail.com
Discussion: http://postgr.es/m/CA+TgmoZGwR=ZVWFeecncubEyPdwghnvfkkdBe9BLccLSiqdf9Q@mail.gmail.com
This commit is contained in:
Robert Haas
2021-10-05 11:50:21 -04:00
parent 68601985e6
commit 0ba281cb4b
6 changed files with 276 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
doc/src/sgml/protocol.sgml
View File

@@ -2517,7 +2517,7 @@ The commands accepted in replication mode are:
</varlistentry>
<varlistentry id="protocol-replication-base-backup" xreflabel="BASE_BACKUP">
<term><literal>BASE_BACKUP</literal> [ <literal>LABEL</literal> <replaceable>'label'</replaceable> ] [ <literal>PROGRESS</literal> ] [ <literal>FAST</literal> ] [ <literal>WAL</literal> ] [ <literal>NOWAIT</literal> ] [ <literal>MAX_RATE</literal> <replaceable>rate</replaceable> ] [ <literal>TABLESPACE_MAP</literal> ] [ <literal>NOVERIFY_CHECKSUMS</literal> ] [ <literal>MANIFEST</literal> <replaceable>manifest_option</replaceable> ] [ <literal>MANIFEST_CHECKSUMS</literal> <replaceable>checksum_algorithm</replaceable> ]
<term><literal>BASE_BACKUP</literal> [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ]
<indexterm><primary>BASE_BACKUP</primary></indexterm>
</term>
<listitem>
@@ -2540,52 +2540,55 @@ The commands accepted in replication mode are:
</varlistentry>
<varlistentry>
<term><literal>PROGRESS</literal></term>
<term><literal>PROGRESS [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
<listitem>
<para>
Request information required to generate a progress report. This will
send back an approximate size in the header of each tablespace, which
can be used to calculate how far along the stream is done. This is
calculated by enumerating all the file sizes once before the transfer
is even started, and might as such have a negative impact on the
performance. In particular, it might take longer before the first data
If set to true, request information required to generate a progress
report. This will send back an approximate size in the header of each
tablespace, which can be used to calculate how far along the stream
is done. This is calculated by enumerating all the file sizes once
before the transfer is even started, and might as such have a
negative impact on the performance. In particular, it might take
longer before the first data
is streamed. Since the database files can change during the backup,
the size is only approximate and might both grow and shrink between
the time of approximation and the sending of the actual files.
The default is false.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>FAST</literal></term>
<term><literal>CHECKPOINT { 'fast' | 'spread' }</literal></term>
<listitem>
<para>
Request a fast checkpoint.
Sets the type of checkpoint to be performed at the beginning of the
base backup. The default is <literal>spread</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>WAL</literal></term>
<term><literal>WAL [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
<listitem>
<para>
Include the necessary WAL segments in the backup. This will include
all the files between start and stop backup in the
If set to true, include the necessary WAL segments in the backup.
This will include all the files between start and stop backup in the
<filename>pg_wal</filename> directory of the base directory tar
file.
file. The default is false.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>NOWAIT</literal></term>
<term><literal>WAIT [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
<listitem>
<para>
By default, the backup will wait until the last required WAL
If set to true, the backup will wait until the last required WAL
segment has been archived, or emit a warning if log archiving is
not enabled. Specifying <literal>NOWAIT</literal> disables both
the waiting and the warning, leaving the client responsible for
ensuring the required log is available.
not enabled. If false, the backup will neither wait nor warn,
leaving the client responsible for ensuring the required log is
available. The default is true.
</para>
</listitem>
</varlistentry>
@@ -2605,25 +2608,25 @@ The commands accepted in replication mode are:
</varlistentry>
<varlistentry>
<term><literal>TABLESPACE_MAP</literal></term>
<term><literal>TABLESPACE_MAP [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
<listitem>
<para>
Include information about symbolic links present in the directory
<filename>pg_tblspc</filename> in a file named
If true, include information about symbolic links present in the
directory <filename>pg_tblspc</filename> in a file named
<filename>tablespace_map</filename>. The tablespace map file includes
each symbolic link name as it exists in the directory
<filename>pg_tblspc/</filename> and the full path of that symbolic link.
The default is false.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>NOVERIFY_CHECKSUMS</literal></term>
<term><literal>VERIFY_CHECKSUMS [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
<listitem>
<para>
By default, checksums are verified during a base backup if they are
enabled. Specifying <literal>NOVERIFY_CHECKSUMS</literal> disables
this verification.
If true, checksums are verified during a base backup if they are
enabled. If false, this is skipped. The default is true.
</para>
</listitem>
</varlistentry>
@@ -2708,6 +2711,7 @@ The commands accepted in replication mode are:
</varlistentry>
</variablelist>
</para>
<para>
After the second regular result set, one or more CopyOutResponse results
will be sent, one for the main data directory and one for each additional tablespace other
@@ -2788,6 +2792,17 @@ The commands accepted in replication mode are:
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>BASE_BACKUP</literal> [ <literal>LABEL</literal> <replaceable>'label'</replaceable> ] [ <literal>PROGRESS</literal> ] [ <literal>FAST</literal> ] [ <literal>WAL</literal> ] [ <literal>NOWAIT</literal> ] [ <literal>MAX_RATE</literal> <replaceable>rate</replaceable> ] [ <literal>TABLESPACE_MAP</literal> ] [ <literal>NOVERIFY_CHECKSUMS</literal> ] [ <literal>MANIFEST</literal> <replaceable>manifest_option</replaceable> ] [ <literal>MANIFEST_CHECKSUMS</literal> <replaceable>checksum_algorithm</replaceable> ]
</term>
<listitem>
<para>
For compatibility with older releases, this alternative syntax for
the <literal>BASE_BACKUP</literal> command is still supported.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>