Migration PR Checklist

Use this checklist for any PR that changes the database schema.

Before Opening PR

• Migration file created with sequential numbering (e.g., 0004_add_feature.sql)
• schema.ts updated to match migration
• Migration follows expand-then-contract pattern for destructive changes
• Migration is idempotent (safe to run multiple times)
• Migration has rollback plan documented (if destructive)

Testing

• Ran pnpm migrate:check locally (no errors)
• Applied migration to local dev database successfully
• Verified app works after migration
• Checked for breaking changes to existing queries

Safety Checks

• No data loss: If dropping columns/tables, data is backed up or migrated first
• No downtime: Old code can run during migration (blue-green compatible)
• Reviewed by DBA (if destructive or touches core tables)

Concurrent Migration Check

• Rebased on main within last 24 hours
• No concurrent migrations detected (CI will verify)
• If conflicts exist, renumbered migration and resolved conflicts

Documentation

• Migration purpose documented in file header
• Breaking changes noted in PR description
• Runbook created if manual intervention needed

Destructive Migration? (Check if YES)

If your migration drops columns, drops tables, or changes data types, also check:

• Two-phase deployment planned (expand → migrate data → contract)
• Backup taken before production deploy
• Manual approval from team lead obtained
• Rollback SQL prepared and tested

CI Validation

CI will automatically:

• ✅ Apply migrations to ephemeral DB
• ✅ Compare schema to canonical snapshot
• ✅ Detect concurrent migrations
• ✅ Run smoke tests

If CI fails, do not merge. Resolve issues first.

Post-Merge

After your PR merges to main:

• Verify CI updates canonical schema snapshot
• Monitor staging deployment for issues
• Plan production deployment window (if needed)