Parameter · Resource Usage / Worker Processes
max_worker_processes
Maximum number of concurrent worker processes.
- Default:
8 - Type: integer
- Range: 0 … 262143
- Applies: Restart required
In plain words
A fixed pool of slots for background worker processes, reserved at server start. Parallel query workers, logical replication workers and extension workers (pg_cron, TimescaleDB, …) all take their slots from this pool. When it is full, new workers simply do not start.
For DBAs and operators
Not counted here: autovacuum workers, I/O workers, walsenders and other auxiliary processes. The logical replication launcher uses one slot (unless max_logical_replication_workers = 0). Rules of thumb: ≥ max_parallel_workers + logical replication workers (apply + table sync + parallel apply) + extension workers + a few spare; often set to the number of CPU cores or more. Raising it needs a restart, so set it generously. On a standby it must be ≥ the primary's value; otherwise recovery pauses with WARNING: hot standby is not possible because of insufficient parameter settings.
Symptoms of exhaustion: Workers Launched lower than Workers Planned in EXPLAIN ANALYZE; logical replication tablesync not starting with WARNING: out of background worker slots plus HINT: You might need to increase "max_worker_processes".; extensions failing to register their worker.
SELECT backend_type, count(*) FROM pg_stat_activity
GROUP BY 1 ORDER BY 2 DESC;
-- PG18: per database
SELECT datname, parallel_workers_to_launch, parallel_workers_launched
FROM pg_stat_database;How to change it
Change in postgresql.conf or ALTER SYSTEM, then restart the server.
See it in context
Parallel and background workers Process model Logical replication workers Postmaster Parallel query
Related parameters
max_parallel_workers max_parallel_workers_per_gather max_parallel_maintenance_workers max_logical_replication_workers