# 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.)* ## Context files - [MongoDB Migration Patterns](https://llms-explorer.com/downloads/sources/mdb-context-hub/mongodb-migration-patterns.md)