# MongoDB Migration Patterns > | Tool | From → To | Downtime | Best for | Parent: [MongoDB Expert Knowledge](https://llms-explorer.com/tree/mongodb-expert-knowledge/) · 19 facets · 66 facts · page: https://llms-explorer.com/tree/mongodb-migration-patterns/ ## Process - Pre-migration check: Atlas validates source cluster compatibility — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#process` - Initial sync: Atlas pulls all documents from source — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#process` - Oplog tailing: Atlas continuously applies changes from source oplog during sync — 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 — 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) — 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 — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#requirements` - Source must be accessible from Atlas servers — 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. — 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 — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#mongosync-limitations` - Destination must be empty at start — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#mongosync-limitations` - No filtering (syncs all databases except admin, local, config) — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#mongosync-limitations` - No support for standalone source (must be replica set) — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#mongosync-limitations` ## Cutover Procedure - Monitor lagTimeSeconds until < 10 seconds — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#cutover-procedure` - Stop writes to source cluster — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#cutover-procedure` - Wait until lagTimeSeconds: 0 and state: COMMITTED — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#cutover-procedure` - Update application connection strings to destination — 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. — 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 — 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) — 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) — 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 — 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) — 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) — 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 — 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 — 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 — 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 — 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 — 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 — 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 — 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 — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-2-initial-sync` - Monitor initial sync progress — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-2-initial-sync` - Monitor source cluster performance (migration reads impact production) — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-2-initial-sync` - Validate document counts periodically — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-2-initial-sync` ## Phase 3: Cutover - Announce maintenance window — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-3-cutover` - Drain writes (stop scheduled jobs, maintenance tasks) — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-3-cutover` - Confirm sync lag < 10 seconds — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-3-cutover` - Stop application writes (brief read-only or maintenance page) — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-3-cutover` - Update connection strings in application config/secrets — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-3-cutover` - Restart applications pointing to Atlas — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#phase-3-cutover` - Verify: check application health, error rates, latency — 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 — 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 — 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 — 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) — 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 — 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 — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#common-migration-anti-patterns` ## References - Atlas Live Migration Documentation — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#references` - mongosync Documentation — source: `https://llms-explorer.com/sources/mdb-context-hub/mongodb-migration-patterns/#references` - MongoDB Relational Migrator — 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](https://llms-explorer.com/tree/mongodb-migration-patterns/) *(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](https://llms-explorer.com/tree/mongodb-migration-patterns/) *(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](https://llms-explorer.com/tree/mongodb-migration-patterns/) *(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](https://llms-explorer.com/tree/mongodb-migration-patterns/) *(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](https://llms-explorer.com/tree/mongodb-migration-patterns/) *(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](https://llms-explorer.com/tree/mongodb-migration-patterns/) *(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](https://llms-explorer.com/tree/mongodb-migration-patterns/) *(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](https://llms-explorer.com/tree/mongodb-migration-patterns/) *(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](https://llms-explorer.com/tree/mongodb-migration-patterns/) *(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](https://llms-explorer.com/tree/mongodb-migration-patterns/) *(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](https://llms-explorer.com/tree/mongodb-migration-patterns/) *(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](https://llms-explorer.com/tree/mongodb-migration-patterns/) *(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](https://llms-explorer.com/tree/mongodb-migration-patterns/) *(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](https://llms-explorer.com/tree/mongodb-migration-patterns/) *(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](https://llms-explorer.com/tree/mongodb-migration-patterns/) *(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](https://llms-explorer.com/tree/mongodb-migration-patterns/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)*