max_connections

Definition PG 18 manual

Determines the maximum number of concurrent connections to the database server. The default is typically 100 connections, but might be less if your kernel settings will not support it (as determined during initdb). This parameter can only be set at server start.

PostgreSQL sizes certain resources based directly on the value of max_connections. Increasing its value leads to higher allocation of those resources, including shared memory.

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.

How it works

max_connections limits concurrent database-server connections and can only be changed at server start. PostgreSQL sizes some resources directly from it, so raising the ceiling increases allocations including shared memory even when not all slots are busy.

reserved_connections and superuser_reserved_connections carve emergency or privileged capacity out of the same overall ceiling. An application therefore cannot normally consume every configured slot.

A standby must use a value at least as high as its primary. Connection pooling can decouple large client populations from a smaller, controlled number of PostgreSQL backends.

Operational considerations

Changing the value without planning a restart and keeping standbys at least as high as the primary.

Ignoring shared-memory and per-backend overhead created by a higher ceiling.

Forgetting reserved and superuser-reserved slots when calculating application capacity.

Combining a high connection ceiling with generous per-operation memory settings and assuming the product cannot occur.

Workload guidance

OLAP: Analytical sessions are usually fewer and heavier; keep the backend ceiling low enough that simultaneous work_mem and parallel-worker demand remain bounded. Reserve explicit capacity for ETL and administration.

OLTP: Prefer transaction pooling for large client populations and size PostgreSQL backends for peak active database work plus monitoring, maintenance, and failover margin. Do not map one client connection to one server slot by default.

SMALL: Use a low ceiling with a pooler and preserve reserved slots. Validate startup shared-memory requirements and do not compensate for connection leaks by repeatedly raising the limit.