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
- Atlas Live Migration
- mongomirror Deprecation (frontier, viability 3.63 / 5)
- Cutover Strategies
- 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 under this node: Cluster-to-Cluster Sync Phases (4.05), Migration Validation Patterns (3.60), MongoSync GA Tool (3.35), Schema Transformation (3.20), Sharded Cluster Migrations (3.58), mongomirror Deprecation (3.63)