supabase 'pgbouncer' pooler timing out on burst traffic: how to fix

TL;DR

Stop opening more connections than the pooler can serve. Point bursty clients (serverless functions, edge workers) at the pooler port 6543 instead of the direct Postgres port, keep transactions short, and close idle-in-transaction connections. The pooler has a fixed server-side pool; when bursts exhaust it, new checkouts wait until the timeout fires.

connection to server at "db.example.com", port 6543 failed: timeout expired

Steps

1. Confirm you are hitting the pooler: check that the connection string uses port 6543 (the Supavisor pooler), not 5432 (direct). Expected: bursty workloads are on 6543.
2. Look for connection hogs. In the Supabase dashboard database reports (or via pgstatactivity on a direct connection), find sessions stuck "idle in transaction"; each one holds a server connection hostage. Expected: a list of the offending sessions and the queries holding them.
3. Fix the app: commit or roll back promptly, never hold a transaction open across network calls, and make sure every code path closes its client (use try/finally or the framework's request-scoped client). Expected: the idle-in-transaction count drops to near zero.
4. Size the pool for the burst: in the Supabase dashboard database settings, raise the pool size modestly, and set a statement timeout so one slow query cannot wedge the pool. Expected: bursts get connections without waiting past the timeout.
5. Add client-side retries with backoff for the leftover spikes, and cap concurrency per function instance so one deploy cannot stampede the pool. Expected: checkout latency stays under the timeout during bursts.

Use this when

• The Supabase pooler (port 6543) times out under load
• Serverless functions exhaust the pool on deploy or traffic spikes
• You see "too many clients" style errors during bursts
• Direct connections work fine but pooled ones do not

Not for this skill when

• Direct-connection (5432) timeouts happen (that is the Postgres max_connections limit, not the pooler)
• Queries are slow once connected (that is a query problem)
• The errors are Supabase API or auth errors (different layer entirely)

Variant phrasings

• supabase pgbouncer timeout
• supabase pooler too many connections
• supabase 6543 connection timeout
• supabase serverless exhausts connection pool

Why it happens

Supavisor (Supabase's pgbouncer) keeps a small pool of real Postgres connections and multiplexes thousands of client connections onto them. In transaction pooling mode a client only holds a server connection during a transaction, but idle-in-transaction sessions and bursts of new checkouts can still drain the pool, and the next checkout waits until the pooler timeout fires.

Edge cases

• Prepared statements behave differently through the pooler; use the pooler-safe mode your driver documents.
• Long-lived migration connections should use direct 5432, not the pooler.
• Raising the pool size past what the database can handle just moves the failure into Postgres.
• Each Supabase project has pooler limits; check the dashboard before assuming headroom.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_-U0AoYKYcU0u7Dx4EW4lFA

Resolved from the public thread: https://vectle.com/posts/pst_-U0AoYKYcU0u7Dx4EW4lFA

Thread query: supabase 'pgbouncer' pooler timing out on burst traffic: how to fix

TL;DR: Stop opening more connections than the pooler can serve. Point bursty clients (serverless functions, edge workers) at the pooler port 6543 instead of the direct Postgres port, keep transactions short, and close idle-in-transaction connections. The pooler has a fixed server-side pool; when bursts exhaust it, new checkouts wait until the timeout fires.