MongoDB Migration Patterns
Parent: MongoDB Expert Knowledge · Published reference · snapshot 2026-09-08 · skill mongodb-operations-expert/references/mongodb-migration-patterns.md
↓ Facts as markdownall context files
| Tool | From → To | Downtime | Best for |
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
Process
- Pre-migration check: Atlas validates source cluster compatibility [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#process]
- Initial sync: Atlas pulls all documents from source [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#process]
- Oplog tailing: Atlas continuously applies changes from source oplog during sync [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#process]
- Cutover: When lag < 30 seconds, initiate cutover - stop writes, confirm lag = 0, switch connection strings [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#process]
Requirements
- Source MongoDB: 4.4–8.0; must be a replica set (not standalone) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#requirements]
- Atlas cluster must be M10+ in same major version or one version ahead [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#requirements]
- Source must be accessible from Atlas servers [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#requirements]
mongosync — Cluster-to-Cluster Sync
- mongosync is MongoDB's cluster-to-cluster synchronization tool. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#mongosync-cluster-to-cluster-sync]
mongosync Limitations
- Source and destination must be compatible versions [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#mongosync-limitations]
- Destination must be empty at start [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#mongosync-limitations]
- No filtering (syncs all databases except admin, local, config) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#mongosync-limitations]
- No support for standalone source (must be replica set) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#mongosync-limitations]
Cutover Procedure
- Monitor lagTimeSeconds until < 10 seconds [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#cutover-procedure]
- Stop writes to source cluster [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#cutover-procedure]
- Wait until lagTimeSeconds: 0 and state: COMMITTED [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#cutover-procedure]
- Update application connection strings to destination [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#cutover-procedure]
Relational Migrator
- MongoDB Relational Migrator is a free GUI tool for migrating RDBMS schemas and data to MongoDB. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#relational-migrator]
Supported Source Databases
- Oracle 11g+, MySQL 5.7+, PostgreSQL 11+, SQL Server 2016+, DB2 11.5+, Sybase/ASE 16.0+, YugabyteDB [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#supported-source-databases]
Migration Strategy Options
- Embedded documents: Denormalize related tables into embedded arrays/documents (recommended for 1:1 or bounded 1:many) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#migration-strategy-options]
- Referenced documents: Keep normalized references (for many:many or unbounded arrays) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#migration-strategy-options]
Pre-Migration Analysis
- Unique index violations in source → become duplicate documents [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#pre-migration-analysis]
- NULL handling: SQL NULL → MongoDB absence (not null by default) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#pre-migration-analysis]
- DECIMAL precision: Map to Decimal128 for financial data (not Double) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#pre-migration-analysis]
- Date/time columns: RDBMS timestamps → MongoDB Date with UTC conversion [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#pre-migration-analysis]
Snapshot vs CDC Migration
- Snapshot only: Full copy; requires application downtime during migration [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#snapshot-vs-cdc-migration]
- Snapshot + CDC: Initial snapshot + ongoing change tracking; minimal downtime cutover [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#snapshot-vs-cdc-migration]
Phase 1: Pre-Migration (Days Before)
- Source assessment: document count, storage size, index count, write rate [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-1-pre-migration-days-before]
- Schema analysis: run Relational Migrator pre-migration advisor [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-1-pre-migration-days-before]
- Network validation: confirm Atlas can reach source [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-1-pre-migration-days-before]
- Pilot migration: migrate subset of non-critical collections [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-1-pre-migration-days-before]
Phase 2: Initial Sync
- Start mongosync or Atlas Live Migration [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-2-initial-sync]
- Monitor initial sync progress [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-2-initial-sync]
- Monitor source cluster performance (migration reads impact production) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-2-initial-sync]
- Validate document counts periodically [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-2-initial-sync]
Phase 3: Cutover
- Announce maintenance window [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-3-cutover]
- Drain writes (stop scheduled jobs, maintenance tasks) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-3-cutover]
- Confirm sync lag < 10 seconds [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-3-cutover]
- Stop application writes (brief read-only or maintenance page) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-3-cutover]
- Update connection strings in application config/secrets [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-3-cutover]
- Restart applications pointing to Atlas [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-3-cutover]
- Verify: check application health, error rates, latency [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-3-cutover]
Common Migration Anti-Patterns
- Migrating without pilot testing: Always test with a non-critical collection first [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#common-migration-anti-patterns]
- Not sizing oplog for migration duration: If migration takes > oplog window, migration restarts from scratch [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#common-migration-anti-patterns]
- Underestimating initial sync time: 1 TB at 100 MB/s = ~3 hours; plan for 2-3x actual transfer time [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#common-migration-anti-patterns]
- Not testing application compatibility before cutover: Atlas has different defaults (w: majority, retryWrites: true, TLS required) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#common-migration-anti-patterns]
- Ignoring DBA user differences: Create all required database users in Atlas before cutover [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#common-migration-anti-patterns]
- Single-attempt cutover with no rollback plan: Keep source live for 48 hours post-cutover [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#common-migration-anti-patterns]
References
- Atlas Live Migration Documentation [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#references]
- mongosync Documentation [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#references]
- MongoDB Relational Migrator [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#references]
Where this helps
- Planning a cutover from a self-managed replica set to Atlas using Live Migration or mongosync, when minimizing downtime matters. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Migrating an RDBMS schema (Oracle, MySQL, PostgreSQL, SQL Server, DB2) to MongoDB and needing to decide between embedding and referencing for each table relationship. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Sizing the pre-migration window correctly — oplog size, initial-sync duration, and pilot-testing scope — before committing to a cutover date. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Deciding whether a migration needs a maintenance window at all (snapshot-only) or can achieve near-zero downtime (snapshot + CDC via mongosync/Atlas Live Migration). [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Project ideas
- Build a migration readiness checker that validates source cluster compatibility (version range, replica-set topology, network reachability) before attempting an Atlas Live Migration. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Automate a pilot-migration workflow that migrates a non-critical collection first, validates document counts and application compatibility, then gates the full migration on that pilot's success. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Build a cutover-lag dashboard that polls lagTimeSeconds during mongosync's initial sync and alerts when it's safe to schedule the cutover window. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Write a schema-mapping tool using Relational Migrator's pre-migration advisor output to flag DECIMAL columns that need Decimal128 and unique-index violations that would become duplicate documents. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Common mistakes
- Migrating without a pilot test on a non-critical collection first, skipping the chance to catch schema or application-compatibility issues before the real cutover. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Sizing the oplog for normal operations instead of for the full expected migration duration — if migration exceeds the oplog window, it restarts from scratch. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Underestimating initial sync time by not accounting for realistic transfer rates (roughly 1TB at 100MB/s takes about 3 hours) and planning for 2-3x that as a buffer. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Cutting over without a rollback plan, instead of keeping the source cluster live for a defined window after cutover in case of an issue. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Known issues
- mongosync requires the destination cluster to be completely empty at the start and cannot filter which databases sync — it syncs everything except admin, local, and config, which constrains partial-migration strategies. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Atlas applies different defaults than many self-managed deployments (w: majority, retryWrites: true, TLS required by default), so an application that worked against a permissive self-managed cluster can break against Atlas without code changes. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- mongosync only supports a replica set as the source, not a standalone deployment, so a standalone source must first be converted before cluster-to-cluster sync is possible. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- SQL NULL and MongoDB's field-absence semantics differ (a NULL column becomes an absent field, not a null value, by default), which can silently change query behavior for code that assumes SQL-style NULL handling. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Children
- MongoSync GA Tool (frontier, viability 3.35 / 5)
- Cluster-to-Cluster Sync Phases (frontier, viability 4.05 / 5)
- Relational Migrator (frontier, viability 4.45 / 5)
- Atlas Live Migration (frontier, viability 4.25 / 5)
- mongomirror Deprecation (frontier, viability 3.63 / 5)
- Cutover Strategies (frontier, viability 4.38 / 5)
- Migration Validation Patterns (frontier, viability 3.60 / 5)
- Schema Transformation (frontier, viability 3.20 / 5)
- Sharded Cluster Migrations (frontier, viability 3.58 / 5)
- Common Migration Failures (frontier, viability 3.67 / 5)
Frontier under this node: Atlas Live Migration (4.25), Cluster-to-Cluster Sync Phases (4.05), Common Migration Failures (3.67), Cutover Strategies (4.38), Migration Validation Patterns (3.60), MongoSync GA Tool (3.35), Relational Migrator (4.45), Schema Transformation (3.20), Sharded Cluster Migrations (3.58), mongomirror Deprecation (3.63)