Skip to content

Commit 5352ca2

Browse files
david-rowleydavid-rowley
committed
Rename force_parallel_mode to debug_parallel_query
force_parallel_mode is meant to be used to allow us to exercise the parallel query infrastructure to ensure that it's working as we expect. It seems some users think this GUC is for forcing the query planner into picking a parallel plan regardless of the costs. A quick look at the documentation would have made them realize that they were wrong, but the GUC is likely too conveniently named which, evidently, seems to often result in users expecting that it forces the planner into usefully parallelizing queries. Here we rename the GUC to something which casual users are less likely to mistakenly think is what they need to make their query run more quickly. For now, the old name can still be used. We'll revisit if the old name mapping can be removed once the buildfarm configs are all updated. Reviewed-by: John Naylor Discussion: https://postgr.es/m/CAApHDvrsOi92_uA7PEaHZMH-S4Xv+MGhQWA+GrP8b1kjpS1HjQ@mail.gmail.com
1 parent 8e0e069 commit 5352ca2

File tree

23 files changed

+79
-76
lines changed

23 files changed

+79
-76
lines changed

‎doc/src/sgml/config.sgml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11091,17 +11091,17 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
1109111091
</listitem>
1109211092
</varlistentry>
1109311093

11094-
<varlistentry id="guc-force-parallel-mode" xreflabel="force_parallel_mode">
11095-
<term><varname>force_parallel_mode</varname> (<type>enum</type>)
11094+
<varlistentry id="guc-debug-parallel-query" xreflabel="debug_parallel_query">
11095+
<term><varname>debug_parallel_query</varname> (<type>enum</type>)
1109611096
<indexterm>
11097-
<primary><varname>force_parallel_mode</varname> configuration parameter</primary>
11097+
<primary><varname>debug_parallel_query</varname> configuration parameter</primary>
1109811098
</indexterm>
1109911099
</term>
1110011100
<listitem>
1110111101
<para>
1110211102
Allows the use of parallel queries for testing purposes even in cases
1110311103
where no performance benefit is expected.
11104-
The allowed values of <varname>force_parallel_mode</varname> are
11104+
The allowed values of <varname>debug_parallel_query</varname> are
1110511105
<literal>off</literal> (use parallel mode only when it is expected to improve
1110611106
performance), <literal>on</literal> (force parallel query for all queries
1110711107
for which it is thought to be safe), and <literal>regress</literal> (like

‎doc/src/sgml/regress.sgml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -370,7 +370,7 @@ make check LANG=C ENCODING=EUC_JP
370370
set in the <varname>PGOPTIONS</varname> environment variable (for settings
371371
that allow this):
372372
<screen>
373-
make check PGOPTIONS="-c force_parallel_mode=regress -c work_mem=50MB"
373+
make check PGOPTIONS="-c debug_parallel_query=regress -c work_mem=50MB"
374374
</screen>
375375
When running against a temporary installation, custom settings can also be
376376
set by supplying a pre-written <filename>postgresql.conf</filename>:

‎src/backend/access/transam/parallel.c

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1152,11 +1152,11 @@ HandleParallelMessage(ParallelContext *pcxt, int i, StringInfo msg)
11521152
* If desired, add a context line to show that this is a
11531153
* message propagated from a parallel worker. Otherwise, it
11541154
* can sometimes be confusing to understand what actually
1155-
* happened. (We don't do this in FORCE_PARALLEL_REGRESS mode
1155+
* happened. (We don't do this in DEBUG_PARALLEL_REGRESS mode
11561156
* because it causes test-result instability depending on
11571157
* whether a parallel worker is actually used or not.)
11581158
*/
1159-
if (force_parallel_mode != FORCE_PARALLEL_REGRESS)
1159+
if (debug_parallel_query != DEBUG_PARALLEL_REGRESS)
11601160
{
11611161
if (edata.context)
11621162
edata.context = psprintf("%s\n%s", edata.context,

‎src/backend/commands/explain.c

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -756,8 +756,8 @@ ExplainPrintPlan(ExplainState *es, QueryDesc *queryDesc)
756756
/*
757757
* Sometimes we mark a Gather node as "invisible", which means that it's
758758
* not to be displayed in EXPLAIN output. The purpose of this is to allow
759-
* running regression tests with force_parallel_mode=regress to get the
760-
* same results as running the same tests with force_parallel_mode=off.
759+
* running regression tests with debug_parallel_query=regress to get the
760+
* same results as running the same tests with debug_parallel_query=off.
761761
* Such marking is currently only supported on a Gather at the top of the
762762
* plan. We skip that node, and we must also hide per-worker detail data
763763
* further down in the plan tree.

‎src/backend/optimizer/plan/planmain.c

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -114,12 +114,12 @@ query_planner(PlannerInfo *root,
114114
* Anything parallel-restricted in the query tlist will be
115115
* dealt with later.) This is normally pretty silly, because
116116
* a Result-only plan would never be interesting to
117-
* parallelize. However, if force_parallel_mode is on, then
117+
* parallelize. However, if debug_parallel_query is on, then
118118
* we want to execute the Result in a parallel worker if
119119
* possible, so we must do this.
120120
*/
121121
if (root->glob->parallelModeOK &&
122-
force_parallel_mode != FORCE_PARALLEL_OFF)
122+
debug_parallel_query != DEBUG_PARALLEL_OFF)
123123
final_rel->consider_parallel =
124124
is_parallel_safe(root, parse->jointree->quals);
125125

‎src/backend/optimizer/plan/planner.c

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@
7070

7171
/* GUC parameters */
7272
double cursor_tuple_fraction = DEFAULT_CURSOR_TUPLE_FRACTION;
73-
int force_parallel_mode = FORCE_PARALLEL_OFF;
73+
int debug_parallel_query = DEBUG_PARALLEL_OFF;
7474
bool parallel_leader_participation = true;
7575

7676
/* Hook for plugins to get control in planner() */
@@ -364,20 +364,20 @@ standard_planner(Query *parse, const char *query_string, int cursorOptions,
364364
* true during plan creation if a Gather or Gather Merge plan is actually
365365
* created (cf. create_gather_plan, create_gather_merge_plan).
366366
*
367-
* However, if force_parallel_mode = on or force_parallel_mode = regress,
368-
* then we impose parallel mode whenever it's safe to do so, even if the
369-
* final plan doesn't use parallelism. It's not safe to do so if the
370-
* query contains anything parallel-unsafe; parallelModeOK will be false
371-
* in that case. Note that parallelModeOK can't change after this point.
372-
* Otherwise, everything in the query is either parallel-safe or
367+
* However, if debug_parallel_query = on or debug_parallel_query =
368+
* regress, then we impose parallel mode whenever it's safe to do so, even
369+
* if the final plan doesn't use parallelism. It's not safe to do so if
370+
* the query contains anything parallel-unsafe; parallelModeOK will be
371+
* false in that case. Note that parallelModeOK can't change after this
372+
* point. Otherwise, everything in the query is either parallel-safe or
373373
* parallel-restricted, and in either case it should be OK to impose
374374
* parallel-mode restrictions. If that ends up breaking something, then
375375
* either some function the user included in the query is incorrectly
376376
* labeled as parallel-safe or parallel-restricted when in reality it's
377377
* parallel-unsafe, or else the query planner itself has a bug.
378378
*/
379379
glob->parallelModeNeeded = glob->parallelModeOK &&
380-
(force_parallel_mode != FORCE_PARALLEL_OFF);
380+
(debug_parallel_query != DEBUG_PARALLEL_OFF);
381381

382382
/* Determine what fraction of the plan is likely to be scanned */
383383
if (cursorOptions & CURSOR_OPT_FAST_PLAN)
@@ -431,7 +431,7 @@ standard_planner(Query *parse, const char *query_string, int cursorOptions,
431431
* Optionally add a Gather node for testing purposes, provided this is
432432
* actually a safe thing to do.
433433
*/
434-
if (force_parallel_mode != FORCE_PARALLEL_OFF && top_plan->parallel_safe)
434+
if (debug_parallel_query != DEBUG_PARALLEL_OFF && top_plan->parallel_safe)
435435
{
436436
Gather *gather = makeNode(Gather);
437437

@@ -449,7 +449,7 @@ standard_planner(Query *parse, const char *query_string, int cursorOptions,
449449
gather->plan.righttree = NULL;
450450
gather->num_workers = 1;
451451
gather->single_copy = true;
452-
gather->invisible = (force_parallel_mode == FORCE_PARALLEL_REGRESS);
452+
gather->invisible = (debug_parallel_query == DEBUG_PARALLEL_REGRESS);
453453

454454
/*
455455
* Since this Gather has no parallel-aware descendants to signal to,

‎src/backend/utils/misc/guc.c

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -186,6 +186,7 @@ static const unit_conversion time_unit_conversion_table[] =
186186
static const char *const map_old_guc_names[] = {
187187
"sort_mem", "work_mem",
188188
"vacuum_mem", "maintenance_work_mem",
189+
"force_parallel_mode", "debug_parallel_query",
189190
NULL
190191
};
191192

‎src/backend/utils/misc/guc_tables.c

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -360,16 +360,16 @@ static const struct config_enum_entry recovery_prefetch_options[] = {
360360
{NULL, 0, false}
361361
};
362362

363-
static const struct config_enum_entry force_parallel_mode_options[] = {
364-
{"off", FORCE_PARALLEL_OFF, false},
365-
{"on", FORCE_PARALLEL_ON, false},
366-
{"regress", FORCE_PARALLEL_REGRESS, false},
367-
{"true", FORCE_PARALLEL_ON, true},
368-
{"false", FORCE_PARALLEL_OFF, true},
369-
{"yes", FORCE_PARALLEL_ON, true},
370-
{"no", FORCE_PARALLEL_OFF, true},
371-
{"1", FORCE_PARALLEL_ON, true},
372-
{"0", FORCE_PARALLEL_OFF, true},
363+
static const struct config_enum_entry debug_parallel_query_options[] = {
364+
{"off", DEBUG_PARALLEL_OFF, false},
365+
{"on", DEBUG_PARALLEL_ON, false},
366+
{"regress", DEBUG_PARALLEL_REGRESS, false},
367+
{"true", DEBUG_PARALLEL_ON, true},
368+
{"false", DEBUG_PARALLEL_OFF, true},
369+
{"yes", DEBUG_PARALLEL_ON, true},
370+
{"no", DEBUG_PARALLEL_OFF, true},
371+
{"1", DEBUG_PARALLEL_ON, true},
372+
{"0", DEBUG_PARALLEL_OFF, true},
373373
{NULL, 0, false}
374374
};
375375

@@ -4852,13 +4852,15 @@ struct config_enum ConfigureNamesEnum[] =
48524852
},
48534853

48544854
{
4855-
{"force_parallel_mode", PGC_USERSET, DEVELOPER_OPTIONS,
4856-
gettext_noop("Forces use of parallel query facilities."),
4857-
gettext_noop("If possible, run query using a parallel worker and with parallel restrictions."),
4855+
{"debug_parallel_query", PGC_USERSET, DEVELOPER_OPTIONS,
4856+
gettext_noop("Forces the planner's use parallel query nodes."),
4857+
gettext_noop("This can be useful for testing the parallel query infrastructure "
4858+
"by forcing the planner to generate plans which contains nodes "
4859+
"which perform tuple communication between workers and the main process."),
48584860
GUC_NOT_IN_SAMPLE | GUC_EXPLAIN
48594861
},
4860-
&force_parallel_mode,
4861-
FORCE_PARALLEL_OFF, force_parallel_mode_options,
4862+
&debug_parallel_query,
4863+
DEBUG_PARALLEL_OFF, debug_parallel_query_options,
48624864
NULL, NULL, NULL
48634865
},
48644866

‎src/include/optimizer/optimizer.h

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -99,16 +99,16 @@ extern bool is_pseudo_constant_for_index(PlannerInfo *root, Node *expr,
9999

100100
/* in plan/planner.c: */
101101

102-
/* possible values for force_parallel_mode */
102+
/* possible values for debug_parallel_query */
103103
typedef enum
104104
{
105-
FORCE_PARALLEL_OFF,
106-
FORCE_PARALLEL_ON,
107-
FORCE_PARALLEL_REGRESS
108-
} ForceParallelMode;
105+
DEBUG_PARALLEL_OFF,
106+
DEBUG_PARALLEL_ON,
107+
DEBUG_PARALLEL_REGRESS
108+
} DebugParallelMode;
109109

110110
/* GUC parameters */
111-
extern PGDLLIMPORT int force_parallel_mode;
111+
extern PGDLLIMPORT int debug_parallel_query;
112112
extern PGDLLIMPORT bool parallel_leader_participation;
113113

114114
extern struct PlannedStmt *planner(Query *parse, const char *query_string,

‎src/pl/plpgsql/src/pl_exec.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8066,7 +8066,7 @@ exec_save_simple_expr(PLpgSQL_expr *expr, CachedPlan *cplan)
80668066

80678067
/*
80688068
* Ordinarily, the plan node should be a simple Result. However, if
8069-
* force_parallel_mode is on, the planner might've stuck a Gather node
8069+
* debug_parallel_query is on, the planner might've stuck a Gather node
80708070
* atop that. The simplest way to deal with this is to look through the
80718071
* Gather node. The Gather node's tlist would normally contain a Var
80728072
* referencing the child node's output, but it could also be a Param, or

‎src/test/isolation/expected/deadlock-parallel.out

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,21 +15,21 @@ lock_share
1515

1616
step e1l: SELECT lock_excl(1,x) FROM bigt LIMIT 1; <waiting ...>
1717
step e2l: SELECT lock_excl(2,x) FROM bigt LIMIT 1; <waiting ...>
18-
step d1a2: SET force_parallel_mode = on;
18+
step d1a2: SET debug_parallel_query = on;
1919
SET parallel_setup_cost = 0;
2020
SET parallel_tuple_cost = 0;
2121
SET min_parallel_table_scan_size = 0;
2222
SET parallel_leader_participation = off;
2323
SET max_parallel_workers_per_gather = 3;
2424
SELECT sum(lock_share(2,x)) FROM bigt; <waiting ...>
25-
step d2a1: SET force_parallel_mode = on;
25+
step d2a1: SET debug_parallel_query = on;
2626
SET parallel_setup_cost = 0;
2727
SET parallel_tuple_cost = 0;
2828
SET min_parallel_table_scan_size = 0;
2929
SET parallel_leader_participation = off;
3030
SET max_parallel_workers_per_gather = 3;
3131
SELECT sum(lock_share(1,x)) FROM bigt;
32-
SET force_parallel_mode = off;
32+
SET debug_parallel_query = off;
3333
RESET parallel_setup_cost;
3434
RESET parallel_tuple_cost;
3535
SELECT lock_share(3,x) FROM bigt LIMIT 1; <waiting ...>

‎src/test/isolation/specs/deadlock-parallel.spec

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
# and is incorrectly marked parallel-safe so that it can execute in a worker.
77

88
# Note that we explicitly override any global settings of isolation level
9-
# or force_parallel_mode, to ensure we're testing what we intend to.
9+
# or debug_parallel_query, to ensure we're testing what we intend to.
1010

1111
# Otherwise, this is morally equivalent to deadlock-soft.spec:
1212
# Four-process deadlock with two hard edges and two soft edges.
@@ -55,13 +55,13 @@ teardown
5555

5656
session d1
5757
setup { BEGIN isolation level repeatable read;
58-
SET force_parallel_mode = off;
58+
SET debug_parallel_query = off;
5959
SET deadlock_timeout = '10s';
6060
}
6161
# these locks will be taken in the leader, so they will persist:
6262
step d1a1 { SELECT lock_share(1,x), lock_excl(3,x) FROM bigt LIMIT 1; }
6363
# this causes all the parallel workers to take locks:
64-
step d1a2 { SET force_parallel_mode = on;
64+
step d1a2 { SET debug_parallel_query = on;
6565
SET parallel_setup_cost = 0;
6666
SET parallel_tuple_cost = 0;
6767
SET min_parallel_table_scan_size = 0;
@@ -72,29 +72,29 @@ step d1c { COMMIT; }
7272

7373
session d2
7474
setup { BEGIN isolation level repeatable read;
75-
SET force_parallel_mode = off;
75+
SET debug_parallel_query = off;
7676
SET deadlock_timeout = '10ms';
7777
}
7878
# this lock will be taken in the leader, so it will persist:
7979
step d2a2 { select lock_share(2,x) FROM bigt LIMIT 1; }
8080
# this causes all the parallel workers to take locks;
8181
# after which, make the leader take lock 3 to prevent client-driven deadlock
82-
step d2a1 { SET force_parallel_mode = on;
82+
step d2a1 { SET debug_parallel_query = on;
8383
SET parallel_setup_cost = 0;
8484
SET parallel_tuple_cost = 0;
8585
SET min_parallel_table_scan_size = 0;
8686
SET parallel_leader_participation = off;
8787
SET max_parallel_workers_per_gather = 3;
8888
SELECT sum(lock_share(1,x)) FROM bigt;
89-
SET force_parallel_mode = off;
89+
SET debug_parallel_query = off;
9090
RESET parallel_setup_cost;
9191
RESET parallel_tuple_cost;
9292
SELECT lock_share(3,x) FROM bigt LIMIT 1; }
9393
step d2c { COMMIT; }
9494

9595
session e1
9696
setup { BEGIN isolation level repeatable read;
97-
SET force_parallel_mode = on;
97+
SET debug_parallel_query = on;
9898
SET deadlock_timeout = '10s';
9999
}
100100
# this lock will be taken in a parallel worker, but we don't need it to persist
@@ -103,7 +103,7 @@ step e1c { COMMIT; }
103103

104104
session e2
105105
setup { BEGIN isolation level repeatable read;
106-
SET force_parallel_mode = on;
106+
SET debug_parallel_query = on;
107107
SET deadlock_timeout = '10s';
108108
}
109109
# this lock will be taken in a parallel worker, but we don't need it to persist

‎src/test/isolation/specs/serializable-parallel.spec

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ step s2c { COMMIT; }
3535
session s3
3636
setup {
3737
BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE;
38-
SET force_parallel_mode = on;
38+
SET debug_parallel_query = on;
3939
}
4040
step s3r { SELECT id, balance FROM bank_account WHERE id IN ('X', 'Y') ORDER BY id; }
4141
step s3c { COMMIT; }

‎src/test/modules/libpq_pipeline/libpq_pipeline.c

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1760,9 +1760,9 @@ main(int argc, char **argv)
17601760
res = PQexec(conn, "SET lc_messages TO \"C\"");
17611761
if (PQresultStatus(res) != PGRES_COMMAND_OK)
17621762
pg_fatal("failed to set lc_messages: %s", PQerrorMessage(conn));
1763-
res = PQexec(conn, "SET force_parallel_mode = off");
1763+
res = PQexec(conn, "SET debug_parallel_query = off");
17641764
if (PQresultStatus(res) != PGRES_COMMAND_OK)
1765-
pg_fatal("failed to set force_parallel_mode: %s", PQerrorMessage(conn));
1765+
pg_fatal("failed to set debug_parallel_query: %s", PQerrorMessage(conn));
17661766

17671767
/* Set the trace file, if requested */
17681768
if (tracefile != NULL)

‎src/test/modules/test_oat_hooks/test_oat_hooks.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -233,7 +233,7 @@ emit_audit_message(const char *type, const char *hook, char *action, char *objNa
233233
/*
234234
* Ensure that audit messages are not duplicated by only emitting them
235235
* from a leader process, not a worker process. This makes the test
236-
* results deterministic even if run with force_parallel_mode = regress.
236+
* results deterministic even if run with debug_parallel_query = regress.
237237
*/
238238
if (REGRESS_audit && !IsParallelWorker())
239239
{

‎src/test/regress/expected/multirangetypes.out

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3257,7 +3257,7 @@ select array[1,3] <@ arraymultirange(arrayrange(array[1,2], array[2,1]));
32573257
--
32583258
create type two_ints as (a int, b int);
32593259
create type two_ints_range as range (subtype = two_ints);
3260-
-- with force_parallel_mode on, this exercises tqueue.c's range remapping
3260+
-- with debug_parallel_query on, this exercises tqueue.c's range remapping
32613261
select *, row_to_json(upper(t)) as u from
32623262
(values (two_ints_multirange(two_ints_range(row(1,2), row(3,4)))),
32633263
(two_ints_multirange(two_ints_range(row(5,6), row(7,8))))) v(t);

‎src/test/regress/expected/rangetypes.out

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1743,7 +1743,7 @@ select array[1,3] <@ arrayrange(array[1,2], array[2,1]);
17431743
--
17441744
create type two_ints as (a int, b int);
17451745
create type two_ints_range as range (subtype = two_ints);
1746-
-- with force_parallel_mode on, this exercises tqueue.c's range remapping
1746+
-- with debug_parallel_query on, this exercises tqueue.c's range remapping
17471747
select *, row_to_json(upper(t)) as u from
17481748
(values (two_ints_range(row(1,2), row(3,4))),
17491749
(two_ints_range(row(5,6), row(7,8)))) v(t);

0 commit comments

Comments
 (0)