# 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