Database Migrations Cheat Sheet
Migration workflows, up/down patterns, expand-contract, versioning, and zero-downtime strategies.
Databases
database
migration
schema
Database migrations version-control your schema so changes are repeatable, reviewable, and reversible. A migration is a forward (up) change plus, ideally, a rollback (down).
Migration lifecycle
code
create → apply (up) → verify → rollback (down, if needed)
Table
| Step | Purpose |
|---|---|
| Create | Generate a timestamped migration file. |
| Apply | Run pending migrations in order. |
| Verify | Confirm schema and data are correct. |
| Rollback | Revert the last migration. |
Up and down pattern
sql
-- up
ALTER TABLE users ADD COLUMN email TEXT;
-- down
ALTER TABLE users DROP COLUMN email;
Expand-contract (zero-downtime)
Table
| Phase | Action |
|---|---|
| Expand | Add the new column/table (backward compatible). |
| Migrate | Backfill data in the background. |
| Contract | Drop the old column/table after deploy. |
This avoids breaking the running app during a deploy.
Best practices
Table
| Practice | Why |
|---|---|
| One change per migration | Easier to review and rollback. |
| Idempotent where possible | Safe re-runs. |
| Never edit applied migrations | History must stay immutable. |
| Test up and down | Both directions must work. |
| Back up before destructive changes | Data loss is irreversible. |
Common tools
Table
| Tool | Ecosystem |
|---|---|
| Prisma Migrate | Node/TypeScript. |
| Drizzle Kit | Node/TypeScript. |
| Flyway / Liquibase | Java. |
| Alembic | Python/SQLAlchemy. |
| golang-migrate | Go. |