Parameter · Connections and Authentication / Connection Settings
superuser_reserved_connections
Sets the number of connection slots reserved for superusers.
- Default:
3 - Type: integer
- Range: 0 … 262143
- Applies: Restart required
In plain words
A small number of connection slots that ordinary users can never take. When an application has used up all other slots, a superuser can still log in to investigate and, for example, terminate runaway sessions.
The default of 3 is fine for most systems; keep it at least 1.
For DBAs and operators
The reserve is counted, not pinned: when the number of free slots is ≤ this value, only superusers are admitted and everyone else gets FATAL: remaining connection slots are reserved for roles with the SUPERUSER attribute. The slots are part of max_connections, so the application really gets max_connections − superuser_reserved_connections − reserved_connections. The value must be less than max_connections − reserved_connections.
Replication connections (WAL senders) use their own slots (max_wal_senders) and are not affected. Since PostgreSQL 16 there is a second, earlier reserve, reserved_connections, for non-superuser roles granted pg_use_reserved_connections (monitoring agents, ops tooling), so you no longer need to give those tools superuser just to be able to connect during an incident.
Pitfall: if the application itself connects as a superuser (common in small setups), the reserve protects nothing: the app eats the reserved slots too and the next login gets FATAL: sorry, too many clients already. Use a non-superuser application role.
How to change it
Change in postgresql.conf or ALTER SYSTEM, then restart the server.
See it in context
Client backend Roles and privileges Process model Postmaster