From 47aeb15eca62ec530231a6ddc63d5ab9fff1de76 Mon Sep 17 00:00:00 2001
From: Greg Nancarrow <gregn4422@gmail.com>
Date: Tue, 2 Feb 2021 10:30:35 +1100
Subject: [PATCH v3 2/2] Test and documentation updates for the GUC option
 "enable_parallel_dml".

---
 doc/src/sgml/config.sgml                      | 23 +++++++++++++++++++
 src/test/regress/expected/insert_parallel.out | 18 +++++++++++++++
 src/test/regress/expected/sysviews.out        |  3 ++-
 src/test/regress/sql/insert_parallel.sql      | 12 ++++++++++
 4 files changed, 55 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index e17cdcc816..7102265dde 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -5026,6 +5026,29 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="
       </listitem>
      </varlistentry>
 
+     <varlistentry id="guc-enable-parallel-dml" xreflabel="enable_parallel_dml">
+      <term><varname>enable_parallel_dml</varname> (<type>boolean</type>)
+      <indexterm>
+       <primary><varname>enable_parallel_dml</varname> configuration parameter</primary>
+      </indexterm>
+      </term>
+      <listitem>
+       <para>
+        Enables or disables the query planner's use of parallel plans for
+        table-modification commands. The default is <literal>off</literal>.
+        When enabled, the planner performs additional parallel-safety checks
+        on the target table's attributes and indexes, in order to determine
+        if it's safe to use a parallel plan for table-modification. In cases
+        such as when the target table has a large number of partitions, and
+        particularly also when that table uses something parallel-unsafe that
+        prevents parallelism, the overhead of these checks may become
+        prohibitively high. To address this potential overhead in these cases,
+        this option can be used to disable the use of parallel plans for
+        table-modification.
+       </para>
+      </listitem>
+     </varlistentry>
+
      </variablelist>
      </sect2>
      <sect2 id="runtime-config-query-constants">
diff --git a/src/test/regress/expected/insert_parallel.out b/src/test/regress/expected/insert_parallel.out
index 3b922a2c3d..f98d1aec7f 100644
--- a/src/test/regress/expected/insert_parallel.out
+++ b/src/test/regress/expected/insert_parallel.out
@@ -76,9 +76,27 @@ create table para_insert_f1 (
 	stringu1	name
 );
 --
+-- Test INSERT with underlying query when enable_parallel_dml=off.
+-- (should create plan with serial INSERT + SELECT)
+--
+explain(costs off) insert into para_insert_p1 select unique1, stringu1 from tenk1;
+        QUERY PLAN        
+--------------------------
+ Insert on para_insert_p1
+   ->  Seq Scan on tenk1
+(2 rows)
+
+insert into para_insert_p1 select unique1, stringu1 from tenk1;
+--
+-- Enable parallel dml
+--
+set enable_parallel_dml = on;
+--
 -- Test INSERT with underlying query.
 -- (should create plan with parallel INSERT+SELECT, Gather parent node)
 --
+truncate para_insert_p1 cascade;
+NOTICE:  truncate cascades to table "para_insert_f1"
 explain(costs off) insert into para_insert_p1 select unique1, stringu1 from tenk1;
                QUERY PLAN               
 ----------------------------------------
diff --git a/src/test/regress/expected/sysviews.out b/src/test/regress/expected/sysviews.out
index 81bdacf59d..3f11216809 100644
--- a/src/test/regress/expected/sysviews.out
+++ b/src/test/regress/expected/sysviews.out
@@ -99,6 +99,7 @@ select name, setting from pg_settings where name like 'enable%';
  enable_mergejoin               | on
  enable_nestloop                | on
  enable_parallel_append         | on
+ enable_parallel_dml            | off
  enable_parallel_hash           | on
  enable_partition_pruning       | on
  enable_partitionwise_aggregate | off
@@ -106,7 +107,7 @@ select name, setting from pg_settings where name like 'enable%';
  enable_seqscan                 | on
  enable_sort                    | on
  enable_tidscan                 | on
-(18 rows)
+(19 rows)
 
 -- Test that the pg_timezone_names and pg_timezone_abbrevs views are
 -- more-or-less working.  We can't test their contents in any great detail
diff --git a/src/test/regress/sql/insert_parallel.sql b/src/test/regress/sql/insert_parallel.sql
index 34a191f7c5..531731378e 100644
--- a/src/test/regress/sql/insert_parallel.sql
+++ b/src/test/regress/sql/insert_parallel.sql
@@ -94,11 +94,23 @@ create table para_insert_f1 (
 	stringu1	name
 );
 
+--
+-- Test INSERT with underlying query when enable_parallel_dml=off.
+-- (should create plan with serial INSERT + SELECT)
+--
+explain(costs off) insert into para_insert_p1 select unique1, stringu1 from tenk1;
+insert into para_insert_p1 select unique1, stringu1 from tenk1;
+
+--
+-- Enable parallel dml
+--
+set enable_parallel_dml = on;
 
 --
 -- Test INSERT with underlying query.
 -- (should create plan with parallel INSERT+SELECT, Gather parent node)
 --
+truncate para_insert_p1 cascade;
 explain(costs off) insert into para_insert_p1 select unique1, stringu1 from tenk1;
 insert into para_insert_p1 select unique1, stringu1 from tenk1;
 -- select some values to verify that the parallel insert worked
-- 
2.27.0