Migration Playbook Pack

We built this skill because manual migration runbooks are a liability. Every engineer who has stared at a terminal window during a 2 AM cutover knows the feeling: the schema parity is broken, the replication lag is spiking, and the rollback plan is a guess. We created the Migration Playbook Pack to eliminate that guesswork. It's a 5-phase workflow system that maps the entire migration lifecycle—from initial assessment to final cutover—using production-grade templates, automated validation scripts, and canonical reference architectures. If you're planning a database migration, this is the infrastructure you need to ship it without waking up the on-call team.

The Cutover Trap: Why 'Big Bang' Migrations Keep Failing

Engineers love the idea of a clean break. Freeze the application, dump the database, restore it on the new stack, point the DNS, and unfreeze. It sounds clean on a whiteboard. In production, it's a disaster waiting to happen. The moment you touch the write path, you introduce significant risk ^[1]. Most teams skip the dual-write phase because it feels like extra application logic, but that's exactly where the trust breaks down. You end up with schema drift between your old and new databases, and by the time you realize the parity is broken, you're already in the freeze window.

If you're just implementing version-controlled database schema changes without a migration strategy, you're building on sand. We see this constantly. Teams treat migrations as an afterthought to their comprehensive guide for backend developers to design, implement, and maintain robust database systems, only to find out that the new schema doesn't support the legacy queries during the transition. The "Big Bang" approach assumes a perfect world where data is static and the application can tolerate a hard stop. Neither is true for high-throughput systems. The real world demands incremental transitions, and that requires a disciplined dual-write strategy that keeps your systems in sync until you're ready to flip the switch.

The Real Cost of Schema Parity Gaps and Replication Lag

Ignoring the migration plan doesn't save time; it mortgages your reliability. When you skip rigorous validation, you're gambling with data integrity. Most migrations fail at the reconciliation stage because teams underestimate the complexity of keeping two systems in sync ^[8]. A single missed edge case in your dual-write logic can lead to silent data corruption, where rows exist in the new database but not the old, or vice versa. The financial impact is immediate. Every minute of unplanned downtime during a cutover bleeds revenue and erodes customer trust. Beyond the direct cost, you're burning senior engineering hours debugging replication lag spikes that could have been caught by a pre-flight check.

If your Database Reliability Engineering practices don't include a hardened migration playbook, you're flying blind. The cost of a failed cutover isn't just the rollback; it's the hours spent reconstructing the state, the angry stakeholders, and the technical debt you accrue by patching a botched migration with hotfixes. Validation and reconciliation are where most migrations fail if ignored ^[7]. Without automated checks, you're relying on manual spot-checks that miss the edge cases. You need a system that enforces structural completeness and validates your configuration before it ever touches production traffic. This isn't about being cautious; it's about respecting the data you're responsible for.

How a 10TB Time-Series Migration Almost Went Off the Rails

Picture a fintech team that needs to migrate a 10TB time-series database from a legacy monolith to a distributed cloud-native store. They decide to use a dual-write strategy to ensure zero downtime. The application logic is updated to write to both the old and new databases simultaneously. During the backfill phase, they encounter a massive latency spike. The replication lag grows to 45 minutes because the dual-write logic isn't batching writes efficiently. The team realizes too late that their schema parity is off; a specific timestamp format used in the old system isn't supported in the new one. They're stuck. The backfill is taking weeks, not days, and the cutover window is approaching.

This is exactly the scenario our Practical guide to cloud migrations is designed to prevent. By using a structured approach, the team could have validated their dual-write configuration before touching production traffic. They could have run the validate-dualwrite-config.sh script to catch missing fields like sync_mode or backfill_window before they caused a production incident. Instead, they're scrambling to patch the application logic while the business demands the migration finish. The examples/production-migration.yaml file in this pack demonstrates how to properly schedule backfill windows for 10TB+ datasets, ensuring you don't overwhelm your network or your database during peak hours. It shows you how to handle the latency/consistency trade-offs explicitly, so you don't have to learn it the hard way.

From Guesswork to RFC-Compliant Cutover Execution

Once you install the Migration Playbook Pack, the ambiguity disappears. You get a 5-phase workflow that maps the entire migration lifecycle: Assessment, Dual-Write Setup, Backfill, Verification, and Cutover. The skill provides production-grade templates that enforce discipline. The migration-plan.yaml template forces you to define your assessment criteria, dual-write sync configuration, and rollback triggers upfront. You don't have to guess how to handle static vs. dynamic data; the cutover-runbook.md template gives you a step-by-step checklist that covers freeze windows, point-of-no-return definitions, and post-cutover validation steps.

The validation scripts ensure your configuration is valid. The validate-dualwrite-config.sh script parses your YAML and exits with a non-zero code if required fields are missing. The cutover-checklist.json validator enforces structural completeness of your runbooks. You can even use the provided SQL queries for real-time data reconciliation, checking row count parity and checksum validation during the dual-write phase. This turns a high-risk, manual process into a repeatable, automated workflow. It integrates seamlessly with your existing Comprehensive release management workflow, ensuring that your migration is just another controlled release in your pipeline. You can also use this skill alongside guides developers through planning, extracting, transforming, and loading database contents to ensure your ETL processes are aligned with your migration strategy. The result is a cutover that feels like a deployment, not a disaster.

What's in the Migration Playbook Pack

• skill.md — Orchestrator skill definition that maps the 5-phase migration workflow (Assessment, Dual-Write Setup, Backfill, Verification, Cutover) and explicitly references all relative paths for templates, references, scripts, validators, and examples.
• templates/migration-plan.yaml — Production-grade YAML template for end-to-end migration planning, including assessment criteria, dual-write sync configuration, backfill windowing, data mapping, and rollback triggers.
• templates/cutover-runbook.md — Step-by-step cutover execution checklist covering freeze windows, static vs dynamic data migration, point-of-no-return definition, and post-cutover validation steps.
• references/dual-write-architecture.md — Embedded canonical knowledge on dual-write patterns: bidirectional sync mechanics, schema parity requirements, backfill strategies for 100GB-10TB+ time-series data, and latency/consistency trade-offs.
• references/cutover-strategies.md — Embedded reference covering flash-cut, incremental, and active/active database cutover strategies, WIP/static vs dynamic data handling, communication freeze protocols, and zero-downtime phase transitions.
• scripts/validate-dualwrite-config.sh — Executable bash script that parses a migration YAML config, validates required dual-write fields (source, target, sync_mode, backfill_window, cutover_window), and exits 1 on missing or malformed values.
• validators/cutover-checklist.json — JSON Schema validator that enforces structural completeness of cutover runbooks, ensuring required phases, rollback steps, and data verification checkpoints are present.
• tests/test-validation.sh — Test harness that executes the config validator and JSON schema checker, asserts non-zero exit codes on failure, and validates example files against production standards.
• examples/production-migration.yaml — Worked example filling the migration template for a 10TB time-series database migration, demonstrating dual-write backfill scheduling and cutover sequencing.
• examples/data-verification-query.sql — Production SQL queries for real-time data reconciliation during dual-write, including row count parity checks, checksum validation, and replication lag monitoring.

Stop Shipping Manual Runbooks. Start Shipping Migrations That Stick.

Manual runbooks are a liability. They rot, they get outdated, and they fail when you need them most. The Migration Playbook Pack gives you a system that enforces discipline, validates your configuration, and guides you through the most dangerous phase of any database migration. Upgrade to Pro to install this skill and stop guessing. Start shipping migrations that stick.