# 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.