Data Migration Cutover Playbook

Template Overview

Data migrations are among the highest-risk maneuvers in software engineering. One missing index, corrupted foreign key, or premature DNS switch can cause irreversible data loss and extended outages. The Data Migration Cutover Plan details pre-migration backups, dual-write synchronization phases, validation scripts, cutover checkpoints, and instant rollback procedures in plain Markdown.

Markdown Template Structure

Copy the block below or click Download .md File to add this template directly to your personal vault:

---
title: "Migration Playbook: [Migration Name / DB Source to Target]"
date_scheduled: [YYYY-MM-DD]
cutover_lead: "[[Principal Data Architect]]"
database_source: "Legacy SQLite v3.38 schema"
database_target: "Optimized WAL SQLite v3.46 schema"
maintenance_window_utc: "02:00 - 04:00 UTC"
maximum_acceptable_downtime: "0 Minutes (Zero Downtime Target)"
rollback_plan_tested: true
tags: [database, migration, cutover, playbook, devops, sre]
---

# Data Migration Cutover Plan — [Migration Name]

## 1. Migration Overview & Strategic Objective
- **System Scope:** Upgrade client local vault index database from legacy schema v1 to relational metadata schema v2.
- **Data Volume:** ~50,000 Markdown note index entries and 200,000 full-text search tokens per user vault.
- **Success Criteria:** 100% record integrity, zero data loss, completed in under 12 seconds per gigabyte on Apple Silicon.

## 2. Multi-Stage Cutover Strategy
```text
Phase 1: Shadow Schema Creation ──> Phase 2: Dual Writes Active ──> Phase 3: Background Backfill
       │
       ▼
Phase 4: Integrity Verification ──> Phase 5: Read Cutover ───────> Phase 6: Legacy Decommission

3. Minute-by-Minute Cutover Execution Runbook

Time (T-minus / T+)	Step Description	Executing Engineer	Verification Command	Rollback Trigger
T - 60 min	Freeze schema changes in repository	Lead Architect	git status clean on main	Any unmerged migration PR
T - 30 min	Perform full snapshot backup of vault index	Automated script	sqlite3 vault.db ".backup vault_pre.db"	Backup checksum mismatch
T - 10 min	Run dry-run migration script on shadow copy	Data Engineer	Exit code 0 on dry-run	Any schema exception
T + 00 min	EXECUTE CUTOVER: Run schema migration	Data Engineer	python3 scripts/migrate_v2.py	Migration runtime > 60s
T + 05 min	Run data checksum validation query	QA Lead	SELECT count(*) FROM v1_notes = v2_notes	Count discrepancy > 0
T + 10 min	Switch application read pointer to v2 schema	Systems Engineer	App launches and loads notes	App UI crash on launch
T + 15 min	Mark legacy schema as read-only	Systems Engineer	PRAGMA table_info verification	-

4. Integrity Validation Script & Checksums

-- Validate that zero records were dropped during table migration
SELECT 
    (SELECT COUNT(*) FROM legacy_notes) AS legacy_count,
    (SELECT COUNT(*) FROM modern_notes) AS modern_count,
    CASE 
        WHEN (SELECT COUNT(*) FROM legacy_notes) = (SELECT COUNT(*) FROM modern_notes) 
        THEN 'INTEGRITY VERIFIED' 
        ELSE 'ABORT: ROW COUNT MISMATCH' 
    END AS validation_status;

5. Instant Rollback Protocol

[!CAUTION] Rollback Activation If any checksum mismatch or fatal SQL constraint error occurs during T+05, immediately abort migration:

1. Revert application config pointer to vault_pre.db.
2. Terminate background migration process.
3. Post incident notification in war room channel.
4. Legacy database remains untouched and fully functional.

6. Post-Migration Verification Checklist

• Full-text search returns accurate results in under 5ms.
• Vault note creation creates proper rows in new v2 schema.
• Pre-migration backup securely stored for 30 days.

## Filled Real-World Example

Here is a realistic example demonstrating how this template captures actual deliberations:

```markdown
---
title: "Migration: Vault Index v2 Upgrade"
date_scheduled: 2026-10-07
cutover_lead: "[[Devin Zhao]]"
database_source: "SQLite v1"
database_target: "SQLite v2 (FTS5)"
tags: [database, migration]
---

# Data Migration Cutover Plan — Vault Index v2 Upgrade

## 1. Summary
Devin Zhao led the SQLite full-text search migration across test vaults.

## 2. Result
All 50,000 note entries migrated in 4.2 seconds with 100% record parity. Zero downtime observed.

When to Use and When to Avoid

When to Use

• Use prior to executing high-risk production database migrations or schema upgrades.
• Use during platform transitions from legacy systems to modern infrastructure.
• Use to coordinate multi-engineer teams during weekend or late-night cutover windows.

When to Avoid

• Avoid using for adding a single non-breaking nullable column to a development database.
• Avoid using when building prototypes with disposable test data.

On-Device AI Integration

Summarize your recording in Oyma with this local instruction:

Analyze the database schema diff and migration specifications:
1. Break down the migration into sequential zero-downtime phases (shadow, dual-write, backfill, cutover).
2. Formulate explicit minute-by-minute execution runbooks with verification commands.
3. Detail concrete rollback procedures and SQL integrity validation checks in Markdown.

Your data remains securely on your Mac with zero cloud exposure.