parallel_leader_participation

Definition PG 18 manual

Allows the leader process to execute the query plan under Gather and Gather Merge nodes instead of waiting for worker processes. The default is on. Setting this value to off reduces the likelihood that workers will become blocked because the leader is not reading tuples fast enough, but requires the leader process to wait for worker processes to start up before the first tuples can be produced. The degree to which the leader can help or hinder performance depends on the plan type, number of workers and query duration.

How it works

parallel_leader_participation controls whether the process above Gather or Gather Merge also runs the parallel subplan while coordinating workers. With it off, the leader focuses on reading worker output.

Leader participation can add useful CPU when result production is expensive, but a leader busy executing the subplan may be slower to consume a large worker result stream.

The value is a planning/execution policy for eligible parallel plans, not an extra worker slot. Its effect depends on tuple volume, Gather versus Gather Merge, worker availability, and where the bottleneck lies. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Operational considerations

Treating the boolean as a degree-of-parallelism or worker-count setting.

Speaking of a 'larger' value when the only choices are on and off.

Disabling participation without measuring the extra wait before workers produce the first tuples.

Enabling participation without checking whether the leader then drains a large worker result stream too slowly.

Workload guidance

OLAP: For CPU-heavy subplans, leader participation often adds useful execution capacity; for very large result streams, disabling it can let the leader drain workers sooner. Compare both boolean states on the same plan and concurrency level.

OLTP: Keep the default on unless a representative Gather plan shows that the leader is too busy executing the subplan to consume worker tuples promptly. Test off only at session scope and compare first-row latency, total latency, and worker blocking.

SMALL: This boolean does not add or remove worker slots. Leave it on unless measurements show a result-consumption bottleneck; size worker counts separately with max_parallel_workers_per_gather and the shared pools.