Make wal streaming the default mode for pg_basebackup

Since streaming is now supported for all output formats, make this the
default as this is what most people want.

To get the old behavior, the parameter -X none can be specified to turn
it off.

This also removes the parameter -x for fetch, now requiring -X fetch to
be specified to use that.

Reviewed by Vladimir Rusinov, Michael Paquier and Simon Riggs

Author: mhagander

doc/src/sgml/ref/pg_basebackup.sgml

@@ -56,7 +56,7 @@ PostgreSQL documentation
    and <filename>pg_hba.conf</filename> must explicitly permit the replication
    connection. The server must also be configured
    with <xref linkend="guc-max-wal-senders"> set high enough to leave at least
-   one session available for the backup.
+   one session available for the backup and one for WAL streaming (if used).
   </para>
 
   <para>
@@ -85,10 +85,8 @@ PostgreSQL documentation
     </listitem>
     <listitem>
      <para>
-      There is no guarantee that all WAL files required for the backup are archived
-      at the end of backup. If you are planning to use the backup for an archive
-      recovery and want to ensure that all required files are available at that moment,
-      you need to include them into the backup by using the <literal>-x</> option.
+      If you are using <literal>-X none</>, there is no guarantee that all
+      WAL files required for the backup are archived at the end of backup.
      </para>
     </listitem>
     <listitem>
@@ -284,34 +282,33 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
-     <varlistentry>
-      <term><option>-x</option></term>
-      <term><option>--xlog</option></term>
-      <listitem>
-       <para>
-        Using this option is equivalent of using <literal>-X</literal> with
-        method <literal>fetch</literal>.
-       </para>
-      </listitem>
-     </varlistentry>
-
      <varlistentry>
       <term><option>-X <replaceable class="parameter">method</replaceable></option></term>
       <term><option>--xlog-method=<replaceable class="parameter">method</replaceable></option></term>
       <listitem>
        <para>
         Includes the required transaction log files (WAL files) in the
         backup. This will include all transaction logs generated during
-        the backup. If this option is specified, it is possible to start
-        a postmaster directly in the extracted directory without the need
-        to consult the log archive, thus making this a completely standalone
-        backup.
+        the backup. Unless the method <literal>none</literal> is specified,
+        it is possible to start a postmaster directly in the extracted
+        directory without the need to consult the log archive, thus
+        making this a completely standalone backup.
        </para>
        <para>
         The following methods for collecting the transaction logs are
         supported:
 
         <variablelist>
+         <varlistentry>
+          <term><literal>n</literal></term>
+          <term><literal>none</literal></term>
+          <listitem>
+           <para>
+            Don't include transaction log in the backup.
+           </para>
+          </listitem>
+         </varlistentry>
+
          <varlistentry>
           <term><literal>f</literal></term>
           <term><literal>fetch</literal></term>
@@ -349,6 +346,9 @@ PostgreSQL documentation
             named <filename>pg_wal.tar</filename> (if the server is a version
             earlier than 10, the file will be named <filename>pg_xlog.tar</filename>).
            </para>
+           <para>
+            This value is the default.
+           </para>
           </listitem>
          </varlistentry>
         </variablelist>
@@ -699,7 +699,7 @@ PostgreSQL documentation
    To create a backup of a single-tablespace local database and compress
    this with <productname>bzip2</productname>:
 <screen>
-<prompt>$</prompt> <userinput>pg_basebackup -D - -Ft | bzip2 &gt; backup.tar.bz2</userinput>
+<prompt>$</prompt> <userinput>pg_basebackup -D - -Ft -X fetch | bzip2 &gt; backup.tar.bz2</userinput>
 </screen>
    (This command will fail if there are multiple tablespaces in the
    database.)

src/bin/pg_basebackup/pg_basebackup.c

@@ -71,8 +71,8 @@ static bool noclean = false;
 static bool showprogress = false;
 static int	verbose = 0;
 static int	compresslevel = 0;
-static bool includewal = false;
-static bool streamwal = false;
+static bool includewal = true;
+static bool streamwal = true;
 static bool fastcheckpoint = false;
 static bool writerecoveryconf = false;
 static bool do_sync = true;
@@ -325,8 +325,7 @@ usage(void)
 	printf(_("  -S, --slot=SLOTNAME    replication slot to use\n"));
 	printf(_("  -T, --tablespace-mapping=OLDDIR=NEWDIR\n"
 	  "                         relocate tablespace in OLDDIR to NEWDIR\n"));
-	printf(_("  -x, --xlog             include required WAL files in backup (fetch mode)\n"));
-	printf(_("  -X, --xlog-method=fetch|stream\n"
+	printf(_("  -X, --xlog-method=none|fetch|stream\n"
 			 "                         include required WAL files with specified method\n"));
 	printf(_("      --xlogdir=XLOGDIR  location for the transaction log directory\n"));
 	printf(_("  -z, --gzip             compress tar output\n"));
@@ -1700,7 +1699,11 @@ BaseBackup(void)
 	 */
 	if (streamwal && !CheckServerVersionForStreaming(conn))
 	{
-		/* Error message already written in CheckServerVersionForStreaming() */
+		/*
+		 * Error message already written in CheckServerVersionForStreaming(),
+		 * but add a hint about using -X none.
+		 */
+		fprintf(stderr, _("HINT: use -X none or -X fetch to disable log streaming\n"));
 		disconnect_and_exit(1);
 	}
 
@@ -2035,7 +2038,6 @@ main(int argc, char **argv)
 		{"write-recovery-conf", no_argument, NULL, 'R'},
 		{"slot", required_argument, NULL, 'S'},
 		{"tablespace-mapping", required_argument, NULL, 'T'},
-		{"xlog", no_argument, NULL, 'x'},
 		{"xlog-method", required_argument, NULL, 'X'},
 		{"gzip", no_argument, NULL, 'z'},
 		{"compress", required_argument, NULL, 'Z'},
@@ -2078,7 +2080,7 @@ main(int argc, char **argv)
 
 	atexit(cleanup_directories_atexit);
 
-	while ((c = getopt_long(argc, argv, "D:F:r:RT:xX:l:nNzZ:d:c:h:p:U:s:S:wWvP",
+	while ((c = getopt_long(argc, argv, "D:F:r:RT:X:l:nNzZ:d:c:h:p:U:s:S:wWvP",
 							long_options, &option_index)) != -1)
 	{
 		switch (c)
@@ -2111,38 +2113,29 @@ main(int argc, char **argv)
 			case 'T':
 				tablespace_list_append(optarg);
 				break;
-			case 'x':
-				if (includewal)
-				{
-					fprintf(stderr,
-					 _("%s: cannot specify both --xlog and --xlog-method\n"),
-							progname);
-					exit(1);
-				}
-
-				includewal = true;
-				streamwal = false;
-				break;
 			case 'X':
-				if (includewal)
+				if (strcmp(optarg, "n") == 0 ||
+					strcmp(optarg, "none") == 0)
 				{
-					fprintf(stderr,
-					 _("%s: cannot specify both --xlog and --xlog-method\n"),
-							progname);
-					exit(1);
+					includewal = false;
+					streamwal = false;
 				}
-
-				includewal = true;
-				if (strcmp(optarg, "f") == 0 ||
+				else if (strcmp(optarg, "f") == 0 ||
 					strcmp(optarg, "fetch") == 0)
+				{
+					includewal = true;
 					streamwal = false;
+				}
 				else if (strcmp(optarg, "s") == 0 ||
 						 strcmp(optarg, "stream") == 0)
+				{
+					includewal = true;
 					streamwal = true;
+				}
 				else
 				{
 					fprintf(stderr,
-							_("%s: invalid xlog-method option \"%s\", must be \"fetch\" or \"stream\"\n"),
+							_("%s: invalid xlog-method option \"%s\", must be \"fetch\", \"stream\" or \"none\"\n"),
 							progname, optarg);
 					exit(1);
 				}

src/bin/pg_basebackup/t/010_pg_basebackup.pl

@@ -4,7 +4,7 @@
 use Config;
 use PostgresNode;
 use TestLib;
-use Test::More tests => 69;
+use Test::More tests => 71;
 
 program_help_ok('pg_basebackup');
 program_version_ok('pg_basebackup');
@@ -63,7 +63,7 @@
 	close FILE;
 }
 
-$node->command_ok([ 'pg_basebackup', '-D', "$tempdir/backup" ],
+$node->command_ok([ 'pg_basebackup', '-D', "$tempdir/backup", '-X', 'none' ],
 	'pg_basebackup runs');
 ok(-f "$tempdir/backup/PG_VERSION", 'backup was created');
 
@@ -225,6 +225,11 @@
 	qr/^primary_conninfo = '.*port=$port.*'\n/m,
 	'recovery.conf sets primary_conninfo');
 
+$node->command_ok([ 'pg_basebackup', '-D', "$tempdir/backupxd" ],
+	'pg_basebackup runs in default xlog mode');
+ok(grep(/^[0-9A-F]{24}$/, slurp_dir("$tempdir/backupxd/pg_wal")),
+	'WAL files copied');
+
 $node->command_ok(
 	[ 'pg_basebackup', '-D', "$tempdir/backupxf", '-X', 'fetch' ],
 	'pg_basebackup -X fetch runs');

src/test/perl/PostgresNode.pm

@@ -484,7 +484,7 @@ sub backup
 
 	print "# Taking pg_basebackup $backup_name from node \"$name\"\n";
 	TestLib::system_or_bail('pg_basebackup', '-D', $backup_path, '-p', $port,
-		'-x', '--no-sync');
+		'--no-sync');
 	print "# Backup finished\n";
 }