generated from john/python-template
113 lines
2.9 KiB
Markdown
113 lines
2.9 KiB
Markdown
# 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. |