| layout | default | ||
|---|---|---|---|
| title | Migration Rules | ||
| nav_order | 4 | ||
| parent | Nice-to-Have | ||
| checklist_enabled | true | ||
| checklist_stage | stage-4 | ||
| checklist_section | Nice-to-Have Artifact Checklist | ||
| checklist_order | 4 | ||
| checklist_audit_areas |
|
Database migrations are high-risk changes. A bad migration can lock tables, corrupt data, or make rollback impossible. LLMs will generate migrations if asked — and without rules, they'll generate naive ones that work in development but fail in production.
Migration rules constrain how schema changes are introduced, tested, and deployed.
- Migration tooling — which tool generates and runs migrations
- What requires a migration — vs what can be changed without one
- Safety rules — what's allowed in a single migration, size limits, locking concerns
- Rollback expectations — must migrations be reversible?
- Review process — who approves schema changes
## Migration Rules
Tool: Prisma Migrate (schema in prisma/schema.prisma)
Rules:
- Never modify or delete an existing migration file
- One logical change per migration (don't combine table creation with data backfill)
- Always test migrations against a copy of production data before deploying
- Adding columns: must be nullable or have a default (no locks on large tables)
- Removing columns: deprecate first (stop reading), then remove in a later migration
- Renaming: create new column, backfill, update code, drop old column (3 migrations)
LLM-specific:
- The model must NEVER generate or modify migration files directly
- The model can modify prisma/schema.prisma
- Human runs `prisma migrate dev` to generate the migration
- Human reviews the generated SQL before applyingLetting the model generate migrations directly. Migration files should be generated by the migration tool, not hand-written by an LLM. The model should modify the schema definition; the tool generates the SQL.
No rule about combining changes. A migration that creates a table, adds indexes, and backfills data is nearly impossible to debug if it fails. One change per migration.
Forgetting about production data volume. Adding a NOT NULL column without a default locks the table for the duration of the backfill. This works in dev (100 rows) but kills production (10M rows).
- Claude Code: Include in CLAUDE.md LLM Guardrails — migration files should be on the protected list.
- All tools: This guideline works alongside guardrails. The guardrails say "don't touch migrations." This guideline explains the correct process.