transcription/docs/ver1/migration_v1.md

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