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 integrity issues early, and document a clean change record.
Trusted by frontline teams 15 years of frontline software
Built for: Saas · Fintech · Healthtech · B2b Software
Overview
This Database Migration Runbook SOP template covers the full change sequence for a planned schema or data migration in a SaaS environment: scope confirmation, backup verification, script validation, write pause, execution, data and application checks, service restoration, and closeout. It is designed for changes that can affect customer-facing availability, data integrity, or downstream jobs, so the runbook makes the actor, verification, and escalation points explicit.
Use this template when a migration needs a controlled window, a known rollback path, and documented evidence that the system returned to a healthy state. It works well for schema alterations, data corrections, backfills, index changes, and migrations that require temporary isolation of the target database or application. It is also useful when multiple roles are involved, such as database engineering, application support, and incident response.
Do not use this template as-is for trivial non-production changes, exploratory database work, or tasks that do not need verification and rollback discipline. If the migration is fully automated and non-disruptive, you can simplify the pause and restore steps, but you should still keep the validation and closeout sections. The runbook should also be tightened for regulated data, customer-impacting changes, or any migration where a failed step could create a non-conformance or data loss event.
Standards & compliance context
- This SOP supports ISO 9001-style documented information by capturing the planned change, execution evidence, verification results, and closeout record.
- The stepwise verification and escalation structure aligns with ITIL change management practices for controlled service changes and incident prevention.
- For regulated data environments, the template helps preserve traceability and review evidence consistent with GMP-like recordkeeping expectations.
- If the migration affects hazardous operational systems or safety-related controls, adapt the approval and isolation steps to match permit-to-work and controlled-change requirements.
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 a risky database change into a controlled sequence with clear ownership, verification, and rollback points.
-
Confirm the migration scope and change window
The release manager verifies that the change ticket includes the exact schema or data changes, affected services, planned start and end times, and named owner. The operator confirms that the maintenance window is active before any database changes begin.
-
Verify pre-migration backups are complete
The database administrator verifies that a fresh backup has completed successfully and that the backup is stored in the approved location. The database administrator confirms the backup timestamp, retention label, and restore test status before proceeding.
-
Validate migration scripts and dependencies
The backend engineer reviews the migration scripts for syntax, ordering, idempotency, and dependency compatibility. The engineer verifies that any required feature flags, application version constraints, or foreign key dependencies are documented before execution.
-
Pause write activity and isolate the target system
The site reliability engineer disables non-essential write paths, pauses background jobs that modify the target tables, and confirms that no competing deployment is running. The engineer records the exact time the system was isolated.
-
Execute the migration
The database administrator runs the approved migration steps in the documented order. The administrator records any warnings, notices, or deviations from expected behavior and stops immediately if an unrecoverable error occurs.
-
Verify data integrity and application behavior
The quality owner verifies that record counts, checksum or sampling checks, foreign key integrity, and critical application transactions match the expected post-migration state. The operator confirms that error rates, latency, and database health metrics remain within tolerance.
-
Restore service and monitor for regressions
The release manager re-enables paused jobs, restores write traffic, and monitors the system for errors, queue buildup, or performance degradation during the observation period. The manager confirms that the service remains stable before closing the change.
-
Document the outcome and close the change
The release manager documents the final status, validation results, any deviations, and the names of the actors who completed each critical step. The manager confirms whether the change is closed, requires follow-up, or must remain open for monitoring.
How to use this template
- 1. The change owner confirms the migration scope, affected tables or services, maintenance window, rollback threshold, and approval path before any execution begins.
- 2. The database engineer verifies that backups are complete, restorable, and time-aligned with the planned change window, then records the backup reference in the change ticket.
- 3. The operator validates the migration scripts, dependency order, environment variables, and test results, and escalates any unresolved deviation before production use.
- 4. The operator pauses write activity, isolates the target system or tenant, and confirms that background jobs, replicas, and integrations will not reintroduce conflicting writes.
- 5. The operator executes the migration, verifies data integrity and application behavior against the expected outcome, restores service, and documents the result with any follow-up actions or non-conformance notes.
Best practices
- Assign one named actor to own the cutover so every step has a clear decision-maker and escalation path.
- Verify the backup restore path, not just backup completion, before you touch production data.
- Record the exact script version, migration timestamp, and target environment so the change can be reproduced or rolled back.
- Pause all write sources, including background workers and scheduled jobs, before the migration starts.
- Check row counts, key constraints, and sample records after the migration to catch silent corruption or partial updates.
- Keep a rollback trigger defined in advance, such as failed verification, unexpected lock contention, or missing records.
- Do not resume traffic until application behavior, error rates, and database health are stable under real load.
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, index rebuilds, and controlled data transformations in a SaaS database. It is written for planned changes that need a change window, verification, and rollback criteria. If the migration is a one-off emergency fix, you can still use the structure, but you should tighten the approval and escalation steps.
How often should a database migration runbook be used?
Use it for every planned database migration, including small schema edits that seem low risk. The point is to keep the same verification and rollback discipline whether the change is routine or high impact. Teams often reuse the same SOP for release trains, maintenance windows, and customer-specific data moves.
Who should run this SOP?
A competent person such as a database engineer, platform engineer, or senior SRE should own the execution, with application and support roles on standby as needed. The person running it should understand the migration script, the rollback path, and the service dependencies. If the change affects customer data or regulated records, include the appropriate data owner or approver in the change process.
Does this template help with compliance requirements?
Yes, it supports documented information and controlled change practices that align with ISO 9001-style quality management expectations. It also fits the kind of traceability and verification discipline used in regulated environments, including GMP-like recordkeeping and ITIL change control practices. It is not a legal substitute, but it helps you capture the evidence auditors usually expect.
What are the most common mistakes this runbook helps prevent?
The biggest failures are skipping backup verification, running scripts without testing dependencies, and resuming writes before integrity checks are complete. Teams also miss rollback criteria, forget to isolate background jobs, or fail to monitor for delayed regressions after service is restored. This SOP forces those checks into the sequence instead of relying on memory.
Can I customize this for zero-downtime migrations?
Yes, you can adapt the steps for online schema changes, dual-write patterns, or phased cutovers. Keep the same structure, but adjust the pause, isolation, and verification steps to match your deployment method. If the migration is truly no-downtime, the runbook should still define what counts as a safe deviation and when to escalate.
How does this compare with an ad-hoc migration checklist?
An ad-hoc checklist usually tells people what to do, but not who does it, what to verify, or when to stop. This SOP adds role-based steps, explicit verification, escalation criteria, and a documented closeout record. That makes it easier to repeat, audit, and hand off across teams.
What integrations or artifacts should be linked to the SOP?
Link the migration ticket, backup job record, script repository, monitoring dashboard, and incident channel. If your team uses CI/CD or database deployment tooling, include the exact pipeline or release reference so the runbook points to the executed version. Those links make the change traceable and reduce confusion during rollback or post-change review.
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.
-
MangoApps explains why vector embeddings are derived data, not source data — and why regeneration beats backup for AI-powered search reliability.
Ready to use this template?
Get started with MangoApps and use Database Migration Runbook SOP with your team — pricing built for small business.
