Database Migration Runbook SOP
A database migration runbook SOP for planning, executing, validating, and rolling back schema or data changes in a SaaS environment. Use it to reduce downtime, catch data issues early, and close the change with clear evidence.
Trusted by frontline teams 15 years of frontline software
Built for: Saas · Fintech · Healthtech · E Commerce
Overview
This Database Migration Runbook SOP is a step-by-step template for planning, executing, validating, and closing a database schema or data migration in a SaaS environment. It is designed for changes that need clear scope, backup verification, dependency review, controlled execution, post-migration integrity checks, and documented closure.
Use it when a migration could affect customer-facing behavior, reporting accuracy, data retention, or service availability. The template helps the team define success criteria before the change, confirm restore readiness, and assign a clear role for each step so the migration is not dependent on tribal knowledge. It also gives you a place to record deviations, escalation triggers, and the final outcome for audit or release review.
Do not use this SOP as a substitute for a full incident response plan when the database is already degraded, corrupted, or under active attack. It is also not the right fit for tiny local-only changes that do not need backup validation or service coordination. If the migration has no rollback path, no verification plan, or no approved maintenance window, the change should be redesigned before execution. The template is meant to make the migration repeatable, reviewable, and safe to close.
Standards & compliance context
- This SOP supports ISO 9001-style documented information by recording scope, approvals, verification, and closure evidence for the migration.
- The rollback and escalation steps align with controlled change management practices used in ITIL service operations and release management.
- If the migration touches regulated records, the verification and retention steps can support audit expectations for traceability and data integrity.
- For environments with safety- or process-critical data, the runbook should be paired with formal approval and deviation handling consistent with internal quality procedures.
General regulatory context for orientation only — verify current requirements with counsel or the relevant agency before relying on this template for compliance.
What's inside this template
Steps
This section matters because it turns the migration into an ordered sequence of accountable actions with clear verification and escalation points.
-
Confirm the migration scope and success criteria
The release manager confirms the source and target databases, migration type (schema, data, or both), maintenance window, and business owner approval. The release manager records the success criteria, including acceptable downtime, data consistency tolerance, and any known exclusions. The release manager also documents the rollback trigger conditions and escalation path.
-
Validate backups and restore readiness
The database administrator verifies that a current full backup exists for the source database and that the backup retention meets the change requirement. The database administrator confirms the backup timestamp, backup location, encryption status, and restore test evidence. If the restore test is missing or failed, the database administrator escalates before continuing.
-
Review pre-migration data quality and dependencies
The backend engineer reviews row counts, null rates, duplicate keys, and any schema constraints that could block the migration. The backend engineer checks application dependencies, scheduled jobs, integrations, and downstream consumers that may be affected. The backend engineer records any deviations from expected data quality and flags them for the change owner.
-
Place the system in the approved migration state
The site reliability engineer disables non-essential write paths, pauses scheduled jobs, and confirms the application is in the approved maintenance or read-only state. The site reliability engineer records the exact time the state change occurred and verifies that user-facing notifications are active if required.
-
Execute the migration script
The database administrator runs the approved migration script against the target database or source database as defined in the change plan. The database administrator monitors execution output for errors, lock contention, timeout conditions, and any deviation from the expected sequence. If the script fails, the database administrator stops the run, records the failure point, and escalates according to the rollback criteria.
-
Verify post-migration data integrity
The backend engineer runs validation queries to compare source and target row counts, critical record samples, constraint status, and checksum or hash checks where applicable. The backend engineer confirms that the observed variance is within the documented tolerance and that no non-conformance exists for critical records. The backend engineer records any mismatch and opens an incident if the deviation exceeds the approved threshold.
-
Restore service and monitor for defects
The site reliability engineer re-enables application writes, resumes paused jobs, and confirms that the service is returning to normal operation. The site reliability engineer monitors logs, alerts, latency, error rates, and database health for the defined observation period. If a critical alert or data defect appears, the site reliability engineer escalates immediately and initiates rollback if the trigger criteria are met.
-
Document the migration outcome and close the change
The release manager records the final status, start and end times, validation results, deviations, rollback actions if any, and follow-up tasks. The release manager attaches evidence such as logs, screenshots, validation reports, and approval notes. The release manager closes the change only after all required verifications are complete and any non-conformance has an owner and due date.
How to use this template
- 1. The release owner confirms the migration scope, target environment, success criteria, rollback trigger, and approved change window before any script is run.
- 2. The database engineer validates that backups exist, restore tests are current, and the recovery point objective is acceptable for the planned change.
- 3. The application owner reviews data quality, foreign key dependencies, downstream jobs, and any feature flags or compatibility constraints that could affect the migration.
- 4. The operator places the system in the approved migration state, pauses conflicting jobs, and records the exact start time and service status.
- 5. The database engineer executes the migration script, verifies each required checkpoint, and escalates immediately if a deviation or failed verification appears.
- 6. The release owner confirms post-migration integrity, restores service, monitors for defects, and documents the outcome, rollback actions, or follow-up tasks before closing the change.
Best practices
- Write the success criteria before the migration starts so the team can decide quickly whether the change passed or failed.
- Validate restore readiness with an actual test restore, not just a backup timestamp, when the migration affects production data.
- Pause only the jobs that conflict with the migration and record exactly which schedulers, queues, or integrations were disabled.
- Check for downstream dependencies such as reports, caches, search indexes, and ETL jobs before changing table structures or data types.
- Use a staging rehearsal for high-risk migrations so the team can confirm timing, locking behavior, and rollback steps in advance.
- Capture verification evidence at the time of the change, including query results, row counts, checksums, or application smoke-test results.
- Escalate any unexpected lock, timeout, or data mismatch immediately instead of trying to finish the migration by guesswork.
What this template typically catches
Issues teams running this template most often surface in practice:
Common use cases
Frequently asked questions
What kinds of migrations does this SOP cover?
This template covers schema changes, data backfills, column renames, table moves, and other controlled database migrations in a SaaS environment. It is written for planned changes that need verification, rollback readiness, and post-migration monitoring. It is not meant for ad-hoc hotfixes with no change record or for one-off developer experiments.
How often should a database migration runbook be used?
Use it for every production migration and for any staging rehearsal that is meant to validate the production path. Teams often also use it for high-risk non-production changes when the same rollback and verification discipline is needed. If the change affects customer data, service availability, or reporting accuracy, it should go through this SOP.
Who should run this SOP?
A competent person such as a database engineer, platform engineer, or release manager should own the runbook execution, with application and operations roles supporting verification. The person running it should understand the migration script, the rollback path, and the acceptance criteria. If the change is safety- or compliance-sensitive, a second role should confirm the go/no-go decision.
Does this template help with rollback planning?
Yes. The template requires backup validation, restore readiness, and explicit criteria for returning service if verification fails. That makes rollback a documented step rather than an improvised reaction. It also helps you define what counts as a failed migration before you start the change.
How does this relate to ISO 9001 or change control practices?
The SOP supports ISO 9001-style documented information by capturing scope, approvals, verification, and outcome evidence. It also fits formal change control because it records the planned state, the executed steps, and the closure notes. Teams can use it as part of a controlled release process without adding unnecessary bureaucracy.
What are the most common mistakes this runbook prevents?
It helps prevent running a migration without verified backups, skipping dependency checks, and restoring service before data integrity is confirmed. It also reduces the risk of unclear ownership, missing rollback criteria, and incomplete change closure. Those failures are common when teams rely on memory or chat messages instead of a written SOP.
Can this template be customized for different databases or deployment tools?
Yes. You can adapt the steps for PostgreSQL, MySQL, SQL Server, or managed cloud databases, and you can add tool-specific commands for your migration framework. The structure should stay the same even if the script runner, backup method, or monitoring stack changes. That keeps the runbook reusable across services.
How does this fit with CI/CD or deployment automation?
This SOP can sit alongside CI/CD by documenting the manual controls, approvals, and verification gates that automation does not replace. You can link the migration script, pipeline job, and monitoring dashboard in the relevant steps. That makes the runbook useful both for fully manual migrations and for semi-automated releases.
What should I do if post-migration checks fail?
Treat the failure as a deviation and follow the rollback or escalation path defined in the runbook. Do not restore service until the affected tables, queries, or application flows are verified against the success criteria. If rollback is not safe, escalate to the database owner and incident lead for a controlled recovery plan.
Related templates
Go deeper on the topic
-
A standard operating procedure (SOP) is a documented, step-by-step procedure for a repeatable task — the written version of "how we do this here." Good SOPs...
-
Overtime calculation is the process of applying federal, state, local, and contractual rules to hours worked to determine the correct pay — including...
-
Predictive scheduling laws — also called fair workweek laws or secure scheduling — require employers in covered industries to publish employee schedules...
-
Geofencing defines a virtual geographic boundary — a "fence" — around a work location. When an employee's mobile device enters or exits the fence, the...
-
See how customers use MangoApps Projects Module to collaborate, track progress, and share knowledge across teams.
-
Intranet file naming conventions that improve search, reduce clutter, and help employees find the right document fast.
-
AI employee self-service assistants cut HR and IT support time with instant answers, automated routing, and better employee experience.
-
A vendor-agnostic checklist covering architecture, frontline access, AI, compliance, and payroll to evaluate any scheduling platform.
Ready to use this template?
Get started with MangoApps and use Database Migration Runbook SOP with your team — pricing built for small business.
