gracefullight/pkgs / .agents/skills/oma-db
oma-db
VerifiedDesign schemas and migrations, tune queries, or plan vector retrieval and database operations. Application API implementation uses oma-backend.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.7 KB |
| resources/anti-patterns.md | markdown | 6.9 KB |
| resources/checklist.md | markdown | 3.4 KB |
| resources/document-templates.md | markdown | 2.1 KB |
| resources/error-playbook.md | markdown | 3.1 KB |
| resources/examples.md | markdown | 5.6 KB |
| resources/execution-protocol.md | markdown | 5.5 KB |
| resources/iso-controls.md | markdown | 3.2 KB |
| resources/migration-playbook.md | markdown | 5.2 KB |
| resources/query-tuning.md | markdown | 4.4 KB |
| resources/vector-db.md | markdown | 3.9 KB |
resources/error-playbook.md
View on GitHub# DB Agent - Error Playbook
## Symptom: Relational model is breaking 3NF everywhere
- Re-check whether reporting columns, derived values, and snapshots are being mixed into OLTP tables
- Split transactional source-of-truth from read models or marts
- Keep denormalization only where query cost justifies it
## Symptom: NoSQL model keeps requiring cross-document joins
- Re-evaluate aggregate boundaries and access patterns
- If strong cross-entity consistency dominates, switch recommendation toward relational storage
## Symptom: Isolation level is unclear
- Start from anomaly prevention required by the business flow
- Document what must be prevented: dirty read, non-repeatable read, phantom, lost update
- Choose the lowest level that still blocks unacceptable anomalies
## Symptom: Capacity estimate is unreliable
- Separate online traffic, batch traffic, retention, and backup retention
- Estimate by object first, then aggregate to tablespace and disk totals
- Add growth and reindex/maintenance headroom
## Symptom: Backup plan exists but restore confidence is low
- Add restore drill frequency
- Define sample recovery scenarios and max tolerable data loss
- Distinguish snapshot/full backup from incremental/log-based recovery
## Symptom: Deadlocks in production
- Read the engine's deadlock log to identify the two lock cycles, not just the victim
- Enforce consistent lock ordering: all transactions touch shared tables/rows in the same order
- Shorten transactions: move reads, external calls, and computation outside the transaction boundary
- Index foreign keys involved in the cycle; unindexed FK checks escalate to scans and widen lock footprints
- Add bounded retry with backoff at the application layer for the surviving unavoidable cases
## Symptom: Replication lag growing
- Look for long-running transactions on the primary holding back apply/vacuum
- Check for unbatched bulk writes (backfills, cascading deletes) and throttle them per `resources/migration-playbook.md`
- Verify large-table DML has supporting indexes on the replica side
- If reads require read-your-writes, route those sessions to the primary or gate on replica LSN/GTID instead of hoping lag stays low
## Symptom: Connection pool exhausted
- Compare app pool size x instance count against the DB's max connections; oversubscription starves everyone
- Hunt leaked connections: sessions idle-in-transaction, missing release on error paths
- Scope sessions to the request/transaction, never to long-lived objects (see backend rule: no shared mutable ORM sessions)
- Front high-instance-count deployments with a server-side pooler (e.g. pgbouncer) instead of raising max connections
## Symptom: Migration failed midway
- Determine what actually applied: transactional DDL engines roll back cleanly; others leave partial state to inspect object-by-object
- Make migration steps idempotent (`IF NOT EXISTS`, guarded DML) so re-running is safe
- Resume batched backfills from their checkpoint rather than restarting from zero
- If the failure was a lock timeout, that is the playbook working: retry at a quieter window per `resources/migration-playbook.md`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |