generated from john/python-template
93 lines
2.5 KiB
Markdown
93 lines
2.5 KiB
Markdown
# V1 Data Migration and Recovery Guidance
|
|
|
|
This document defines migration/backfill and rollback guidance for the V1 SQLite baseline.
|
|
|
|
## Purpose
|
|
|
|
- provide safe procedures for local schema evolution and recovery
|
|
- reduce data-loss risk during version upgrades
|
|
- establish repeatable pre-change and post-change checks
|
|
|
|
## Current Baseline
|
|
|
|
- canonical relational store: SQLite
|
|
- default DB path: `./transcription.db`
|
|
- schema bootstrap may apply compatibility updates for dev/test scenarios
|
|
|
|
## Pre-Change Checklist
|
|
|
|
Before changing runtime version or schema behavior:
|
|
|
|
1. Stop the app process.
|
|
2. Create a timestamped DB backup copy.
|
|
3. Capture current app commit/version.
|
|
4. Export a quick status inventory:
|
|
- job counts by status
|
|
- total documents/sources/revisions
|
|
5. Ensure sufficient disk space.
|
|
|
|
## Backup Procedure (SQLite)
|
|
|
|
Minimum procedure:
|
|
|
|
1. Stop app.
|
|
2. Copy DB file to a safe location with timestamp.
|
|
3. Store backup path in release notes or change log.
|
|
|
|
## Upgrade Procedure (V1)
|
|
|
|
1. Perform pre-change checklist.
|
|
2. Deploy updated app version.
|
|
3. Start app and observe startup logs.
|
|
4. Verify schema bootstrap completes (if enabled).
|
|
5. Run smoke flow:
|
|
- upload valid file
|
|
- observe terminal status
|
|
- open job detail
|
|
|
|
## Backfill Guidance
|
|
|
|
V1 backfill is limited and conservative:
|
|
|
|
- for records missing newly introduced non-null defaults, use explicit one-time SQL updates only after backup
|
|
- avoid destructive rewrites of `Job.text` or `Revision.text`
|
|
- never backfill by overwriting original immutable transcription output
|
|
|
|
## Rollback Procedure
|
|
|
|
If upgrade fails or causes data inconsistency:
|
|
|
|
1. Stop app.
|
|
2. Restore prior DB backup file.
|
|
3. Revert app version to last known-good commit.
|
|
4. Restart app.
|
|
5. Run smoke flow and confirm stability.
|
|
|
|
## Recovery Scenarios
|
|
|
|
### Stale processing jobs after crash/restart
|
|
|
|
- restart app and allow stale-job recovery to re-queue timed-out `processing` jobs
|
|
- monitor for terminal progression
|
|
|
|
### Schema mismatch symptoms
|
|
|
|
- errors during startup or writes indicating missing columns/indexes
|
|
- rollback to last good DB + app version
|
|
- reattempt with documented upgrade path
|
|
|
|
## Validation Evidence
|
|
|
|
For each upgrade rehearsal, capture:
|
|
|
|
- backup filename/path
|
|
- pre and post job status counts
|
|
- smoke test result
|
|
- rollback rehearsal result (recommended)
|
|
|
|
## Operational Constraints
|
|
|
|
- treat DB backups as required before non-trivial upgrades
|
|
- do not perform in-place DB edits while app is running
|
|
- do not skip post-upgrade smoke validation
|