fiddy/docs/DB_MIGRATION_WORKFLOW.md

DB Migration Workflow (Active Set)

Goal

• Run only approved migration files.
• Keep a clear record of what is in scope and what is applied.

Active Migration Manifest

• Source of truth: packages/db/migrations/active-migrations.json
• Current active set:
  • 007_rate_limits.sql
  • 008_schedules_pivot.sql

Commands

• Show active-scope status:
  • npm run db:migrate:status
• Apply active-scope migrations:
  • npm run db:migrate
• Show full migration status:
  • npm run db:migrate:status:all
• Apply all migration files (escape hatch):
  • npm run db:migrate:all

Tracking

• Applied migrations are tracked in _migrations.
• db:migrate:status reports:
  • APPLIED
  • PENDING
  • HASH_MISMATCH
  • applied files outside active scope

Rule For New Migrations

1. Add the new SQL file under packages/db/migrations/.
2. Append the filename to packages/db/migrations/active-migrations.json.
3. Run npm run db:migrate:status.
4. Run npm run db:migrate.
5. Commit migration + manifest + docs update together.

Notes

• If hash mismatch appears for stale files outside active scope, it does not block active migration runs.
• If hash mismatch appears for a file inside active scope, fix it before applying.