Flexible options for BASE_BACKUP.

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

1 files changed, 41 insertions, 26 deletions

diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index a232546b1d0..8ed88334442 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -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>