ver1 - Step 4 implemented - Revision functionality added

2026-06-26 14:59:16 -05:00
parent 754a273ead
commit dd80cd60cf
16 changed files with 607 additions and 94 deletions
@@ -0,0 +1,113 @@
+# 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.