max_worker_processes

Definition PG 18 manual

Sets the maximum number of background processes that the cluster can support. This parameter can only be set at server start. The default is 8.

When running a standby server, you must set this parameter to the same or higher value than on the primary server. Otherwise, queries will not be allowed in the standby server.

When changing this value, consider also adjusting max_parallel_workers, max_parallel_maintenance_workers, and max_parallel_workers_per_gather.

How it works

max_worker_processes is the startup-time ceiling for concurrent background worker processes, including parallel workers and extension-managed workers. It is broader than max_parallel_workers.

The setting allocates shared control capacity but does not launch workers. Replication, extensions, logical apply, and parallel execution can all depend on slots beneath this ceiling.

A standby should normally configure the same or a higher value than its primary because worker requirements can be replayed or promoted. Increasing it without a CPU and memory budget only creates possible concurrency. Its postmaster context fixes the value at server start; changing it requires a restart.

Operational considerations

Treating max_worker_processes 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_worker_processes, 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_worker_processes 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_worker_processes conservative on a small host. More possible workers can reduce throughput through context switching and memory pressure even when a single query becomes faster.