# 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

```text
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