Our review

Handles safe database schema changes and data migrations with a focus on reversibility and best practices.

Strengths

Every migration is reversible with both up and down scripts
One change per migration to avoid conflicts and simplify rollbacks
Enforces testing on dev and backup before production deployment
Checklist for dangerous operations (rename, drop, type changes)

Limitations

Geared towards Drizzle ORM (not directly applicable to other ORMs)
Requires understanding of database schema design
Can be overkill for trivial schema tweaks

When to use it

When you need to add, modify, or remove database tables or columns safely, with a clear rollback plan.

When not to use it

For ad-hoc data fixes that don't require migration scripts or when using a non-Drizzle ORM without adapting the workflow.

Examples

Add user roles table

Generate a database migration to create a 'roles' table with columns id, name, and description. Follow the reversible migration pattern with up and down scripts.

Rename column safely

Create a migration to rename 'email' column to 'user_email' in the users table using the three-step approach: add new column, copy data, drop old column.

Skill: Database Migration

Description

Handles safe database schema changes and data migrations.

When to Use

Adding/modifying database tables or columns
Changing relationships between entities
Data transformations

Instructions

Migration Rules

Always reversible — every migration needs an up and down
One change per migration — don't bundle unrelated schema changes
Test on dev first — never run untested migrations in production
Backup before production — always have a rollback plan
No data loss — add columns as nullable first, then backfill

Drizzle Workflow

# Generate migration from schema changes
npx drizzle-kit generate

# Review generated SQL in drizzle/ folder
# Apply migration
npx drizzle-kit push

# Or use migrate for production
npx drizzle-kit migrate

Naming Convention

YYYYMMDD_HHMMSS_description.sql Example: 20260212_143000_add_user_roles.sql

Dangerous Operations Checklist

[ ] Column rename → Create new, copy data, drop old (3-step)
[ ] Column type change → Verify data compatibility first
[ ] Drop table → Confirm no foreign key references
[ ] Add NOT NULL → Set default or backfill first

Database Migration

Recommended for