# Database Observability

> Instrument database queries, connection pools, and detect N+1 queries

- Skill: `majiayu000/database-observability` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/database-observability`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/database-observability/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/database-observability

---


# Database Observability

Database is often the bottleneck. Track queries, pools, and patterns.

## Query Span Attributes

| Attribute | Example | Required |
|-----------|---------|----------|
| `db.system` | postgresql, mysql | Yes |
| `db.operation` | SELECT, INSERT | Yes |
| `db.name` | orders_db | Yes |
| `db.sql.table` | users | Recommended |
| `db.statement` | SELECT * FROM users WHERE id = ? | **Parameterized only!** |

## Connection Pool Metrics (USE)

| Metric | Type | Description |
|--------|------|-------------|
| `db.connections.active` | Gauge | In use |
| `db.connections.idle` | Gauge | Available |
| `db.connections.max` | Gauge | Pool limit |
| `db.connections.wait_count` | Counter | Had to wait |
| `db.connections.wait_duration` | Histogram | Wait time |

## Issues to Detect

| Issue | Detection | Fix |
|-------|-----------|-----|
| **N+1 queries** | >10 identical queries per request | Use eager loading |
| **Slow queries** | Duration > p95 threshold | Add indexes, optimize |
| **Pool exhaustion** | wait_count increasing | Increase pool, fix leaks |

## Query Wrapper Pattern

```
Before: Start span (db.system, db.operation, db.sql.table), start timer
After:  Record duration, set db.rows_affected, record errors, end span
```

## Pool Monitor Pattern

```
Every 10s: Record active, idle, wait_count, wait_duration from pool stats
```

## Anti-Patterns

- **Full SQL with values** → PII risk, use parameterized only
- **No pool metrics** → Can't detect saturation
- **Missing slow query alerts** → Problems go unnoticed

## References

- `references/methodology/use-methodology.md`
- `references/platforms/{platform}/database.md`