Now-Next

SaaS architecture

remaining connection slots are reserved in PostgreSQL

Why PostgreSQL says 'remaining connection slots are reserved' or 'too many connections for role', measured on 15–17 (role limits on 17), and how to free slots.

Chris van Eijk, Now-Next · · 8 min read

Now-Next builds SaaS products and takes over existing ones. What we build

FATAL: remaining connection slots are reserved for … means the server is almost full: every connection slot that an ordinary role may use is taken, and the few that are left are kept for superusers (and, since PostgreSQL 16, for roles you choose). It is SQLSTATE 53300. The fix is not the reserve but whatever is holding the ordinary slots: too many application connections, connections nobody closes, or sessions left idle in a transaction.

We filled servers running PostgreSQL 15.19, 16.15 and 17.11, each with max_connections = 10 and the default superuser_reserved_connections = 3, one connection at a time, and wrote down which connection was refused with which message.

Why does PostgreSQL say the remaining connection slots are reserved?

Because max_connections counts every client connection, and superuser_reserved_connections (3 by default) of those are kept back. An ordinary role can use the rest: with 10 slots, our application role opened 7 connections, and the 8th was refused. A superuser then opened 3 more, and the 4th superuser connection got a different message: sorry, too many clients already. Both are SQLSTATE 53300.

The wording depends on the version. The same 8th connection got:

VersionMessage for an ordinary role when only reserved slots are left
15.19remaining connection slots are reserved for non-replication superuser connections
16.15, 17.11remaining connection slots are reserved for roles with the SUPERUSER attribute
16.15, 17.11 with reserved_connections setremaining connection slots are reserved for roles with privileges of the "pg_use_reserved_connections" role
any, when every slot is takensorry, too many clients already

The background processes we saw did not count against max_connections: at the full moment, pg_stat_activity showed 15 rows — the 10 client connections plus the autovacuum launcher, background writer, checkpointer, logical replication launcher and WAL writer.

Who gets the last slots: reserved_connections in PostgreSQL 16 and 17

PostgreSQL 16 added a second reserve: reserved_connections slots for roles with privileges of the predefined role pg_use_reserved_connections. It is useful for roles you need when the server is full — monitoring, an operator, a migration — without making them superusers. It does not exist on 15: SHOW reserved_connections there returned unrecognized configuration parameter "reserved_connections".

Filling a server with max_connections = 10, superuser_reserved_connections = 3 and reserved_connections = 2
  1. Application role, connections 1–5All accepted.
    5 free slots left: the two reserves
  2. Application role, connection 6Refused: reserved for roles with privileges of the "pg_use_reserved_connections" role.
    Still 5 free
  3. Operator role (member of pg_use_reserved_connections), connections 1–2Accepted.
    3 free: the superuser reserve
  4. Operator role, connection 3Refused: reserved for roles with the SUPERUSER attribute.
    Still 3 free
  5. Superuser, connections 1–3Accepted.
    0 free
  6. Anyone, the next connectionRefused for the application role, the operator and the superuser alike: sorry, too many clients already.
    Full

Measured the same on PostgreSQL 16.15 and 17.11. On 15.19 there is no second reserve: the application role got 7 connections and the 8th the message for non-replication superusers.

The documentation describes the same order: the superuser_reserved_connections slots “are intended as final reserve for emergency use after the slots reserved by reserved_connections have been exhausted”. Both settings only change at a server restart.

Why does PostgreSQL say too many connections for role?

Because the role, or the database, has its own connection limit, and that limit is full while the server itself still has room. FATAL: too many connections for role "app" and FATAL: too many connections for database "d2" are also SQLSTATE 53300, but max_connections has nothing to do with them: on PostgreSQL 17.11 with max_connections = 100 and fewer than ten connections open, they were refused all the same.

ALTER ROLE app CONNECTION LIMIT 2;
ALTER DATABASE d2 CONNECTION LIMIT 1;
SELECT rolname, rolconnlimit FROM pg_roles WHERE rolname = 'app';      -- app | 2
SELECT datname, datconnlimit FROM pg_database WHERE datname = 'd2';    -- d2  | 1
-- -1 means no limit

What we measured on 17.11, from psql 16.15 on the host:

What we didWhat happened
app (limit 2) holds two connections to d1, opens a third to d1too many connections for role "app"
the same third connection, but to another database d2too many connections for role "app" — the role limit counts over all databases
app2 connects to d2 (limit 1) while app holds the one slot theretoo many connections for database "d2"
both limits full at oncethe role message; in the server log the role check (InitializeSessionUserId) ran before the database check (CheckMyDatabase)
a superuser with CONNECTION LIMIT 1, and the superuser postgres into the full d2both connected: neither limit is enforced against a superuser
the superuser postgres holds the one slot of d2, app2 connects to d2too many connections for database "d2": a superuser is not stopped by the limit, but its connection does count towards it
CONNECTION LIMIT 0too many connections for role "app", the same message as a full limit, not a login error
limit lowered from 2 to 1 while two connections were openboth stayed open; the next new connection was refused
a session idle in a transactioncounted: with limit 1 it kept the next connection out
one session running a parallel query with 2 workers, limit 2a second connection was accepted while pg_stat_activity showed 3 backends for the role (1 client backend, 2 parallel workers); a third was refused

psql shows only the sentence, even with \set VERBOSITY verbose, but the code travels with it: the server’s error response carries 53300, so a driver that exposes the SQLSTATE reports it. In the server log, log_error_verbosity = verbose adds it as well: FATAL: 53300: too many connections for role "app". So the questions are the same as for a full server, only narrower: who holds the connections of this role (select count(*) from pg_stat_activity where usename = 'app' and backend_type = 'client backend'; parallel workers show up under the same name but do not count), and is the limit still right. For a database limit, count by datname and include superusers.

The documentation says the same about background workers, which is what the parallel query showed, and that “the limit is never enforced for superusers”. It adds two things we did not reproduce: prepared transactions do not count either, and the limit “is only enforced approximately; if two new sessions start at about the same time when just one connection ‘slot’ remains for the role, it is possible that both will fail.”

How do you free connection slots?

Look at who holds them first. As a superuser, or a role with pg_use_reserved_connections, you can still get in:

select usename, application_name, state, count(*)
from pg_stat_activity
where backend_type = 'client backend'
group by 1, 2, 3
order by 4 desc;

What we saw in the measurements, and what follows from it:

  • Killing the client does not free the slot straight away. We killed seven psql clients whose server sessions were inside a pg_sleep(600). Two seconds later pg_stat_activity still showed all seven as active; after killing a superuser client on a full server, a new connection one second later was still refused. The server session keeps running until its query ends; only then, when it tries to answer, does it notice the client is gone, so a client process that dies mid-query keeps its slot until then. With client_connection_check_interval = '1s' the session was gone within 3 seconds, with FATAL: connection to client lost (SQLSTATE 08006); the default is 0, off. pg_terminate_backend(pid) ends a session from the server side: after terminating one, a new application connection was accepted immediately.
  • Sessions idle in a transaction keep their slot for as long as nobody ends them. After ALTER ROLE app SET idle_in_transaction_session_timeout = '5s', new sessions of that role that opened a transaction and then did nothing were ended after 5 seconds, and the client’s next statement got FATAL: terminating connection due to idle-in-transaction timeout (SQLSTATE 25P03). Sessions that were already open before the ALTER ROLE were not affected: one that stayed idle in its transaction for 30 seconds still ran its next query (checked on 15 and 17). What else such a session holds — row locks, ALTER TABLE, vacuum — is in idle in transaction in PostgreSQL.
  • Raising max_connections moves the limit, not the cause. It needs a restart, and every connection is a separate server process. For a SaaS application with many app servers or workers, the usual answer is a pooler in front of the database, so that hundreds of client connections share a few dozen server sessions.

A pooler has its own trap for multi-tenant applications: a tenant set with a plain SET stays on the server session and reaches the next client. What leaked and what did not, measured with PgBouncer in transaction mode, is in PgBouncer and row-level security.

Can a migration or a deploy still connect when the ordinary slots are full?

Only if its role can use a reserve. On 15 that means a superuser. On 16 and 17, GRANT pg_use_reserved_connections TO migrator; plus reserved_connections above zero let our operator role in while the application role was refused. Keep the number small: those slots are taken from what ordinary roles can use — with reserved_connections = 2 our application role got 5 connections instead of 7.

What we did not measure

Managed services, which may reserve slots of their own for their administration roles. max_connections at production sizes and the memory per connection. Connection limits per role and per database on 15 and 16 (we measured them on 17 only), prepared transactions, and two sessions racing for the last slot of a role.

Sources: PostgreSQL 17 documentation on connection settings (max_connections, reserved_connections, superuser_reserved_connections) and predefined roles, and the PostgreSQL 16 release notes, read on 16 October 2026; CREATE ROLE and CREATE DATABASE (CONNECTION LIMIT), read on 27 October 2026. All measurements are our own, on PostgreSQL 15.19, 16.15 and 17.11 in containers, on 16 October 2026; the per-role and per-database limits on 17.11 on 27 October 2026.

Let's talk

What are we building?

One conversation is enough to know whether we fit. Tell us what you have in mind — we will tell you how fast it can happen, and whether we are the right people for it.

Start the conversation