“Max client connections reached”? Your functions are holding the seats.

The database isn’t busy. The waiting room is full.

Every Supabase project caps concurrent connections according to its compute size, with Supavisor pooling clients in front of Postgres. Serverless and edge functions break the assumption that pool was designed around: each invocation can open its own connection, and an instance that exits without closing leaves its client parked until the pooler refuses new ones.

This is why the symptom is so misleading. You go looking for a slow query and find none, because the problem was never load on the database — it is that nothing new can get to the database. A leak of idle connections and a genuine capacity problem produce the same error message and need opposite fixes, so the first job is telling them apart.

Six ways a connection pool quietly fills up

Paste this into your incident notes

Supabase connection-limit triage

[ ] Prove where the seats went, before changing anything:
    select application_name, state, count(*)
      from pg_stat_activity
     where datname = current_database()
     group by 1, 2
     order by 3 desc;
    -- mostly 'idle' from one application_name  -> a leak
    -- mostly 'active' across many names        -> genuine capacity

[ ] Find transactions left open:
    select pid, state, now() - state_change as held, query
      from pg_stat_activity
     where state = 'idle in transaction'
     order by held desc;

[ ] Move serverless/edge code to the transaction pooler (port 6543),
    not the session-mode direct connection (port 5432).
[ ] Add connection_limit=1 to each serverless client's URL.
[ ] Reuse a module-scoped client; do not construct one per request.
[ ] Release clients in a finally block so error paths cannot skip it.
[ ] Set idle_in_transaction_session_timeout so the DB reclaims stragglers.
[ ] Point migrations and admin queries at a different connection.
[ ] Re-check pg_stat_activity under load: idle count should stay flat.
[ ] Only then consider a larger compute size.

Watch a route that actually touches the database

An exhausted pool is invisible to a homepage check. Static pages and cached routes keep answering perfectly while every database-backed request fails, which is why this failure so often reaches customers first. Nightlamp runs an api_canary against an endpoint that really queries Postgres and asserts the response contains what it should, so an intermittent 5xx fails the check instead of passing as a suspiciously empty success.

Two more checks close the gap. An http_status monitor tracks the error rate and latency trend on the public surface, so you see the climb before the pool is completely full. And a heartbeat on each background worker catches jobs that die partway through because they could not get a connection — the failure mode that leaves half-written records behind and no error anywhere a human would look.