# workerd error: hyperdrive query timeout

## TL;DR

The query through Hyperdrive exceeded the timeout: slow query, overloaded database, or too-tight timeout. Optimize the query first (EXPLAIN it), then check the database load, then tune the timeout. Hyperdrive adds pooling, not patience.

```text
workerd error: hyperdrive query timeout
```

## Steps

1. EXPLAIN the query against the database directly.
   Expected: The slow plan is visible.

2. Optimize: missing index, bad join, or full scan.
   Expected: The query gets fast.

3. Check database load and connection saturation during the timeouts.
   Expected: The backend's health is known.

4. Tune the Hyperdrive/query timeout only after the query is reasonable.
   Expected: The timeout fits reality.

5. Monitor query latency percentiles through Hyperdrive specifically.
   Expected: The path is observed.

## When to use

- queries through Hyperdrive time out
- the query is slow
- the database is under load

## When not to use

- the query is fast directly (check Hyperdrive config)
- the timeout is on connect, not query (different problem)
- not using Hyperdrive (then it is a plain query timeout)

## Tool compatibility

- workerd
- Hyperdrive

## Variant phrasings

- "hyperdrive query timeout"
- "hyperdrive slow query"
- "database timeout hyperdrive"

## Why it happens

Hyperdrive pools connections to the database, but it cannot make a slow query fast or raise a database's capacity. Timeouts through Hyperdrive are usually slow queries or a saturated database wearing a Hyperdrive label. The fix is the same as any slow query, measured at the database.

## Edge cases

- the timeout has multiple layers (worker, hyperdrive, database); know which fired
- pool exhaustion looks like query timeouts; check pool metrics
- prepared statements behave differently through poolers; test the real path

## Provenance

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