docs

docs/operations/migration-checklist.md

@@ -0,0 +1,48 @@
+# 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.