workerd: hyperdrive connection failed, pool exhausted

Fix hyperdrive connection failed, pool exhausted

TL;DR

Pool exhaustion means your origin database allows fewer concurrent connections than your Workers open through Hyperdrive. Raise the database max_connections, keep the Hyperdrive pool max below it with headroom, reuse one database client per request instead of opening many, and shorten idle timeouts so parked connections close faster.

Verbatim error

workerd: hyperdrive connection failed, pool exhausted

Steps

1. Check your database's max_connections setting. Expected: you know the hard ceiling.
2. In the Hyperdrive configuration, set the pool max below the database limit, leaving headroom for non-worker clients (dashboards, migrations). Expected: Hyperdrive max is comfortably under the DB max.
3. In worker code, create one database client per request and reuse it for every query in that request; never open a client per query. Expected: at most one connection held per concurrent request.
4. Reduce the idle timeout so idle pooled connections close quickly. Expected: fewer lingering connections during quiet periods.
5. Load-test and watch the database's active connection count. Expected: it stays under the limit with no "pool exhausted" errors.

Use this when

• "hyperdrive connection failed, pool exhausted" appears in logs
• Database errors spike with traffic, not with particular queries
• Adding more workers or concurrency made the errors worse

Not for this skill when

• The error is authentication or wrong host (connection never establishes)
• No Hyperdrive config exists at all (set up the binding first)
• Queries time out individually while the pool is healthy (slow-query problem)

Variant phrasings

• hyperdrive too many connections
• postgres pool exhausted cloudflare
• hyperdrive max_connections
• too many clients already database workers

Why it happens

Hyperdrive multiplexes worker connections into a pool against your origin database. Each concurrent worker request can hold a connection, so traffic spikes multiply open connections until the origin database refuses more and the pool reports exhausted. It is a capacity mismatch, not a broken query.

Edge cases

• Serverless databases have low default connection limits; check the provider's cap, not just your config.
• Prepared statements hold connections longer than simple queries.
• A connection leak (a client opened in a loop and never closed) exhausts any pool size; fix the leak before resizing the pool.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_YMUJT0hhEYvplmzw59V9vw