What it is
The Database Migration Runbook is a step-by-step operational document that walks a team through moving a production database from one place to another — between engines (say MySQL to PostgreSQL), between major versions, or from a self-managed server to a cloud-managed platform like Amazon Aurora. It is structured as five sequential phases: assess and plan, convert the schema, load the data, validate, and cut over. Each phase carries its own checklist of concrete tasks, so the migration runs as a script you execute rather than a set of decisions you improvise mid-window.
What separates a runbook from a vague migration plan is that it pre-decides the hard parts before the clock is running. It forces you to choose a strategy up front — a big-bang downtime window versus a CDC-based near-zero-downtime cutover using binlog, WAL, or oplog replication — and it sets a hard rollback deadline so nobody is debating whether to abort at 3am. The document is engine-agnostic in structure but specific in practice: it expects you to resolve type mappings, collation differences, and sequence-versus-auto-increment quirks as real work, not footnotes.
Crucially, the runbook treats validation and rollback as first-class phases rather than afterthoughts. Before any traffic moves, a Pre-Cutover Gate requires a validated restorable backup, passing row-count and checksum reconciliation, green application smoke tests, confirmed zero replication lag, and a tested rollback procedure with a named owner. That gate is the difference between a migration you can trust and one you are merely hoping works.
What it's used for
Teams reach for a migration runbook whenever the cost of getting a database move wrong is high — which is nearly always, because the database holds the state everything else depends on. It is used to turn a risky, one-shot event into a rehearsed, reversible procedure. The concrete jobs it does:
- ✓ Planning an engine or version change — inventorying the source schema, data volume, and incompatible types, extensions, or stored procedures before committing to a target.
- ✓ Choosing and documenting a cutover strategy — deciding between a downtime window and a change-data-capture approach that keeps the target in sync via binlog/WAL/oplog replication until the final repoint.
- ✓ Converting and staging schema as reviewable migration scripts in version control, so the target DDL is peer-reviewed and builds clean in a sandbox before any row of data moves.
- ✓ Sequencing the bulk data load during low traffic — deferring non-essential indexes during insert and rebuilding them afterward for speed, while tracking row counts and load duration to size the real cutover window.
- ✓ Validating the move with row-count and checksum reconciliation, referential-integrity spot checks, encoding and timezone verification, and EXPLAIN ANALYZE benchmarks that confirm no query-plan regression on the target.
- ✓ Executing a controlled cutover — going read-only on the source, draining final CDC changes to zero lag, repointing connection strings or DNS, and running post-cutover smoke tests before re-enabling traffic.
- ✓ Defining a tested, owned rollback path so that if the gate fails, the team reverts cleanly to the source instead of patching forward under pressure.
Who uses it
A migration touches more than the person typing the commands, so the runbook is written to be read by several roles who each own a slice of the outcome. It is the shared source of truth during the window.
Context & good to know
Database migrations are among the highest-stakes operations any engineering team runs, because unlike an application deploy you cannot simply roll back a container image — the data has moved, and moving it back may itself lose writes. That asymmetry is why the runbook front-loads so much rehearsal: staging the schema in a sandbox, reconciling checksums table by table, and confirming zero replication lag before the repoint. The discipline exists precisely because the failure mode is data loss, not just downtime.
The rise of managed cloud databases has made migrations more common, not less. Teams move off self-managed PostgreSQL or MySQL onto platforms like Amazon Aurora to offload backups, patching, and failover; others consolidate onto MongoDB or migrate between Oracle Database versions to stay supported. Each move surfaces the same recurring questions buyers ask — what is an example of a database software, and which of the four broad database types (relational, document, key-value, and wide-column) fits the workload. A runbook keeps those strategic choices from derailing the tactical execution.
The near-zero-downtime pattern the runbook describes — initial bulk load plus change data capture until a brief read-only cutover — has become the default expectation for any database serving live traffic. It depends on the engine's replication stream (binary log in MySQL, write-ahead log in PostgreSQL, oplog in MongoDB) being healthy and drainable to zero lag, which is why the runbook treats lag confirmation as a gating check rather than a nice-to-have.
Spotsaas publishes this runbook as part of its database-management resources because the teams comparing engines on the platform — weighing Oracle Database, MongoDB, PostgreSQL, MariaDB, and Aurora — almost always face a migration as the cost of switching. A clear runbook makes that cost legible: it turns 'how hard would it be to move?' into a concrete, phased checklist a team can scope and rehearse.