reserved_connections

Definition PG 18 manual

Determines the number of connection “slots” that are reserved for connections by roles with privileges of the pg_use_reserved_connections role. Whenever the number of free connection slots is greater than superuser_reserved_connections but less than or equal to the sum of superuser_reserved_connections and reserved_connections, new connections will be accepted only for superusers and roles with privileges of pg_use_reserved_connections. If superuser_reserved_connections or fewer connection slots are available, new connections will be accepted only for superusers.

The default value is zero connections. The value must be less than max_connections minus superuser_reserved_connections. This parameter can only be set at server start.

How it works

reserved_connections sets the number of connection slots reserved for roles with privileges of pg_use_reserved_connections. These slots become available only to roles granted pg_use_reserved_connections and sit above ordinary capacity but below superuser-only reserves.

reserved_connections is a POSTMASTER-context setting: PostgreSQL reads it during server startup, and a configuration reload or session SET cannot activate a new value.

reserved_connections and superuser_reserved_connections carve privileged tiers from max_connections; poolers, monitoring, replication, maintenance, and failover must all fit the same total backend budget.

Operational considerations

Expecting a reload or SET to activate reserved_connections, although it requires a controlled server restart.

Counting reserved slots outside max_connections even though every tier consumes the same total ceiling.

Reserving too little for incident response or so much that ordinary application capacity collapses at saturation.

Sizing ordinary, reserved, and superuser-reserved slots without ensuring their sum fits max_connections.

Workload guidance

OLAP: Reserve enough slots for control, monitoring, and cancellation around heavy analytical sessions, but do not let reserves consume an excessive share of a deliberately small backend pool.

OLTP: Size reserved_connections inside max_connections from the number of independent emergency actors, pooler behavior, and failover operations. Test that ordinary saturation still leaves usable administrative access.

SMALL: Keep reserved_connections modest relative to max_connections while preserving at least one tested emergency path; reserved slots are capacity unavailable to ordinary clients at saturation.