# Database Migrations

> Use when: write and apply schema migrations safely without downtime or data loss.

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

---


Goal: schema changes that are reversible, ordered, and safe in production.

Use for:
- adding, altering, or dropping columns and tables
- coordinating schema and code deploys
- avoiding locks and data loss on large tables

Workflow:
1. Make each migration small, ordered, and version-controlled.
2. Prefer additive changes; split risky changes into steps.
3. Use expand-then-contract for renames and type changes.
4. Backfill data in batches to avoid long locks.
5. Deploy code that tolerates both old and new schema.
6. Verify on a production-like dataset before rollout.

Expand/contract:
- add new column/table, deploy dual-write code
- backfill, then switch reads
- remove old column only after nothing uses it

Rules:
- never edit an already-applied migration; add a new one
- avoid long-held locks on large tables
- make migrations reversible or document the rollback
- test against realistic data volume, not an empty schema