workerd error: hyperdrive query timeout

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.

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