profile-db-usagelisted
Install: claude install-skill tstapler/stapler-squad
# Profile DB Usage (pool wait, contention, slow queries)
Find which pool is starved, which call site holds it, and fix demand before raising limits. Read-only on the live DB.
Related: `sqlite-optimizer` (PRAGMAs, indexes, EXPLAIN), `go:optimize` / `golang-profiling` (CPU, mutex), `observability-victoriametrics-tempo` (querying the stack), `observability-grafana-dashboards` (editing panels). Metric reference: `docs/reference/database-observability.md`. Pool layout: `docs/adr/ADR-036-database-pool-registry.md`.
## 0. Quick triage
| Owner symptom | Start at |
|---|---|
| "pool waits are high", "saturating" | section 2 first four queries, then 3.1 / 3.2 |
| "database is locked" / SQLITE_BUSY | `db_busy_errors_total` (section 2), then `BEGIN`/`COMMIT` rows in `/actuator/db` `top_statements` (3.4) |
| "which query is slow" | by-caller `topk` queries (section 2), `top_statements` by `total_ms - pool_wait_ms` |
| "need more ent-read connections" | "Does ent-read need more than 4" in section 3 |
Step 0 for every case: rule out the host. `uptime` load average vs `sysctl -n hw.ncpu` (or `nproc`), swap and disk. A load several times the core count slows every statement and looks like pool saturation; also exclude the first minutes after a restart (startup maintenance and backfills burst). Raising limits does not fix a loaded host; reducing demand still helps.
## 1. Find the data
| Source | How |
|---|---|
| VictoriaMetrics | `docker ps --format '{{.Names}} {{.Ports}}' \| grep vict