superuser_reserved_connections

Definition PG 18 manual

Determines the number of connection “slots” that are reserved for connections by PostgreSQL superusers. At most max_connections connections can ever be active simultaneously. Whenever the number of active concurrent connections is at least max_connections minus superuser_reserved_connections, new connections will be accepted only for superusers. The connection slots reserved by this parameter are intended as final reserve for emergency use after the slots reserved by reserved_connections have been exhausted.

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

How it works

superuser_reserved_connections sets the number of connection slots reserved for superusers. These slots are usable only after ordinary and reserved_connections capacity is exhausted, preserving an emergency path for superusers.

superuser_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 superuser_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.

Changing superuser_reserved_connections globally without a rollback plan and a client or operational compatibility test.

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 superuser_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 superuser_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.