mk:database
Database patterns — schema design, safe migrations, query optimization, and indexing. PostgreSQL primary; patterns apply to MySQL and SQLite.
| Source | .claude/skills/database/SKILL.md |
| Owner | portability |
| Runtime | portable |
| Risk | high |
What This Skill Does
Owns the data layer end to end: invariants, schema, safe evolution, and query/index evidence, plus the ORM data-access boundary. It discovers the engine, migration tool, and ORM the repository already runs before proposing any syntax — there is no default engine, and an answer written for the wrong one is wasted.
When to Use
- Designing a data model, or changing a schema
- Writing or reviewing a migration, backfill, or recovery path
- Diagnosing a slow query or choosing an index from evidence
- Shaping the ORM data-access boundary, or selecting a datastore on greenfield work
- NOT for: API contracts (
mk:api-design-principles), service or handler code (mk:backend-development), infrastructure and deployment (mk:devops), or the security verdict
Ownership Boundary
| Owner | Owns |
|---|---|
mk:database | Data invariants, schema, migration and recovery, query/index evidence, ORM boundary |
mk:api-design-principles | The API contract — a table is not an API type |
mk:backend-development | The service change that consumes the data |
mk:devops | Provisioning, backups, replicas, and any production effect |
Arguments
[model|migration|query|index|orm|store] [description]
Workflow
- Discover the source of truth — dependency manifest, schema, migration tool, ORM config, query call sites, data tests, active plan. No engine stated means ask.
- Classify — model/schema, migration, query/index, or store and ORM selection
- State invariants before syntax — entity and lifecycle, identity and uniqueness, tenancy and authorization boundary, retention and personal data, consistency need, known access patterns, performance baseline; unknowns marked unknown
- Design proportional to the evidence — normalize or denormalize only with a stated rationale; index from filter/join/order evidence weighed against write cost
- Evolve safely — compatibility with running code, locking behavior at this size, backfill approach, verification signal, and a reverse migration or forward recovery
- Validate and hand off — on a disposable database with synthetic, non-personal fixtures
References
| File | Load when |
|---|---|
references/schema-design.md | Entities, keys, relationships, tenancy, constraints |
references/migration-patterns.md | Changing a table that holds data; backfills; recovery |
references/query-optimization.md | A slow query, or an index decision needing evidence |
Security Constraint
Never build a query by string interpolation or template concatenation. Use the parameter mechanism the driver or ORM provides. Never log, print, or copy personal data while investigating — a row that reproduces a bug can be described by its shape.
Pro Tips
- There is no default engine. Every locking, index-type, and DDL claim below is conditional on the one the repository actually runs.
- The analysing form of
EXPLAINexecutes the statement. Never run it on a mutating statement outside a transaction you will roll back. - A reverse migration that silently discards data is worse than declaring the change irreversible. Say recovery is forward-only and name the corrective change.
- Pool exhaustion looks like a slow query, not a pool error. Check for connections held past their work before optimizing.
mk:build-fix
Universal build error resolver — detects language, loads fix patterns, classifies by fixability, auto-retries up to 3 attempts. Chains into mk:verify.
mk:devops
Infrastructure, containers, CI/CD, deployment safety, observability, and rollback — with a hard secret boundary and no deployment authority.