Parameter · Developer Options
debug_parallel_query
Forces the planner's use parallel query nodes. This can be useful for testing the parallel query infrastructure by forcing the planner to generate plans that contain nodes that perform tuple communication between workers and the main process.
- Default:
off - Type: enum
- Values: off · on · regress
- Applies: Session (any user)
In plain words
Makes the planner put a "Gather" node on top of any plan that could run in a parallel worker, so the work happens in a worker even when that is slower. It exists to test that functions and extensions are correctly labelled parallel safe.
Before PostgreSQL 16 it was called force_parallel_mode.
For DBAs and operators
Captured on 18.6 on a small table:
SET debug_parallel_query = on;
EXPLAIN (COSTS OFF) SELECT * FROM pt WHERE a = 3;
Gather
Workers Planned: 1
Single Copy: true
-> Seq Scan on pt
Filter: (a = 3)Single Copy means one worker runs the subplan and the leader just relays tuples. With regress the plan is the same but EXPLAIN hides the Gather (and worker CONTEXT lines are suppressed), so regression test output matches a serial run. Plans that are not parallel safe (temporary tables, functions marked PARALLEL UNSAFE, writes) are unchanged.
Use it in a test environment to find user functions that are wrongly labelled PARALLEL SAFE: they then fail with errors like cannot execute … during a parallel operation. Fix by labelling them PARALLEL RESTRICTED or UNSAFE. Never use it to "make queries parallel" in production: it ignores costs, and real parallelism is controlled by max_parallel_workers_per_gather and the parallel cost settings.
Developer option: meant for debugging and testing PostgreSQL itself. Leave it at the default on production servers unless a specific diagnosis calls for it.
How to change it
Any user can change it for their session with SET.
See it in context
Related parameters
max_parallel_workers_per_gather parallel_setup_cost parallel_tuple_cost min_parallel_table_scan_size