Parameter · Resource Usage / Worker Processes
max_parallel_workers
Sets the maximum number of parallel workers that can be active at one time.
- Default:
8 - Type: integer
- Range: 0 … 1024
- Applies: Session (any user)
In plain words
A cap on the total number of parallel workers running at the same time, across all sessions. It must fit inside max_worker_processes: setting it higher has no effect. When the cap is reached, queries still run, just with fewer (or no) helpers.
For DBAs and operators
Parallel workers for queries (Gather / Gather Merge) and for parallel CREATE INDEX / VACUUM come from the max_worker_processes pool and are limited by this value. Keep some headroom below max_worker_processes for logical replication and extensions. A common setting is the number of CPU cores dedicated to query work.
Shortage is silent: the plan runs with fewer workers. Compare Workers Planned vs Workers Launched in EXPLAIN (ANALYZE), or PostgreSQL 18's parallel_workers_to_launch vs parallel_workers_launched in pg_stat_database and pg_stat_statements. Because each worker has its own work_mem, more parallel workers also means more memory: a 4-worker query can use about 5× the memory of a serial one.
How to change it
Any user can change it for their session with SET.
See it in context
Related parameters
max_worker_processes max_parallel_workers_per_gather max_parallel_maintenance_workers work_mem