Add --parallel option to vacuumdb command.

Commit 40d964ec99 allowed vacuum command to leverage multiple CPUs by
invoking parallel workers to process indexes.  This commit provides a
'--parallel' option to specify the parallel degree used by vacuum command.

Author: Masahiko Sawada, with few modifications by me
Reviewed-by: Mahendra Singh and Amit Kapila
Discussion: https://postgr.es/m/CAD21AoDTPMgzSkV4E3SFo1CH_x50bf5PqZFQf4jmqjk-C03BWg@mail.gmail.com

diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml
index 47d93456f862009cb3519d13c4d71e7c59c03a02..775c9ec651b419ee5f78b46900a4df8ee2f83d29 100644 (file)
--- a/doc/src/sgml/ref/vacuumdb.sgml
+++ b/doc/src/sgml/ref/vacuumdb.sgml
@@ -226,6 +226,24 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term><option>-P <replaceable class="parameter">parallel_degree</replaceable></option></term>
+      <term><option>--parallel=<replaceable class="parameter">parallel_degree</replaceable></option></term>
+      <listitem>
+       <para>
+        Specify the parallel degree of <firstterm>parallel vacuum</firstterm>.
+        This allows the vacuum to leverage multiple CPUs to process indexes.
+        See <xref linkend="sql-vacuum"/>.
+       </para>
+       <note>
+        <para>
+         This option is only available for servers running
+         <productname>PostgreSQL</productname> 13 and later.
+        </para>
+       </note>
+      </listitem>
+     </varlistentry>
+
      <varlistentry>
       <term><option>-q</option></term>
       <term><option>--quiet</option></term>

diff --git a/src/bin/scripts/t/100_vacuumdb.pl b/src/bin/scripts/t/100_vacuumdb.pl
index b685b3528287031a853e6334b18701fd45e44908..c2284c8195f6ef3626261160a8916f294f757b50 100644 (file)
--- a/src/bin/scripts/t/100_vacuumdb.pl
+++ b/src/bin/scripts/t/100_vacuumdb.pl
@@ -3,7 +3,7 @@ use warnings;
 
 use PostgresNode;
 use TestLib;
-use Test::More tests => 44;
+use Test::More tests => 49;
 
 program_help_ok('vacuumdb');
 program_version_ok('vacuumdb');
@@ -48,6 +48,14 @@ $node->issues_sql_like(
 $node->command_fails(
        [ 'vacuumdb', '--analyze-only', '--disable-page-skipping', 'postgres' ],
        '--analyze-only and --disable-page-skipping specified together');
+$node->issues_sql_like(
+       [ 'vacuumdb', '-P', 2, 'postgres' ],
+       qr/statement: VACUUM \(PARALLEL 2\).*;/,
+       'vacuumdb -P 2');
+$node->issues_sql_like(
+       [ 'vacuumdb', '-P', 0, 'postgres' ],
+       qr/statement: VACUUM \(PARALLEL 0\).*;/,
+       'vacuumdb -P 0');
 $node->command_ok([qw(vacuumdb -Z --table=pg_am dbname=template1)],
        'vacuumdb with connection string');
 
@@ -81,6 +89,9 @@ $node->command_fails(
 $node->command_fails(
        [ 'vacuumdb', '--analyze', '--table', 'vactable(c)', 'postgres' ],
        'incorrect column name with ANALYZE');
+$node->command_fails(
+       [ 'vacuumdb', '-P', -1, 'postgres' ],
+       'negative parallel degree');
 $node->issues_sql_like(
        [ 'vacuumdb', '--analyze', '--table', 'vactable(a, b)', 'postgres' ],
        qr/statement: VACUUM \(ANALYZE\) public.vactable\(a, b\);/,

diff --git a/src/bin/scripts/vacuumdb.c b/src/bin/scripts/vacuumdb.c
index bfa6ac63553e4e06d7c51961887aff076570ccdb..0560f6304fff4fdb61697ec9c4e170963fab6626 100644 (file)
--- a/src/bin/scripts/vacuumdb.c
+++ b/src/bin/scripts/vacuumdb.c
@@ -35,6 +35,8 @@ typedef struct vacuumingOptions
        bool            skip_locked;
        int                     min_xid_age;
        int                     min_mxid_age;
+       int                     parallel_workers;       /* >= 0 indicates user specified the
+                                                                        * parallel degree, otherwise -1 */
 } vacuumingOptions;
 
 
@@ -87,6 +89,7 @@ main(int argc, char *argv[])
                {"full", no_argument, NULL, 'f'},
                {"verbose", no_argument, NULL, 'v'},
                {"jobs", required_argument, NULL, 'j'},
+               {"parallel", required_argument, NULL, 'P'},
                {"maintenance-db", required_argument, NULL, 2},
                {"analyze-in-stages", no_argument, NULL, 3},
                {"disable-page-skipping", no_argument, NULL, 4},
@@ -116,6 +119,7 @@ main(int argc, char *argv[])
 
        /* initialize options to all false */
        memset(&vacopts, 0, sizeof(vacopts));
+       vacopts.parallel_workers = -1;
 
        pg_logging_init(argv[0]);
        progname = get_progname(argv[0]);
@@ -123,7 +127,7 @@ main(int argc, char *argv[])
 
        handle_help_version_opts(argc, argv, "vacuumdb", help);
 
-       while ((c = getopt_long(argc, argv, "h:p:U:wWeqd:zZFat:fvj:", long_options, &optindex)) != -1)
+       while ((c = getopt_long(argc, argv, "h:p:U:wWeqd:zZFat:fvj:P:", long_options, &optindex)) != -1)
        {
                switch (c)
                {
@@ -183,6 +187,14 @@ main(int argc, char *argv[])
                                        exit(1);
                                }
                                break;
+                       case 'P':
+                               vacopts.parallel_workers = atoi(optarg);
+                               if (vacopts.parallel_workers < 0)
+                               {
+                                       pg_log_error("parallel vacuum degree must be a non-negative integer");
+                                       exit(1);
+                               }
+                               break;
                        case 2:
                                maintenance_db = pg_strdup(optarg);
                                break;
@@ -258,6 +270,23 @@ main(int argc, char *argv[])
                /* allow 'and_analyze' with 'analyze_only' */
        }
 
+       /* Prohibit full and analyze_only options with parallel option */
+       if (vacopts.parallel_workers >= 0)
+       {
+               if (vacopts.analyze_only)
+               {
+                       pg_log_error("cannot use the \"%s\" option when performing only analyze",
+                                                "parallel");
+                       exit(1);
+               }
+               if (vacopts.full)
+               {
+                       pg_log_error("cannot use the \"%s\" option when performing full",
+                                                "parallel");
+                       exit(1);
+               }
+       }
+
        setup_cancel_handler(NULL);
 
        /* Avoid opening extra connections. */
@@ -405,6 +434,13 @@ vacuum_one_database(const char *dbname, vacuumingOptions *vacopts,
                exit(1);
        }
 
+       if (vacopts->parallel_workers >= 0 && PQserverVersion(conn) < 130000)
+       {
+               pg_log_error("cannot use the \"%s\" option on server versions older than PostgreSQL %s",
+                                        "--parallel", "13");
+               exit(1);
+       }
+
        if (!quiet)
        {
                if (stage != ANALYZE_NO_STAGE)
@@ -823,6 +859,14 @@ prepare_vacuum_command(PQExpBuffer sql, int serverVersion,
                                appendPQExpBuffer(sql, "%sANALYZE", sep);
                                sep = comma;
                        }
+                       if (vacopts->parallel_workers >= 0)
+                       {
+                               /* PARALLEL is supported since v13 */
+                               Assert(serverVersion >= 130000);
+                               appendPQExpBuffer(sql, "%sPARALLEL %d", sep,
+                                                                 vacopts->parallel_workers);
+                               sep = comma;
+                       }
                        if (sep != paren)
                                appendPQExpBufferChar(sql, ')');
                }
@@ -886,6 +930,7 @@ help(const char *progname)
        printf(_("  -j, --jobs=NUM                  use this many concurrent connections to vacuum\n"));
        printf(_("      --min-mxid-age=MXID_AGE     minimum multixact ID age of tables to vacuum\n"));
        printf(_("      --min-xid-age=XID_AGE       minimum transaction ID age of tables to vacuum\n"));
+       printf(_("  -P, --parallel=PARALLEL_DEGREE  use this many background workers for vacuum, if available\n"));
        printf(_("  -q, --quiet                     don't write any messages\n"));
        printf(_("      --skip-locked               skip relations that cannot be immediately locked\n"));
        printf(_("  -t, --table='TABLE[(COLUMNS)]'  vacuum specific table(s) only\n"));