force_parallel_mode

Definition PG 15 manual

Allows the use of parallel queries for testing purposes even in cases where no performance benefit is expected. The allowed values of force_parallel_mode are off (use parallel mode only when it is expected to improve performance), on (force parallel query for all queries for which it is thought to be safe), and regress (like on, but with additional behavior changes as explained below).

More specifically, setting this value to on will add a Gather node to the top of any query plan for which this appears to be safe, so that the query runs inside of a parallel worker. Even when a parallel worker is not available or cannot be used, operations such as starting a subtransaction that would be prohibited in a parallel query context will be prohibited unless the planner believes that this will cause the query to fail. If failures or unexpected results occur when this option is set, some functions used by the query may need to be marked PARALLEL UNSAFE (or, possibly, PARALLEL RESTRICTED).

Setting this value to regress has all of the same effects as setting it to on plus some additional effects that are intended to facilitate automated regression testing. Normally, messages from a parallel worker include a context line indicating that, but a setting of regress suppresses this line so that the output is the same as in non-parallel execution. Also, the Gather nodes added to plans by this setting are hidden in EXPLAIN output so that the output matches what would be obtained if this setting were turned off.

How it works

Through PG15, force_parallel_mode forced otherwise safe queries to run under a Gather so parallel-mode behavior could be tested even without an expected speedup. regress suppressed output differences for regression suites.

It did not make unsafe queries safe and could impose parallel-context restrictions even when no worker ran. The top-level Gather was diagnostic overhead rather than a plan hint.

PostgreSQL 16 removed this GUC and introduced debug_parallel_query for the testing role. Upgrade configurations must delete the old name and should not automatically enable the replacement in production. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Operational considerations

Leaving force_parallel_mode enabled after the bounded diagnostic or recovery task.

Running the experiment on the only copy of production data.

Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.

Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Workload guidance

OLAP: Analytical workload does not justify retaining the removed force_parallel_mode. Diagnose current versions with supported EXPLAIN, logs, or the documented replacement.

OLTP: Do not configure force_parallel_mode on current PostgreSQL. Remove it during upgrades; use any named successor only for the same controlled developer test, not as a production default.

SMALL: Delete force_parallel_mode from modern configurations. Unknown-parameter startup failure and diagnostic overhead outweigh any historical use.