Query timeout diagnosis

A specific playbook under the performance skill: its measured before and after still applies.

Use when a Node/pg app reports query timeouts (Query read timeout, bounded-operation deadline errors) but DB metrics look healthy.

Decision tree

1. Get the real error source. Error: Query read timeout at pg/lib/client.js is the client-side query_timeout (wall clock). canceling statement due to statement timeout is server-side. Drizzle's DrizzleQueryError ("Failed query: ") hides the pg cause; find the run trace or reproduce to get it.
2. Check DB health during the failure window (CPU, active connections, error logs). If CPU is low, connections are far under max, and there are no DB errors, the database is innocent: do NOT raise DB resources.
3. Ask which statement timed out. BEGIN, COMMIT or a single-row indexed UPDATE "taking 30s" is physically impossible server-side, so the time was spent client-side.
4. Client-side causes, in order of likelihood:
   • Event-loop stall. pg's query_timeout counts wall time until the event loop reads the socket. CPU-heavy work (JSON parse or stringify of large payloads, tokenization) on a small worker (Trigger.dev micro is 0.25 vCPU) stalls the loop past the timer even though Postgres answered in milliseconds. Check the worker machine preset and the compute duration.
   • Per-row query loops over WAN. N sequential round trips (about 50-100ms each) inside one bounded transaction: 400+ rows is roughly 30s or more. Grep the failing helper for for (...) await query(...).
   • Pool acquisition starvation. An unbounded Promise.all of N queries through a small pool (max: 10) with a short connectionTimeoutMillis. Concurrent workloads multiply it.

Fixes (root cause, not band-aid)