scholarr/docs/ops/migration_checklist.md

Migration Checklist

Use this checklist for every schema/data migration.

1. Design Review

• Define change type: expand, backfill, contract.
• Document expected lock behavior and index impact.
• Confirm backward compatibility with currently deployed app version.
• Define rollback strategy before implementation.

2. Pre-Migration Controls

• Capture a fresh backup before applying migration.
• Confirm migration head revision and working tree cleanliness.
• Prepare validation queries for new/changed tables and indexes.
• Identify high-risk tables (large row count, hot write paths).

3. Implementation Standards

• Keep migrations idempotent when feasible.
• Prefer additive steps first (nullable, new index, new table).
• For destructive changes, separate into later contract migration.
• Avoid large blocking rewrites in a single deployment step.

4. Verification

• Apply migration in staging against production-like snapshot.
• Verify:
  • expected tables/columns/indexes,
  • app startup and health endpoint,
  • affected API flows,
  • data consistency queries.

5. Rollout and Recovery

• Apply migration during planned window.
• Monitor logs/errors and DB metrics during rollout.
• If rollback needed:
  • follow downgrade/recovery runbook,
  • restore from backup if downgrade is unsafe,
  • document incident timeline.

6. Post-Migration Tasks

• Update README.md / .env.example / ops docs.
• Add/update integration tests for new schema assumptions.
• Record migration notes in changelog.