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