transcription/docs/ver1/ver1-step4-migration-runbook.md

Ver1 Step 4 Migration and Rollback Runbook

Purpose

Provide a concise, operator-safe procedure for schema migration execution, compatibility validation, and rollback/mitigation for personal-scale deployments.

This runbook supports docs/ver1/ver1-step4.md and REQ-10 by keeping normal production startup non-mutating unless explicitly configured otherwise.

---

Preconditions

1. Application version to deploy is known and checked out.
2. .env values are configured for target environment.
3. Database backup path is prepared.
4. Application process is stopped before migration on production-like systems.

---

Commands

Use explicit migration runner operations:

1. List pending migrations:
   • uv run python -m transcription.migration_runner --list
2. Apply pending migrations:
   • uv run python -m transcription.migration_runner --apply
3. Validate schema compatibility:
   • uv run python -m transcription.migration_runner --check

Recommended execution order:

1. --list
2. backup database
3. --apply
4. --check
5. start application

---

Backup Procedure (SQLite Baseline)

For SQLite deployments, copy the DB file before migration:

• Example DB path default: ./transcription.db
• Keep timestamped backup copy in a safe location.

If the file is in active use, stop the app first.

---

Verification Checklist

After migration apply:

1. --check exits successfully.
2. schema_migration_history includes applied revisions.
3. Application starts successfully.
4. Health endpoint responds: /healthz.
5. Critical flows smoke-check:
   • upload
   • job processing
   • revision listing/acceptance

---

Rollback and Mitigation Decision Tree

1. If migration fails before changes commit:
   • fix issue
   • re-run apply
2. If migration partially applied or compatibility check fails:
   • stop app
   • restore from backup
   • investigate and produce forward-fix migration if needed
3. If app starts but functional invariants fail:
   • stop app
   • restore backup
   • add corrective migration/backfill and rehearse before retry

For this Step 4 baseline, backup restore is the primary rollback mechanism.

---

Failure Classification Guidance

Classify migration failures using docs/error_handling.md categories:

• transient connection issues -> infrastructure_transient_error
• permissions/misconfiguration -> infrastructure_persistent_error
• unexpected migration logic defects -> internal_unexpected_error

Record failure details with operation context and timestamp.

---

Operational Notes

• migration_auto_apply_on_startup defaults to False.
• validate_schema_on_startup defaults to True.
• Startup schema validation fails fast on incompatibility.

This protects production from accidental schema drift.

---

Post-Step-4 Follow-Up

If migration complexity grows beyond lightweight revision scripts, introduce a dedicated migration framework in a future step while preserving this runbook structure and operator-first workflow.