| name | database-migration |
| description | Use when creating, updating, reviewing, or debugging database migrations, schema changes, indexes, constraints, seeds, data migrations, rollback safety, or tenant-safe database changes. |
Database Migration
Use this skill for safe schema, index, seed, and data migration work.
Rules
- Follow the project’s existing database, ORM, migration, and naming patterns.
- Do not add a new ORM, migration tool, database provider, or schema system unless already used or explicitly requested.
- Treat migrations as production-sensitive.
- Avoid destructive changes unless explicitly required and safe.
- Preserve existing data.
- Add indexes and constraints intentionally.
- Keep migrations reversible when the project supports rollback.
- For multi-tenant systems, preserve tenant isolation.
- Do not edit generated migration history carelessly.
- Avoid unrelated schema changes.
Inspect First
Before changing database code, check existing patterns for:
- ORM/database client
- migration folder
- schema naming
- indexes
- constraints
- seeds
- soft delete behavior
- tenant columns/scoping
- rollback strategy
- migration commands
- test database setup
Implementation Checklist
- Identify the exact schema/data change.
- Check existing models and relations.
- Add or update schema definitions.
- Generate or write migration using the project’s tool.
- Add constraints only when existing data allows it.
- Add indexes for common filters, joins, sorts, and tenant scope.
- Handle nullable/backfill steps safely.
- Keep data migrations idempotent where possible.
- Update affected queries, types, tests, and seeds.
- Run migration and relevant tests.
Safety Rules
- Do not drop columns/tables without explicit need.
- For risky changes, prefer expand-and-contract:
- add new nullable field
- backfill data
- switch code
- enforce constraint
- remove old field later
- Avoid long locks on large tables.
- Avoid unbounded data updates without batching when the project is large.
- Do not put secrets or production data in seeds.
- Do not break existing rollback or deploy flow.
Multi-Tenant Rules
- Tenant-owned tables need tenant scope when the project uses tenancy.
- Add tenant-aware indexes for tenant-filtered queries.
- Do not create cross-tenant uniqueness accidentally.
- Verify joins and foreign keys do not break tenant isolation.
- Seeds and fixtures must not mix tenant data incorrectly.
Tests
Cover relevant paths:
- migration applies cleanly
- schema matches model expectations
- affected queries still work
- constraints reject invalid data
- indexes support expected query paths when relevant
- tenant isolation still holds
- rollback if the project supports it
