max_parallel_workers

Definition PG 18 manual

Sets the maximum number of workers that the cluster can support for parallel operations. The default value is 8. When increasing or decreasing this value, consider also adjusting max_parallel_maintenance_workers and max_parallel_workers_per_gather. Also, note that a setting for this value which is higher than max_worker_processes will have no effect, since parallel workers are taken from the pool of worker processes established by that setting.

How it works

max_parallel_workers caps the cluster-wide number of workers simultaneously active for parallel query and maintenance. It is a pool ceiling beneath max_worker_processes.

Per-operation parameters request workers from this pool, but no slots are reserved. A plan can start with fewer workers than planned, and concurrent jobs can starve each other.

Increasing it expands potential CPU, memory, and I/O concurrency; it does not itself make plans parallel. Planner thresholds, safety checks, and max_parallel_workers_per_gather still govern query choices. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Operational considerations

Treating max_parallel_workers as reserved capacity rather than an upper bound shared with other work.

Ignoring that parallel plans multiply CPU, I/O, and work_mem-limited nodes.

Benchmarking one query without concurrent worker contention.

Assuming planned workers will always be launched at execution time.

Workload guidance

OLAP: Analytical work can use a larger max_parallel_workers, but multiply per-node memory and I/O by concurrent statements. Benchmark throughput under realistic worker contention rather than one isolated query.

OLTP: Set max_parallel_workers from a concurrency budget, not core count alone. Protect latency-sensitive OLTP from report and maintenance bursts, and verify actual Workers Planned versus Workers Launched.

SMALL: Keep max_parallel_workers conservative on a small host. More possible workers can reduce throughput through context switching and memory pressure even when a single query becomes faster.