max_connections

The startup-time ceiling on concurrent PostgreSQL client connections and a sizing input for several shared resources.

Note

Fact — official short description: “Sets the maximum number of concurrent connections.”

Identity

Type , Valueinteger: Upstream pg_settings type
Context , Valuepostmaster: Requires a server restart
Unit , Value—: Raw unit
Range , Value1 – 262143: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueConnections and Authentication / Connection Settings: Upstream classification
Latest boot value , Value100: 100

Lifecycle

Fact	Value
First observed	PG9.0 (research boundary)
Present in	PG9.0–19 Beta 3
Removed in	No
Introduction commit	Not asserted: predates the PG9.0 research boundary
Commit date	—
Discussion	—

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG9.0–19 Beta 3	`100`	—	100

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.

Tuning advice

Tip

Advice. These are workload-specific starting points and must be validated with measurements.

Workload	Guidance
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.
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.
Small nodes	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.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG19 Beta 3; this does not assert current Pigsty support for that historical or beta release.

Template	Effective value	Versus upstream boot	Source expression
OLTP	`500`	different	`{{ pg_max_connections }}`
OLAP	`500`	different	`{{ pg_max_connections }}`
CRIT	`500`	different	`{{ pg_max_connections }}`
TINY	`250`	different	`{{ pg_max_connections }}`

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 500 (dcs); OLAP: PG9.0–19 Beta 3 = 500 (dcs); CRIT: PG9.0–19 Beta 3 = 500 (dcs); TINY: PG9.0–19 Beta 3 = 250 (dcs). Advice, pending human review — Editorial inference: the templates expose a generous compatibility ceiling behind pooling while reducing it for the small-node profile, but actual active-backend and memory limits still need workload-specific review.

Common pitfalls

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.

reserved_connections · superuser_reserved_connections · work_mem · max_worker_processes · max_prepared_transactions · max_wal_senders