A database migration checklist is a control framework for moving production data from one database environment to another without losing track of compatibility, recovery, write authority, validation, and rollback.
For most small teams, the practical plan has six phases: assess the source, prepare the target, prove recovery, move and synchronize data, perform a controlled cutover, then validate before retiring the source. The copy itself is only one part of the project.
At Raff, teams can migrate supported workloads into Managed Databases when they want to reduce host-level database operations, or continue on Raff VM when the workload requires operating-system or filesystem control. If PostgreSQL or MySQL is already selected, review the live Managed PostgreSQL and Managed MySQL pages before planning production compatibility around a specific feature or version.
This guide owns the migration checklist and go/no-go process. For synchronization, expand-contract schema changes, staged backfills, and low-downtime cutovers, use Zero-Downtime Database Migrations.
The migration checklist has six control gates
| Phase | Main question | Evidence required before continuing |
|---|
| 1. Assess | Is the target compatible with the real workload? | Engine/version, extensions, clients, dependencies, data size, write rate |
| 2. Prepare | Is the target production-ready? | Networking, credentials, capacity, backups, monitoring, connection model |
| 3. Prove recovery | Can the team recover if migration fails? | Tested source recovery point, rollback owner, RPO/RTO |
| 4. Move and sync | Is the target complete and current enough? | Transfer logs, counts/checks, synchronization health, lag threshold |
| 5. Cut over | Which database is authoritative now? | Go/no-go approval, final sync, endpoint switch, write control |
| 6. Validate | Can the application safely stay on the target? | Business workflows, data checks, jobs, integrations, backups, monitoring |
A migration should not advance because the previous command completed. It should advance because the evidence for the next risk boundary exists.
1. Start the migration plan with the target state
Before choosing export/import, replication, change data capture, or another migration method, document what production should look like after the move.
Record:
- source engine and version;
- target engine and version;
- required extensions, plugins, collations, and character sets;
- application runtime and database drivers;
- stored procedures, triggers, generated columns, scheduled events, or database jobs;
- users, roles, and permission model;
- current data size and expected growth;
- peak write rate;
- peak connection demand;
- connection pooling behavior;
- application-to-database network path;
- backup and point-in-time recovery requirements;
- monitoring and alert ownership;
- availability requirements;
- maintenance expectations;
- migration owner;
- go/no-go approver;
- rollback approver.
This is where provider compatibility should be checked.
For Raff, use the live Managed PostgreSQL or Managed MySQL page and console as the source of truth for current engine availability, supported capabilities, networking, backup and recovery behavior, connection model, limits, and optional availability features. Do not build a production migration around engine versions or product limits copied from an older guide.
A target is compatible only when the application, data model, operational requirements, and recovery path all fit.
2. Inventory every database client before data moves
The main web application is rarely the only client of a production database.
Inventory every reader and writer:
- web or API application instances;
- background workers;
- scheduled jobs;
- queue consumers;
- reporting services;
- analytics or ETL jobs;
- admin tools;
- migration tools;
- monitoring accounts;
- integration services;
- operations scripts.
Then record how each client discovers and authenticates to the database:
| Client dependency | What to record |
|---|
| Endpoint | Hostname, DNS, direct or pooled endpoint, port |
| Credentials | Secret location, role, rotation path |
| TLS | Required mode, certificate assumptions |
| Pooling | Pool size, recycle behavior, timeout |
| Network | VPC/private path, firewall, allowlist |
| Deploy behavior | How config changes reach running processes |
| Reconnect | Whether the client caches connections or endpoints |
A migration can copy every row correctly and still fail because one worker continues writing to the old source or one long-lived pool never reconnects.
The checklist should track clients, not only database objects.
3. Choose the migration method from downtime and rollback requirements
Use the least complex method that satisfies the business requirement.
| Migration condition | Practical starting method | Main trade-off |
|---|
| Small database, maintenance window acceptable | Logical export/import | More downtime, simpler authority and rollback |
| Same engine, shorter interruption required | Baseline copy plus ongoing synchronization | More synchronization, lag, and rollback complexity |
| Provider-to-provider move | Export/import or supported replication path | Feature and endpoint differences |
| Major-version change | Tested supported upgrade or logical migration | Compatibility validation required |
| Cross-engine migration | Logical transformation plus application changes | Highest compatibility and validation scope |
| Large, write-heavy workload | Baseline plus change synchronization plus controlled cutover | Requires strong lag, consistency, and rollback controls |
A maintenance window is not a migration failure. For a small team, a planned write interruption can be safer than a replication and failback system the team cannot operate confidently.
Use Zero-Downtime Database Migrations when the business requirement justifies staged synchronization, expand-contract, dual compatibility, or near-zero-downtime techniques.
4. Prove source recovery before changing production authority
A current backup is necessary. A tested recovery path is stronger evidence.
Before migration day, define:
- approved RPO;
- approved RTO;
- newest usable recovery point;
- expected restore duration;
- source retention after cutover;
- rollback deadline;
- person authorized to restore or roll back;
- application validation required after recovery.
At minimum, confirm that the recovery path can return a usable copy of the source database and that the application can connect to it in an isolated environment.
A recovery test should answer:
- Can the backup or recovery chain actually be restored?
- Are the expected schemas, roles, permissions, and extensions present?
- Can the application authenticate?
- Are critical records available?
- Does the measured recovery time fit the migration's rollback assumptions?
A backup job marked successful does not prove that the rollback path will work under production pressure.
Use Database Backup Strategy for SaaS Apps and Database Restore Testing for the broader recovery framework.
5. Make the target production-ready before the copy starts
Provisioning the target is not the same as preparing it for cutover.
Verify:
- target engine and version compatibility;
- required extensions and features;
- schema compatibility;
- storage capacity and growth headroom;
- connection limits;
- connection pooling path;
- TLS requirements;
- users and roles;
- private networking or scoped public access;
- application credentials;
- backup and recovery configuration;
- monitoring and alerts;
- availability settings where required;
- maintenance expectations;
- application configuration for the new endpoint.
Then run representative application tests against the target before migration day where possible:
- authentication;
- critical reads;
- critical writes;
- transactions;
- background jobs;
- reports;
- migration framework operations;
- connection-pool behavior;
- reconnect after connection interruption;
- application startup with the target endpoint.
A SQL connection succeeding proves connectivity. It does not prove production compatibility.
Raff's PostgreSQL and MySQL free tiers start at $0/month, which gives teams a low-cost target for early application-compatibility checks.
6. Separate baseline transfer from ongoing synchronization
For low-downtime migrations, treat the initial copy and ongoing-change synchronization as different operating phases.
Source database
-> baseline copy
Target database
-> ongoing synchronization
Lag + consistency reach approved cutover state
-> final write-control phase
-> target becomes authoritative
During the baseline transfer, record:
- transfer start and finish time;
- source data size;
- target data size;
- row or object counts where useful;
- excluded objects;
- failed objects;
- schema differences;
- transfer errors or retries.
During synchronization, monitor:
- replication or change-capture health;
- current lag;
- lag trend;
- retained source logs;
- schema compatibility;
- target write capacity;
- network stability;
- unsupported objects or DDL changes;
- synchronization errors.
Do not cut over because a synchronization process is merely "running." Define what ready for cutover means before migration day.
Examples of readiness criteria include:
- no unresolved synchronization errors;
- lag below the agreed threshold;
- required objects validated;
- source backup and recovery current;
- target monitoring active;
- application change prepared;
- rollback owner available.
Operational insight from Raff: treat replication lag, recovery readiness, and write authority as separate cutover gates rather than one "replication is running" signal.
7. Freeze risky change before the cutover window
Migration risk increases when the application schema, source database, and target database all change at once.
Before the final window, define a temporary change policy for:
- schema migrations;
- extension or plugin changes;
- large imports;
- index rebuilds;
- bulk jobs;
- major application deployments;
- credential rotation;
- network changes.
This does not mean the whole business must stop changing for days. It means the migration window should not overlap avoidable structural changes that can invalidate compatibility or synchronization assumptions.
8. Use an explicit go/no-go checkpoint
Immediately before cutover, the migration owner should be able to answer these questions with evidence:
- Is the source recovery path current?
- Is the target healthy?
- Are synchronization errors resolved?
- Is lag within the approved threshold?
- Have schema and dependency checks passed?
- Are all application clients accounted for?
- Are the endpoint and credentials ready?
- Are monitoring and alerts active on the target?
- Is the rollback path still practical?
- Are the go/no-go and rollback approvers available?
If a condition is unknown, treat it as a decision risk rather than assuming it is safe.
9. Keep one authoritative database during cutover
The most important database migration rule is simple:
At every stage, the team should know which database is authoritative for new writes.
A controlled cutover can look like this:
| Phase | Authoritative system | Write behavior |
|---|
| Before cutover | Source | Normal production writes |
| Final synchronization | Source | Writes controlled according to migration plan |
| Endpoint switch | Transition explicitly owned | Prevent accidental split authority |
| After switch | Target | Approved clients write to target |
| Rollback window | Defined in runbook | Source and target write policy remains explicit |
A practical sequence is:
- Confirm go/no-go evidence.
- Freeze or control writes according to the plan.
- Let final synchronization complete.
- Run final database consistency checks.
- Switch application endpoint, secrets, or configuration.
- Recycle clients or pools that retain old connections.
- Verify target reads.
- Verify controlled target writes.
- Verify workers, jobs, integrations, and reporting clients.
- Declare the target authoritative.
- Start the rollback observation window.
Avoid a period where some systems write to the source and others write to the target without an explicit reconciliation design.
10. Validate business correctness, not only row counts
Database-level validation should include relevant technical checks such as:
- expected schemas and tables;
- key row or object counts;
- recent records;
- primary and foreign keys;
- indexes;
- sequences or auto-increment state;
- users and permissions;
- extensions or plugins;
- representative checksums or samples where useful.
Application validation should include the business workflows that matter:
- sign-in;
- tenant or account lookup;
- critical create or update flow;
- billing or subscription lookup where applicable;
- background workers;
- scheduled jobs;
- integrations;
- reports and exports;
- connection-pool behavior;
- latency and error rates.
The provider can help prove database state. The application team is usually the only party that can prove whether migrated data is correct for the business.
11. Rollback needs a trigger, deadline, and write policy
"Keep the old database online" is not a complete rollback plan.
Document:
- conditions that trigger rollback;
- rollback approver;
- rollback deadline;
- endpoint-switch method;
- source state during the observation window;
- whether the source remains read-only or writable;
- how target-only writes will be handled;
- how divergence will be detected;
- when rollback becomes impractical;
- when the old source can be retired.
Useful rollback triggers can include:
- sustained application error rate above the agreed threshold;
- critical workflow failure;
- unresolved data mismatch;
- missing required database capability;
- unacceptable latency;
- connection exhaustion;
- failed workers or integrations;
- inability to meet an agreed recovery objective.
Rollback becomes harder after the target begins accepting new writes. The runbook should explain what happens to those writes if the source must become authoritative again.
12. Managed databases change the operating boundary after migration
Migrating to a managed database changes who operates parts of the database platform, but it does not transfer application responsibility.
Use the live Raff Managed Databases and engine-specific product pages to verify the current provider-managed scope before cutover.
Depending on the selected service and current capabilities, the managed platform can reduce work around:
- database host provisioning;
- platform maintenance;
- managed backup and recovery workflows;
- service monitoring;
- storage operations;
- supported availability features;
- private connectivity.
The application team still owns:
- schema and data model;
- queries and indexes;
- application credentials;
- migrations;
- connection pooling behavior;
- capacity decisions;
- recovery-point selection where applicable;
- application reconnect behavior;
- business validation;
- cutover and rollback decisions.
Teams that need operating-system access, custom packages, unsupported extensions or topology, or another hard host-level requirement can use Raff VM instead of forcing the workload into a managed service.
For teams evaluating provider help rather than only the execution checklist, continue with Database Migration Services: Costs, Process & Provider Checklist.
The production checklist should be signed off before source retirement
Discovery
Recovery
Target readiness
Data movement
Go/no-go
Cutover
Validation and completion
Common migration mistakes create authority and recovery gaps
Treating the migration as a data-copy job
A complete migration also changes endpoints, credentials, recovery, monitoring, application behavior, and operational ownership.
Assuming a managed target is automatically compatible
Verify the exact engine, features, extensions, connection behavior, networking, and recovery requirements against the live target service.
Cutting over because replication is running
Use measurable readiness conditions such as lag, errors, validation, and recovery status.
Testing only row counts
Business workflows, permissions, sequences, jobs, integrations, and connection behavior can fail even when broad counts match.
Keeping both databases writable without an authority rule
This can create divergence that turns rollback into a data-reconciliation incident.
Keep the source according to the documented rollback and retention plan until the team has enough evidence to decommission it safely.
A safe migration ends after recovery and rollback controls are proven
A database migration checklist should control compatibility, recoverability, authority, validation, and rollback from the first assessment through source retirement.
Prepare the target before data moves. Prove the source recovery path before cutover. Use measurable synchronization and go/no-go criteria. Keep one authoritative writer. Validate application behavior after the switch, and retire the source only after the rollback window and recovery controls are confirmed.
For Raff Managed PostgreSQL or MySQL migrations, use the live product pages and console to confirm current compatibility and service capabilities before the final production cutover.
If the broader operating model is still undecided, return to Managed Database vs Self-Hosted.
Sources
