# mongosync > mongosync is MongoDB's official utility for continuous, real-time replication between two MongoDB clusters. It performs a full initial sync followed by change-stream-based CDC (no Kafka, no Debezium) Parent: [MongoDB Expert Knowledge](https://llms-explorer.com/tree/mongodb-expert-knowledge/) · 47 facets · 164 facts · page: https://llms-explorer.com/tree/mongosync/ ## mongosync — MongoDB's Native Live Migration Tool - mongosync is MongoDB's official utility for continuous, real-time replication between two MongoDB clusters. It performs a full initial sync followed by change-stream-based CDC (no Kafka, no Debezium) and supports cutover with sub-minute downtime, reverse sync for rollback, and filtered namespace replication. mongosync powers Atlas Live Migration and Cluster-to-Cluster Sync. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#mongosync-mongodbs-native-live-migration-tool) ## 1. Architecture — Initial Sync + Ongoing CDC - mongosync runs as a standalone Go binary outside of mongod/mongos. It opens connections to two clusters and moves data in two phases: — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#1-architecture-initial-sync-ongoing-cdc) - Initial sync - mongosync reads collection data from the source cluster in parallel workers, applies inserts to the destination cluster, builds indexes, and tracks progress per-collection. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#1-architecture-initial-sync-ongoing-cdc) - Change Event Application (CEA) - once initial sync completes, mongosync tails the source via change streams, applies operations to the destination, and stays in lockstep until you commit or pause. mongosync does not read the oplog directly - it relies on the change-streams API. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#1-architecture-initial-sync-ongoing-cdc) - Because CDC runs over change streams, mongosync's resumability depends on the source oplog window. If un-applied operations age out of the source oplog, the change stream returns ChangeStreamHistoryLost and mongosync fails - see Section 6. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#1-architecture-initial-sync-ongoing-cdc) ## Topology notes - Replica set → replica set: one mongosync instance. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#topology-notes) - Sharded → sharded: run one mongosync per shard on the source. mongosync replicates individual shards in parallel from source to destination. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#topology-notes) - Replica set → sharded and sharded → replica set: supported with a single mongosync for the all-to-one cases, with caveats; check the version-specific topology page. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#topology-notes) - Both clusters must run MongoDB 6.0 or later and share the same major version (mongosync also supports certain version-cross migrations - confirm against the version matrix for your mongosync release). — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#topology-notes) ## Migration host sizing - For a production sync, MongoDB recommends a dedicated migration host with at least 8 CPUs and 24 GB of RAM. The host needs network reachability to both clusters and enough disk for logs and the local progress state. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#migration-host-sizing) ## CLI vs config file - mongosync accepts CLI flags or a YAML/JSON config file via --config. The config file is the production-grade path because: — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cli-vs-config-file) - Passwords on the command line are visible to ps, top, and audit logs. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cli-vs-config-file) - The config file can be reloaded mid-migration to change settings like loadLevel. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cli-vs-config-file) ## Core connection options - > Cluster role (source vs destination) is not set on the binary - it's decided by the call to the /api/v1/start endpoint. The same mongosync process can be reversed; see Section 8. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#core-connection-options) ## REST API surface - mongosync exposes an HTTP API on 127.0.0.1:27182 (default port). Key endpoints: — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#rest-api-surface) ## `start` body — the essential fields - reversible:true + enableUserWriteBlocking:true are both required to support reverse sync later. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#start-body-the-essential-fields) - enableUserWriteBlocking tells mongosync to block writes on the destination during the sync so reverse sync remains safe. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#start-body-the-essential-fields) ## Basic filters - includeNamespaces and excludeNamespaces are mutually exclusive arrays of filter objects. Each object has a database and optionally a collections array. With no filter mongosync performs a full cluster sync (every non-system database/collection). — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#basic-filters) - This includes only sales.EMEA, sales.APAC, and every collection under marketing. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#basic-filters) ## Regex filters (mongosync 1.6+) - Filter values can be regular expressions, so you can match many databases/collections at once: — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#regex-filters-mongosync-16) ## Namespace remapping - namespaceRemap lets you rewrite the destination namespace, useful for tenant consolidation or rename-during-migration. The destination database and/or collection name can differ from the source. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#namespace-remapping) ## Filter immutability - You cannot change a filter on a running sync. Stop mongosync, prepare the destination (drop any partially-synced collections), and start a new sync with the updated filter. There is no in-place filter edit. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#filter-immutability) ## Items mongosync never replicates - local, config, admin database internals (system collections). — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#items-mongosync-never-replicates) - User credentials and roles - you must recreate roles/users on the destination. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#items-mongosync-never-replicates) - Any collection mongosync flags as "unsupported" for the version (e.g., certain time-series edge cases - check the FAQ for your release). — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#items-mongosync-never-replicates) ## Where state lives - mongosync writes progress and resume tokens to the destination cluster (in a metadata collection mongosync owns). That is why resume after a process crash works even on a brand-new mongosync host: the durable checkpoint lives next to the data. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#where-state-lives) ## Resume rules - resume only works if mongosync is in PAUSED state (or the process was killed in RUNNING and you bring it back). — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#resume-rules) - After resume, mongosync may take at least 2 minutes before re-entering RUNNING - it re-validates the resume token and reopens the change stream. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#resume-rules) - The resume token is a change-stream _data value. If the oplog has rolled past it, the change stream errors with ChangeStreamHistoryLost and the sync cannot resume - you must drop the destination and start over. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#resume-rules) ## When you cannot resume - Long pause + small source oplog → window exhausted. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#when-you-cannot-resume) - Destination collection dropped/altered while mongosync was paused. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#when-you-cannot-resume) - Filter change attempted (filters are immutable - see Section 3). — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#when-you-cannot-resume) ## 5. Verification - mongosync ships four verification methods. Pick based on cluster shape and downtime budget. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#5-verification) ## 5.1 Embedded verifier (default, replica sets) - On by default for replica-set clusters. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#51-embedded-verifier-default-replica-sets) - Runs in the background after initial sync, comparing documents on the destination as they are written. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#51-embedded-verifier-default-replica-sets) - No locks, no extra downtime. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#51-embedded-verifier-default-replica-sets) ## 5.2 Hash comparison (dbHash MD5) - dbHash MD5 over each collection on source vs destination. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#52-hash-comparison-dbhash-md5) - Locks the cluster for the duration of the hash - no writes can land. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#52-hash-comparison-dbhash-md5) - Not available on sharded clusters. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#52-hash-comparison-dbhash-md5) - Slow on large collections; precise. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#52-hash-comparison-dbhash-md5) ## 5.3 Document counts - Cheapest method: db.coll.countDocuments() on both sides. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#53-document-counts) - Only safe for insert-only workloads - it cannot detect document drift from updates. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#53-document-counts) ## 5.4 Migration Verifier (`mongodb-labs/migration-verifier`) - Standalone open-source tool from MongoDB Labs. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#54-migration-verifier-mongodb-labsmigration-verifier) - Connects to source and destination, compares documents/views/indexes. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#54-migration-verifier-mongodb-labsmigration-verifier) - Can run concurrently with mongosync - no need to pause. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#54-migration-verifier-mongodb-labsmigration-verifier) - The right choice for large, heavily-mutated, or sharded migrations. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#54-migration-verifier-mongodb-labsmigration-verifier) ## Oplog window exhaustion - Symptom: mongosync exits with ChangeStreamHistoryLost or similar - the source oplog rolled past mongosync's resume point. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#oplog-window-exhaustion) - Initial sync taking too long on a high-write source. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#oplog-window-exhaustion) - Long pause while CDC is suspended. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#oplog-window-exhaustion) - Source oplog sized too small (default 5% of disk can be tiny on busy servers). — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#oplog-window-exhaustion) - Pre-sync: increase oplogSizeMB (or replSetResizeOplog with minRetentionHours > expected sync duration). — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#oplog-window-exhaustion) - During sync: scale up the mongosync host (more CPU/RAM) so CDC keeps up. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#oplog-window-exhaustion) - Post-failure: drop destination collections and restart - there is no recovery once the oplog window is gone. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#oplog-window-exhaustion) - Rule of thumb: set minRetentionHours to 2–3× the expected initial-sync duration plus any pause window. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#oplog-window-exhaustion) ## Network partitions - mongosync retries transient network errors with exponential backoff. Sustained partitions cause mongosync to surface errors via /progress and eventually stop. Restart picks up from the last checkpoint iff the oplog window is still intact. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#network-partitions) ## Schema drift - mongosync replicates DDL via change events - collection creates, drops, index builds. It does not repair manual drift on the destination. If someone writes directly to the destination while a sync runs, you've corrupted the migration; restart from scratch. enableUserWriteBlocking on the destination is the guardrail. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#schema-drift) ## Stalled progress - Check /api/v1/progress for lagTimeSeconds. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#stalled-progress) - Check destination index builds - slow index builds back up CDC. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#stalled-progress) - Check destination CPU/IOPS - loadLevel may be too high. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#stalled-progress) ## Cannot reverse / reverse refused - reversible was not true at start. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cannot-reverse-reverse-refused) - enableUserWriteBlocking was not true. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cannot-reverse-reverse-refused) - Source and destination MongoDB major versions differ. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cannot-reverse-reverse-refused) - Topologies differ (e.g., replica set vs sharded). — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cannot-reverse-reverse-refused) - Destination oplog rolled past the moment mongosync went canWrite=true. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cannot-reverse-reverse-refused) ## 7. mongosync vs Atlas Live Migration vs Cluster-to-Cluster Sync - All three use the same underlying mongosync engine. The difference is the operating envelope: — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#7-mongosync-vs-atlas-live-migration-vs-cluster-to-cluster-sync) ## Decision rules - Need filtered sync, namespace remap, private link, or cross-version → standalone mongosync. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#decision-rules) - Smaller cluster going into Atlas with public network → Atlas Live Migration (one-click). — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#decision-rules) - Long-lived ongoing replication between two clusters (DR, multi-region, active-passive) → Cluster-to-Cluster Sync (same binary, configured to never reach COMMITTED). — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#decision-rules) ## Cutover process - mongosync is RUNNING with lagTimeSeconds low (sub-second on healthy networks). — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cutover-process) - Quiesce application writes on the source. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cutover-process) - Call POST /api/v1/commit. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cutover-process) - mongosync moves to COMMITTING - drains remaining change events. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cutover-process) - mongosync reaches COMMITTED - final state. The destination is now authoritative. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cutover-process) - Flip application connection strings to the destination cluster. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cutover-process) - Healthy production cutovers complete in under 60 seconds because mongosync already had CDC caught up before commit. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cutover-process) ## Reverse sync — rollback - If the destination misbehaves post-cutover, you can flip the direction: — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#reverse-sync-rollback) - reversible:true set at original start. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#reverse-sync-rollback) - enableUserWriteBlocking:true set at original start. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#reverse-sync-rollback) - Same major version on both clusters. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#reverse-sync-rollback) - Same topology (replica set ↔ replica set, or sharded ↔ sharded). — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#reverse-sync-rollback) - The destination cluster's oplog has not rolled past the canWrite=true moment. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#reverse-sync-rollback) - After reverse, the original destination becomes source, and writes on the new source flow back to the original source. Filtered Sync is not supported during reverse - reverse syncs the full cluster. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#reverse-sync-rollback) ## State machine summary - State transitions are mostly API-driven; COMMITTING→COMMITTED and REVERSING→RUNNING are automatic. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#state-machine-summary) ## loadLevel - 1–4 scale. Default 3. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#loadlevel) - Higher means more parallelism on both sides → faster initial sync, more load on the destination. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#loadlevel) - Can be changed mid-sync by editing the config file and signaling mongosync. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#loadlevel) ## One mongosync per shard - For sharded sources, run one mongosync instance per shard for true parallel copy. Coordinate them so they share the destination cluster's URI. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#one-mongosync-per-shard) ## Index builds - Allocate 100 MB–1 GB of memory per concurrent index build. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#index-builds) - Keep total concurrent-index-build memory under 20% of destination RAM. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#index-builds) - mongosync defers some index builds until after initial sync to avoid contention. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#index-builds) ## Balancer - Disable the balancer on the sharded destination (sh.stopBalancer() / balancerStop) before starting the migration. The balancer fighting with mongosync inflates the migration window and can cause chunk-move-vs-CDC races. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#balancer) ## Other tuning knobs - Increase migration host CPU/RAM if CDC lag grows. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#other-tuning-knobs) - Increase source oplog window proactively for long initial syncs. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#other-tuning-knobs) - Use connection pooling URIs (maxPoolSize, socketTimeoutMS) tuned for your cluster. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#other-tuning-knobs) ## 10. Security — TLS & x.509 - mongosync inherits MongoDB's standard auth. For production: — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#10-security-tls-x509) ## TLS - Use TLS for every connection - both cluster0 and cluster1 URIs should be mongodb+srv with TLS implied, or include tls=true. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#tls) - The mongosync host needs to trust the CA bundle for both clusters. Use the CA file via the URI parameter tlsCAFile=. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#tls) - mongod logs a warning if the presented certificate expires within 30 days - monitor cert expiry on the migration host as part of pre-flight checks. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#tls) ## x.509 auth (recommended for self-managed source ↔ Atlas dest) - Authentication mechanism: MONGODB-X509. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#x509-auth-recommended-for-self-managed-source-atlas-dest) - authSource=$external in the connection URI. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#x509-auth-recommended-for-self-managed-source-atlas-dest) - The DN of the migration host's client certificate must exist as a user in $external on both clusters with sufficient privileges. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#x509-auth-recommended-for-self-managed-source-atlas-dest) ## Required roles - The mongosync user on each cluster needs broad read/write across the synced namespaces plus: — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#required-roles) - On source: read on every synced namespace, plus permission to open change streams. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#required-roles) - On destination: readWrite on every synced namespace, plus index creation, plus the metadata collections mongosync writes to. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#required-roles) - Atlas exposes a built-in role specifically for mongosync (Atlas Admin is sufficient but overpowered - use the documented minimal role set). — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#required-roles) ## Network security - Migration host inside a VPC with private link or VPC peering to both clusters when possible. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#network-security) - Lock the mongosync HTTP API to 127.0.0.1 (default) - it has no built-in auth. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#network-security) - If you must expose the API, front it with a TLS-terminating reverse proxy + auth. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#network-security) ## Quick-reference checklist for a new mongosync migration - Both clusters on MongoDB 6.0+, same major version. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration) - Migration host with >= 8 CPU, >= 24 GB RAM, network access to both. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration) - Source oplog window >= 2-3x expected initial sync duration. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration) - Destination cluster sized to absorb both sync load and post-cutover production load. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration) - TLS + x.509 (or strong password auth) wired up on both URIs. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration) - Balancer disabled on sharded destination. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration) - Users/roles recreated on destination (mongosync does NOT migrate them). — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration) - Config file (not CLI password) - secrets out of ps. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration) - reversible: true and enableUserWriteBlocking: true if rollback is required. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration) - Filters reviewed - includeNamespaces/excludeNamespaces (cannot be changed later). — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration) - loadLevel chosen for destination capacity. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration) - Monitor /api/v1/progress for state + lagTimeSeconds. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration) - Watch source oplog window vs sync ETA. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration) - Run migration-verifier in parallel for sharded or high-mutation workloads. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration) - Quiesce source writes. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration) - POST /commit, wait for COMMITTED. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration) - Verify counts/hashes on destination. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration) - Flip app connection strings. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration) - Keep mongosync available for reverse until you're confident in the destination. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration) ## Sources - Mongosync - MongoDB Docs (current) — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) - mongosync Quickstart — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) - mongosync Configuration Reference — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) - mongosync Binary Reference — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) - start API endpoint — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) - resume API endpoint — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) - mongosync States — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) - Filtered Sync — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) - Regular Expressions in Filters — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) - Verify Data Transfer — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) - Verify with Hash Comparison — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) - Verify with Migration Verifier — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) - migration-verifier (mongodb-labs) — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) - oplog Sizing — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) - Reverse Sync Direction — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) - Finalize Cutover Process — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) - Sync Sharded Clusters — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) - Atlas Live Migration vs Mongosync — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) - Mongosync product page — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) - Mongosync FAQ — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) - X.509 Client Authentication on Self-Managed MongoDB — [source](https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources) ## Where this helps - Migrating a self-managed MongoDB cluster into Atlas, or between two Atlas clusters or regions, with sub-minute cutover downtime instead of a dump-and-restore maintenance window. — [source](https://llms-explorer.com/tree/mongosync/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Tenant consolidation or namespace renaming during migration, using namespaceRemap to land collections under different destination database or collection names. — [source](https://llms-explorer.com/tree/mongosync/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Cross-major-version or filtered migrations covering only specific databases or collections, where Atlas Live Migration's one-click flow doesn't offer enough control. — [source](https://llms-explorer.com/tree/mongosync/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Setting up long-lived active-passive or disaster-recovery replication between two clusters via Cluster-to-Cluster Sync, which runs the same mongosync engine configured to never reach COMMITTED. — [source](https://llms-explorer.com/tree/mongosync/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* ## Project ideas - Build a migration pre-flight checker that validates oplog window size (2-3x the expected initial sync duration), driver/version compatibility, and that reversible and enableUserWriteBlocking are both set before calling /api/v1/start. — [source](https://llms-explorer.com/tree/mongosync/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Build a cutover runbook automation that polls /api/v1/progress for lagTimeSeconds, quiesces application writes once lag is sub-second, calls /api/v1/commit, and waits for the COMMITTED state before flipping connection strings. — [source](https://llms-explorer.com/tree/mongosync/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Set up a parallel migration-verifier run alongside a sharded or heavily-mutated mongosync migration, since the embedded verifier and dbHash comparison aren't sufficient for that shape of workload. — [source](https://llms-explorer.com/tree/mongosync/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Build a per-shard mongosync orchestrator for a sharded-to-sharded migration, coordinating one mongosync instance per source shard against a shared destination URI. — [source](https://llms-explorer.com/tree/mongosync/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* ## Antipatterns - Passing credentials as CLI flags instead of using a config file: CLI passwords are visible to ps, top, and audit logs. — [source](https://llms-explorer.com/tree/mongosync/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Leaving the sharded destination's balancer enabled during migration: it fights with mongosync's chunk placement and can cause chunk-move-vs-CDC races that inflate the migration window. — [source](https://llms-explorer.com/tree/mongosync/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Relying on document-count verification for a workload with updates, not just inserts: count comparison can't detect document drift and will report a clean migration even when data has diverged. — [source](https://llms-explorer.com/tree/mongosync/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Writing directly to the destination cluster while a sync is running without enableUserWriteBlocking: this corrupts the migration since mongosync doesn't repair manual destination drift, forcing a restart from scratch. — [source](https://llms-explorer.com/tree/mongosync/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* ## Known issues - mongosync never migrates users, roles, or system-database internals; they must be recreated manually on the destination before cutover. — [source](https://llms-explorer.com/tree/mongosync/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - If un-applied change-stream operations age out of the source oplog (ChangeStreamHistoryLost), the sync cannot resume, and the only recovery is dropping the destination collections and starting over. — [source](https://llms-explorer.com/tree/mongosync/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Sync filters (includeNamespaces/excludeNamespaces) are immutable once a sync is running; changing them requires stopping mongosync, cleaning up the destination, and starting a new sync. — [source](https://llms-explorer.com/tree/mongosync/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - The dbHash MD5 verification method locks the cluster for its duration and isn't available on sharded clusters at all, which limits it to smaller replica-set migrations with a maintenance window. — [source](https://llms-explorer.com/tree/mongosync/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* ## Context files - [mongosync](https://llms-explorer.com/downloads/sources/mdb-context-hub/mongosync.md)