Skip to content

Commit 0ba281c

Browse files
robertmhaasrobertmhaas
committed
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 parent 6860198 commit 0ba281c

File tree

6 files changed

+276
-83
lines changed

6 files changed

+276
-83
lines changed

‎doc/src/sgml/protocol.sgml

Lines changed: 41 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -2517,7 +2517,7 @@ The commands accepted in replication mode are:
25172517
</varlistentry>
25182518

25192519
<varlistentry id="protocol-replication-base-backup" xreflabel="BASE_BACKUP">
2520-
<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> ]
2520+
<term><literal>BASE_BACKUP</literal> [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ]
25212521
<indexterm><primary>BASE_BACKUP</primary></indexterm>
25222522
</term>
25232523
<listitem>
@@ -2540,52 +2540,55 @@ The commands accepted in replication mode are:
25402540
</varlistentry>
25412541

25422542
<varlistentry>
2543-
<term><literal>PROGRESS</literal></term>
2543+
<term><literal>PROGRESS [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
25442544
<listitem>
25452545
<para>
2546-
Request information required to generate a progress report. This will
2547-
send back an approximate size in the header of each tablespace, which
2548-
can be used to calculate how far along the stream is done. This is
2549-
calculated by enumerating all the file sizes once before the transfer
2550-
is even started, and might as such have a negative impact on the
2551-
performance. In particular, it might take longer before the first data
2546+
If set to true, request information required to generate a progress
2547+
report. This will send back an approximate size in the header of each
2548+
tablespace, which can be used to calculate how far along the stream
2549+
is done. This is calculated by enumerating all the file sizes once
2550+
before the transfer is even started, and might as such have a
2551+
negative impact on the performance. In particular, it might take
2552+
longer before the first data
25522553
is streamed. Since the database files can change during the backup,
25532554
the size is only approximate and might both grow and shrink between
25542555
the time of approximation and the sending of the actual files.
2556+
The default is false.
25552557
</para>
25562558
</listitem>
25572559
</varlistentry>
25582560

25592561
<varlistentry>
2560-
<term><literal>FAST</literal></term>
2562+
<term><literal>CHECKPOINT { 'fast' | 'spread' }</literal></term>
25612563
<listitem>
25622564
<para>
2563-
Request a fast checkpoint.
2565+
Sets the type of checkpoint to be performed at the beginning of the
2566+
base backup. The default is <literal>spread</literal>.
25642567
</para>
25652568
</listitem>
25662569
</varlistentry>
25672570

25682571
<varlistentry>
2569-
<term><literal>WAL</literal></term>
2572+
<term><literal>WAL [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
25702573
<listitem>
25712574
<para>
2572-
Include the necessary WAL segments in the backup. This will include
2573-
all the files between start and stop backup in the
2575+
If set to true, include the necessary WAL segments in the backup.
2576+
This will include all the files between start and stop backup in the
25742577
<filename>pg_wal</filename> directory of the base directory tar
2575-
file.
2578+
file. The default is false.
25762579
</para>
25772580
</listitem>
25782581
</varlistentry>
25792582

25802583
<varlistentry>
2581-
<term><literal>NOWAIT</literal></term>
2584+
<term><literal>WAIT [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
25822585
<listitem>
25832586
<para>
2584-
By default, the backup will wait until the last required WAL
2587+
If set to true, the backup will wait until the last required WAL
25852588
segment has been archived, or emit a warning if log archiving is
2586-
not enabled. Specifying <literal>NOWAIT</literal> disables both
2587-
the waiting and the warning, leaving the client responsible for
2588-
ensuring the required log is available.
2589+
not enabled. If false, the backup will neither wait nor warn,
2590+
leaving the client responsible for ensuring the required log is
2591+
available. The default is true.
25892592
</para>
25902593
</listitem>
25912594
</varlistentry>
@@ -2605,25 +2608,25 @@ The commands accepted in replication mode are:
26052608
</varlistentry>
26062609

26072610
<varlistentry>
2608-
<term><literal>TABLESPACE_MAP</literal></term>
2611+
<term><literal>TABLESPACE_MAP [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
26092612
<listitem>
26102613
<para>
2611-
Include information about symbolic links present in the directory
2612-
<filename>pg_tblspc</filename> in a file named
2614+
If true, include information about symbolic links present in the
2615+
directory <filename>pg_tblspc</filename> in a file named
26132616
<filename>tablespace_map</filename>. The tablespace map file includes
26142617
each symbolic link name as it exists in the directory
26152618
<filename>pg_tblspc/</filename> and the full path of that symbolic link.
2619+
The default is false.
26162620
</para>
26172621
</listitem>
26182622
</varlistentry>
26192623

26202624
<varlistentry>
2621-
<term><literal>NOVERIFY_CHECKSUMS</literal></term>
2625+
<term><literal>VERIFY_CHECKSUMS [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
26222626
<listitem>
26232627
<para>
2624-
By default, checksums are verified during a base backup if they are
2625-
enabled. Specifying <literal>NOVERIFY_CHECKSUMS</literal> disables
2626-
this verification.
2628+
If true, checksums are verified during a base backup if they are
2629+
enabled. If false, this is skipped. The default is true.
26272630
</para>
26282631
</listitem>
26292632
</varlistentry>
@@ -2708,6 +2711,7 @@ The commands accepted in replication mode are:
27082711
</varlistentry>
27092712
</variablelist>
27102713
</para>
2714+
27112715
<para>
27122716
After the second regular result set, one or more CopyOutResponse results
27132717
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:
27882792
</para>
27892793
</listitem>
27902794
</varlistentry>
2795+
2796+
<varlistentry>
2797+
<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> ]
2798+
</term>
2799+
<listitem>
2800+
<para>
2801+
For compatibility with older releases, this alternative syntax for
2802+
the <literal>BASE_BACKUP</literal> command is still supported.
2803+
</para>
2804+
</listitem>
2805+
</varlistentry>
27912806
</variablelist>
27922807

27932808
</para>

‎src/backend/replication/basebackup.c

Lines changed: 32 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
#include "access/xlog_internal.h" /* for pg_start/stop_backup */
2020
#include "catalog/pg_type.h"
2121
#include "common/file_perm.h"
22+
#include "commands/defrem.h"
2223
#include "commands/progress.h"
2324
#include "lib/stringinfo.h"
2425
#include "libpq/libpq.h"
@@ -764,7 +765,7 @@ parse_basebackup_options(List *options, basebackup_options *opt)
764765
ListCell *lopt;
765766
bool o_label = false;
766767
bool o_progress = false;
767-
bool o_fast = false;
768+
bool o_checkpoint = false;
768769
bool o_nowait = false;
769770
bool o_wal = false;
770771
bool o_maxrate = false;
@@ -787,7 +788,7 @@ parse_basebackup_options(List *options, basebackup_options *opt)
787788
ereport(ERROR,
788789
(errcode(ERRCODE_SYNTAX_ERROR),
789790
errmsg("duplicate option \"%s\"", defel->defname)));
790-
opt->label = strVal(defel->arg);
791+
opt->label = defGetString(defel);
791792
o_label = true;
792793
}
793794
else if (strcmp(defel->defname, "progress") == 0)
@@ -796,25 +797,35 @@ parse_basebackup_options(List *options, basebackup_options *opt)
796797
ereport(ERROR,
797798
(errcode(ERRCODE_SYNTAX_ERROR),
798799
errmsg("duplicate option \"%s\"", defel->defname)));
799-
opt->progress = true;
800+
opt->progress = defGetBoolean(defel);
800801
o_progress = true;
801802
}
802-
else if (strcmp(defel->defname, "fast") == 0)
803+
else if (strcmp(defel->defname, "checkpoint") == 0)
803804
{
804-
if (o_fast)
805+
char *optval = defGetString(defel);
806+
807+
if (o_checkpoint)
805808
ereport(ERROR,
806809
(errcode(ERRCODE_SYNTAX_ERROR),
807810
errmsg("duplicate option \"%s\"", defel->defname)));
808-
opt->fastcheckpoint = true;
809-
o_fast = true;
811+
if (pg_strcasecmp(optval, "fast") == 0)
812+
opt->fastcheckpoint = true;
813+
else if (pg_strcasecmp(optval, "spread") == 0)
814+
opt->fastcheckpoint = false;
815+
else
816+
ereport(ERROR,
817+
(errcode(ERRCODE_SYNTAX_ERROR),
818+
errmsg("unrecognized checkpoint type: \"%s\"",
819+
optval)));
820+
o_checkpoint = true;
810821
}
811-
else if (strcmp(defel->defname, "nowait") == 0)
822+
else if (strcmp(defel->defname, "wait") == 0)
812823
{
813824
if (o_nowait)
814825
ereport(ERROR,
815826
(errcode(ERRCODE_SYNTAX_ERROR),
816827
errmsg("duplicate option \"%s\"", defel->defname)));
817-
opt->nowait = true;
828+
opt->nowait = !defGetBoolean(defel);
818829
o_nowait = true;
819830
}
820831
else if (strcmp(defel->defname, "wal") == 0)
@@ -823,19 +834,19 @@ parse_basebackup_options(List *options, basebackup_options *opt)
823834
ereport(ERROR,
824835
(errcode(ERRCODE_SYNTAX_ERROR),
825836
errmsg("duplicate option \"%s\"", defel->defname)));
826-
opt->includewal = true;
837+
opt->includewal = defGetBoolean(defel);
827838
o_wal = true;
828839
}
829840
else if (strcmp(defel->defname, "max_rate") == 0)
830841
{
831-
long maxrate;
842+
int64 maxrate;
832843

833844
if (o_maxrate)
834845
ereport(ERROR,
835846
(errcode(ERRCODE_SYNTAX_ERROR),
836847
errmsg("duplicate option \"%s\"", defel->defname)));
837848

838-
maxrate = intVal(defel->arg);
849+
maxrate = defGetInt64(defel);
839850
if (maxrate < MAX_RATE_LOWER || maxrate > MAX_RATE_UPPER)
840851
ereport(ERROR,
841852
(errcode(ERRCODE_NUMERIC_VALUE_OUT_OF_RANGE),
@@ -851,21 +862,21 @@ parse_basebackup_options(List *options, basebackup_options *opt)
851862
ereport(ERROR,
852863
(errcode(ERRCODE_SYNTAX_ERROR),
853864
errmsg("duplicate option \"%s\"", defel->defname)));
854-
opt->sendtblspcmapfile = true;
865+
opt->sendtblspcmapfile = defGetBoolean(defel);
855866
o_tablespace_map = true;
856867
}
857-
else if (strcmp(defel->defname, "noverify_checksums") == 0)
868+
else if (strcmp(defel->defname, "verify_checksums") == 0)
858869
{
859870
if (o_noverify_checksums)
860871
ereport(ERROR,
861872
(errcode(ERRCODE_SYNTAX_ERROR),
862873
errmsg("duplicate option \"%s\"", defel->defname)));
863-
noverify_checksums = true;
874+
noverify_checksums = !defGetBoolean(defel);
864875
o_noverify_checksums = true;
865876
}
866877
else if (strcmp(defel->defname, "manifest") == 0)
867878
{
868-
char *optval = strVal(defel->arg);
879+
char *optval = defGetString(defel);
869880
bool manifest_bool;
870881

871882
if (o_manifest)
@@ -890,7 +901,7 @@ parse_basebackup_options(List *options, basebackup_options *opt)
890901
}
891902
else if (strcmp(defel->defname, "manifest_checksums") == 0)
892903
{
893-
char *optval = strVal(defel->arg);
904+
char *optval = defGetString(defel);
894905

895906
if (o_manifest_checksums)
896907
ereport(ERROR,
@@ -905,8 +916,10 @@ parse_basebackup_options(List *options, basebackup_options *opt)
905916
o_manifest_checksums = true;
906917
}
907918
else
908-
elog(ERROR, "option \"%s\" not recognized",
909-
defel->defname);
919+
ereport(ERROR,
920+
errcode(ERRCODE_SYNTAX_ERROR),
921+
errmsg("option \"%s\" not recognized",
922+
defel->defname));
910923
}
911924
if (opt->label == NULL)
912925
opt->label = "base backup";

0 commit comments

Comments
 (0)