MongoDB Migration Patterns

Parent: MongoDB Expert Knowledge · researched 2026-05-28T15:16:04.042Z· 10 sources · 10 concepts · skill mongodb-migration-patterns

| Tool | From → To | Downtime | Best for |

Process

Pre-migration check: Atlas validates source cluster compatibility [source]
Initial sync: Atlas pulls all documents from source [source]
Oplog tailing: Atlas continuously applies changes from source oplog during sync [source]
Cutover: When lag < 30 seconds, initiate cutover - stop writes, confirm lag = 0, switch connection strings [source]

Requirements

Source MongoDB: 4.4–8.0; must be a replica set (not standalone) [source]
Atlas cluster must be M10+ in same major version or one version ahead [source]
Source must be accessible from Atlas servers [source]

mongosync — Cluster-to-Cluster Sync

mongosync is MongoDB's cluster-to-cluster synchronization tool. [source]

mongosync Limitations

Source and destination must be compatible versions [source]
Destination must be empty at start [source]
No filtering (syncs all databases except admin, local, config) [source]
No support for standalone source (must be replica set) [source]

Cutover Procedure

Monitor lagTimeSeconds until < 10 seconds [source]
Stop writes to source cluster [source]
Wait until lagTimeSeconds: 0 and state: COMMITTED [source]
Call commit API [source]
Update application connection strings to destination [source]

Relational Migrator

MongoDB Relational Migrator is a free GUI tool for migrating RDBMS schemas and data to MongoDB. [source]

Supported Source Databases

Oracle 11g+, MySQL 5.7+, PostgreSQL 11+, SQL Server 2016+, DB2 11.5+, Sybase/ASE 16.0+, YugabyteDB [source]

Migration Strategy Options

Embedded documents: Denormalize related tables into embedded arrays/documents (recommended for 1:1 or bounded 1:many) [source]
Referenced documents: Keep normalized references (for many:many or unbounded arrays) [source]

Pre-Migration Analysis

Unique index violations in source → become duplicate documents [source]
NULL handling: SQL NULL → MongoDB absence (not null by default) [source]
DECIMAL precision: Map to Decimal128 for financial data (not Double) [source]
Date/time columns: RDBMS timestamps → MongoDB Date with UTC conversion [source]

Snapshot vs CDC Migration

Snapshot only: Full copy; requires application downtime during migration [source]
Snapshot + CDC: Initial snapshot + ongoing change tracking; minimal downtime cutover [source]

Phase 1: Pre-Migration (Days Before)

Source assessment: document count, storage size, index count, write rate [source]
Schema analysis: run Relational Migrator pre-migration advisor [source]
Network validation: confirm Atlas can reach source [source]
Pilot migration: migrate subset of non-critical collections [source]

Phase 2: Initial Sync

Start mongosync or Atlas Live Migration [source]
Monitor initial sync progress [source]
Monitor source cluster performance (migration reads impact production) [source]
Validate document counts periodically [source]

Phase 3: Cutover

Announce maintenance window [source]
Drain writes (stop scheduled jobs, maintenance tasks) [source]
Confirm sync lag < 10 seconds [source]
Stop application writes (brief read-only or maintenance page) [source]
Confirm sync lag = 0 [source]
Update connection strings in application config/secrets [source]
Restart applications pointing to Atlas [source]
Resume writes [source]
Verify: check application health, error rates, latency [source]

Common Migration Anti-Patterns

Migrating without pilot testing: Always test with a non-critical collection first [source]
Not sizing oplog for migration duration: If migration takes > oplog window, migration restarts from scratch [source]
Underestimating initial sync time: 1 TB at 100 MB/s = ~3 hours; plan for 2-3x actual transfer time [source]
Not testing application compatibility before cutover: Atlas has different defaults (w: majority, retryWrites: true, TLS required) [source]
Ignoring DBA user differences: Create all required database users in Atlas before cutover [source]
Single-attempt cutover with no rollback plan: Keep source live for 48 hours post-cutover [source]

References

Atlas Live Migration Documentation [source]
mongosync Documentation [source]
MongoDB Relational Migrator [source]

Children

MongoSync GA Tool (frontier)
Cluster-to-Cluster Sync Phases (frontier)
Relational Migrator (frontier)
Atlas Live Migration (frontier)
mongomirror Deprecation (frontier)
Cutover Strategies (frontier)
Migration Validation Patterns (frontier)
Schema Transformation (frontier)
Sharded Cluster Migrations (frontier)
Common Migration Failures (frontier)

Frontier under this node: Atlas Live Migration, Cluster-to-Cluster Sync Phases, Common Migration Failures, Cutover Strategies, Migration Validation Patterns, MongoSync GA Tool, Relational Migrator, Schema Transformation, Sharded Cluster Migrations, mongomirror Deprecation

← the whole tree · 3D view· how to read this page