V6 Phase 2 complete

docs/data_migration.md

@@ -19,13 +19,36 @@ Optional source overrides:
 - `--source-db <path-or-sqlalchemy-url>`
 - `--source-upload-dir <path>`
 
-### 2) Import bundle into a fresh DB + uploads root
+### 2) Import bundle into a fresh target (SQLite or PostgreSQL)
 
 ```bash
 uv run python tools/export_import_migration.py import --bundle-dir .migration-bundle --target-db .\data\transcription-new.db --target-upload-dir .\data-new
 ```
 
-### 3) One-shot export+import
+PostgreSQL target example:
+
+```bash
+uv run python tools/export_import_migration.py import --bundle-dir .migration-bundle --target-db postgresql://transcription:change-me@localhost:5432/transcription --target-upload-dir .\data-new
+```
+
+### 3) Verify migration parity and integrity
+
+```bash
+uv run python tools/export_import_migration.py verify --source-db .\data\transcription.db --target-db postgresql://transcription:change-me@localhost:5432/transcription
+```
+
+The verify command checks:
+
+- row-count parity across migration tables
+- orphan-reference checks for `source`, `job`, `job_source`, and `execution_attempt`
+- duplicate `(job_id, source_id, attempt_number)` in `execution_attempt`
+
+Exit code:
+
+- `0` when counts and integrity checks pass
+- `1` when mismatches or integrity violations are detected
+
+### 4) One-shot export+import
 
 ```bash
 uv run python tools/export_import_migration.py migrate --bundle-dir .migration-bundle --target-db .\data\transcription-new.db --target-upload-dir .\data-new
@@ -50,9 +73,22 @@ Legacy V4.x portrait/homepage backfill in the export step:
 - Legacy homepage markdown is relocated from `UPLOAD_DIR/homepage/homepage.md` to `UPLOAD_DIR/homepage.md`.
 - Legacy `person.full_name` values are split into `given_names` + `last_name` for V5.1 schema compatibility.
 
-## Cutover
+## Cutover (SQLite -> PostgreSQL)
 
 After importing to a fresh target:
-1. Stop the app.
-2. Point `DATABASE__*` and `UPLOAD_DIR` to the new targets.
-3. Start the app and run smoke checks (`/healthz`, create/upload/process one job).
+1. Stop app and worker services to freeze writes.
+2. Export a migration bundle from the last SQLite state.
+3. Import bundle to PostgreSQL target.
+4. Run `verify` against source and target before switching runtime.
+5. Switch runtime config to PostgreSQL (`DATABASE__DRIVER=postgres` and related `DATABASE__*` values).
+6. Start app and worker services.
+7. Run smoke checks (`/healthz`, create/upload/process one job).
+
+## Rollback
+
+If verify or smoke checks fail:
+
+1. Stop app and worker services.
+2. Revert runtime config to SQLite.
+3. Start app and worker against pre-cutover SQLite database.
+4. Preserve failed migration bundle and logs for analysis.