perf(db): add query timing, statement timeouts, and replica routing for usage reads

[jeanduplessis]

Summary

Addresses connection-pool saturation caused by slow microdollar_usage aggregation queries (10-22s, causing 17k-28k pool waiting spikes during peak hours).

This PR implements Phase 1 of the performance plan documented in plans/db-perf-improvements.md:

• Query instrumentation (Phase 1a): New timedUsageQuery() helper in src/lib/usage-query.ts wraps all hot usage queries in a transaction with structured JSON logging (route, label, scope, period, duration, row count) for before/after measurement.
• Statement timeouts (Phase 1b): SET LOCAL statement_timeout enforced per-query — 5s for interactive reads (dashboard, billing, autocomplete), 20s for admin reads (abuse stats). Runaway queries are cancelled instead of holding connections for 10-22s.
• Replica routing (Phase 1c): All read-only microdollar_usage aggregation queries moved from db (primary) to readDb (replica), except getCurrentPeriodUsageUsd which stays on primary because it drives the subscription-state response shown immediately after usage writes.

Affected endpoints: profile usage, user autocomplete metrics, Kilo Pass billing reads, org 30-day summary, org usage details (time series, daily breakdown, autocomplete), and admin abuse stats (hourly, daily, 1h/24h aggregates).

Verification

• pnpm typecheck — passes

Visual Changes

N/A

Reviewer Notes

• getCurrentPeriodUsageUsd intentionally stays on primary (db) — see inline comment in kilo-pass-router.ts. Moving it to replica would risk showing stale billing state immediately after usage writes.
• The timedUsageQuery helper casts tx as unknown as DbInstance because Drizzle's transaction type is narrower than the top-level db type but supports the same .select() API. This is the one as cast in the PR — alternatives (generics over Drizzle's internal transaction types) add complexity without safety benefit.
• Phase 2 (bounded queries / period selectors) and Phase 3 (covering indexes) are planned as follow-up PRs per the plan doc.

[jrf0110]

Another thing we could consider - the abuse service currently tracks all usage in cloudflare's analytics engine (backed by clickhouse). It has no problem this load. We're already dual-writing usage there. Perhaps we can offload the aggregate usage stats to that dataset

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (10 files)

• plans/db-perf-improvements.md
• src/app/admin/api/abuse/daily-stats/route.ts
• src/app/admin/api/abuse/hourly-stats/route.ts
• src/app/admin/api/abuse/stats/route.ts
• src/app/api/profile/usage/route.ts
• src/lib/usage-query.ts
• src/routers/kilo-pass-router.ts
• src/routers/organizations/organization-router.ts
• src/routers/organizations/organization-usage-details-router.ts
• src/routers/user-router.ts

---

_{Reviewed by gpt-5.4-20260305 · 805,972 tokens}