mongosync

Parent: MongoDB Expert Knowledge · Published reference · snapshot 2026-09-08 · skill mongodb-operations-expert/references/mongosync.md

↓ Facts as markdown all context files

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)

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.

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. [archived 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: [archived 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. [archived 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. [archived 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. [archived 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. [archived 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. [archived 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. [archived 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). [archived 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. [archived 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: [archived 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. [archived 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. [archived 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. [archived 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: [archived 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. [archived 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. [archived 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). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#basic-filters]
This includes only sales.EMEA, sales.APAC, and every collection under marketing. [archived 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: [archived 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. [archived 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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#filter-immutability]

Items mongosync never replicates

local, config, admin database internals (system collections). [archived 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. [archived 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). [archived 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. [archived 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). [archived 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. [archived 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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#resume-rules]

When you cannot resume

Long pause + small source oplog → window exhausted. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#when-you-cannot-resume]
Destination collection dropped/altered while mongosync was paused. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#when-you-cannot-resume]
Filter change attempted (filters are immutable - see Section 3). [archived 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. [archived 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. [archived 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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#51-embedded-verifier-default-replica-sets]
No locks, no extra downtime. [archived 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. [archived 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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#52-hash-comparison-dbhash-md5]
Not available on sharded clusters. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#52-hash-comparison-dbhash-md5]
Slow on large collections; precise. [archived 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. [archived 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. [archived 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. [archived 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. [archived 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. [archived 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. [archived 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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#oplog-window-exhaustion]
- Initial sync taking too long on a high-write source. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#oplog-window-exhaustion]
- Long pause while CDC is suspended. [archived 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). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#oplog-window-exhaustion]
- Pre-sync: increase oplogSizeMB (or replSetResizeOplog with minRetentionHours > expected sync duration). [archived 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. [archived 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. [archived 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. [archived 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. [archived 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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#schema-drift]

Stalled progress

Check /api/v1/progress for lagTimeSeconds. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#stalled-progress]
Check destination index builds - slow index builds back up CDC. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#stalled-progress]
Check destination CPU/IOPS - loadLevel may be too high. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#stalled-progress]

Cannot reverse / reverse refused

reversible was not true at start. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cannot-reverse-reverse-refused]
enableUserWriteBlocking was not true. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cannot-reverse-reverse-refused]
Source and destination MongoDB major versions differ. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cannot-reverse-reverse-refused]
Topologies differ (e.g., replica set vs sharded). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cannot-reverse-reverse-refused]
Destination oplog rolled past the moment mongosync went canWrite=true. [archived 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: [archived 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. [archived 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). [archived 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). [archived 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). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cutover-process]
Quiesce application writes on the source. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cutover-process]
Call POST /api/v1/commit. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cutover-process]
mongosync moves to COMMITTING - drains remaining change events. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cutover-process]
mongosync reaches COMMITTED - final state. The destination is now authoritative. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#cutover-process]
Flip application connection strings to the destination cluster. [archived 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. [archived 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: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#reverse-sync-rollback]
- reversible:true set at original start. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#reverse-sync-rollback]
- enableUserWriteBlocking:true set at original start. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#reverse-sync-rollback]
- Same major version on both clusters. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#reverse-sync-rollback]
- Same topology (replica set ↔ replica set, or sharded ↔ sharded). [archived 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. [archived 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. [archived 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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#state-machine-summary]

loadLevel

1–4 scale. Default 3. [archived 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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#loadlevel]
Can be changed mid-sync by editing the config file and signaling mongosync. [archived 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. [archived 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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#index-builds]
Keep total concurrent-index-build memory under 20% of destination RAM. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#index-builds]
mongosync defers some index builds until after initial sync to avoid contention. [archived 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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#balancer]

Other tuning knobs

Increase migration host CPU/RAM if CDC lag grows. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#other-tuning-knobs]
Increase source oplog window proactively for long initial syncs. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#other-tuning-knobs]
Use connection pooling URIs (maxPoolSize, socketTimeoutMS) tuned for your cluster. [archived 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: [archived 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. [archived 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=. [archived 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. [archived 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. [archived 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. [archived 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. [archived 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: [archived 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. [archived 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. [archived 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). [archived 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. [archived 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. [archived 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. [archived 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. [archived 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. [archived 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. [archived 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. [archived 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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration]
Balancer disabled on sharded destination. [archived 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). [archived 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. [archived 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. [archived 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). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration]
loadLevel chosen for destination capacity. [archived 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. [archived 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. [archived 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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration]
Quiesce source writes. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration]
POST /commit, wait for COMMITTED. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration]
Verify counts/hashes on destination. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration]
Flip app connection strings. [archived 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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#quick-reference-checklist-for-a-new-mongosync-migration]

Sources

Mongosync - MongoDB Docs (current) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources]
mongosync Quickstart [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources]
mongosync Configuration Reference [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources]
mongosync Binary Reference [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources]
start API endpoint [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources]
resume API endpoint [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources]
mongosync States [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources]
Filtered Sync [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources]
Regular Expressions in Filters [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources]
Verify Data Transfer [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources]
Verify with Hash Comparison [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources]
Verify with Migration Verifier [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources]
migration-verifier (mongodb-labs) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources]
oplog Sizing [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources]
Reverse Sync Direction [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources]
Finalize Cutover Process [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources]
Sync Sharded Clusters [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources]
Atlas Live Migration vs Mongosync [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources]
Mongosync product page [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources]
Mongosync FAQ [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongosync/#sources]
X.509 Client Authentication on Self-Managed MongoDB [archived 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] — 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] — 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] — 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] — 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] — 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] — 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] — 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] — 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] — 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] — 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] — 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] — 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] — 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] — 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] — 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] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Children

initial-sync-and-cdc (frontier, viability 4.00 / 5)
namespace-filtering (frontier, viability 4.00 / 5)
resume-and-checkpoint (frontier, viability 3.42 / 5)
verification-modes (frontier, viability 4.30 / 5)
reverse-sync-cutover (frontier, viability 4.00 / 5)
oplog-window-sizing (frontier, viability 4.00 / 5)
atlas-live-migration-comparison (frontier, viability 3.83 / 5)
mongosync-state-machine (frontier, viability 3.88 / 5)
loadlevel-tuning (frontier, viability 3.80 / 5)
tls-x509-auth (frontier, viability 3.42 / 5)

Frontier under this node: atlas-live-migration-comparison (3.83), initial-sync-and-cdc (4.00), loadlevel-tuning (3.80), mongosync-state-machine (3.88), namespace-filtering (4.00), oplog-window-sizing (4.00), resume-and-checkpoint (3.42), reverse-sync-cutover (4.00), tls-x509-auth (3.42), verification-modes (4.30)

← the whole tree · 3D view· how to read this page