During a MongoDB chunk migration, what happens on the donor and recipient shards, and how does live traffic feel it?

## The phases of a range migration 1. The balancer, on the config-server primary, sends `moveRange` (historically `moveChunk`) to the **donor** shard's primary. 2. The donor tells the **recipient** to start receiving. The recipient builds any indexes it is missing for that collection. 3. The recipient **clones** the documents whose shard-key values fall in the range. The donor keeps serving reads and writes normally throughout. 4. Writes that land in the range while cloning is in progress are tracked and shipped to the recipient in a catch-up phase, repeated until the recipient is nearly in sync. 5. The donor enters the **critical section**: incoming writes to that range are blocked and queued, the last changes are transferred, and the ownership change is committed to the config servers. 6. Routers and shards that still believe the old owner holds the range get a stale-config error, refresh their routing table, and retry. 7. The documents remain on the donor as **orphans** until the range deleter removes them — after any open cursors on the range finish, and after `orphanCleanupDelaySecs` (default 900 seconds). Pending deletions are tracked in each shard's own `config.rangeDeletions` collection. ## What the workload actually experiences **A short write stall on that range.** Only step 5 blocks writes, and only for documents in the range being moved. It is normally sub-second, but it is real: on a hot range under heavy write load, or when the donor's primary is struggling, the queued writes show up as a latency spike. **Read and write amplification on both shards.** The donor reads the range out; the recipient writes it in. Those recipient writes go through its oplog and replicate to its secondaries, so a migration inflates oplog volume and can push secondaries behind. The donor's later range deletion is another burst of write work and IOPS. **Cache churn.** Scanning a range on the donor and inserting it on the recipient evicts hot working-set pages on both sides, so query latency can degrade for minutes after a big move even though nothing is blocked. **Metadata refresh chatter.** Every router that had the old ownership cached takes a stale-config error and refreshes. With many `mongos` processes and continuous migrations, this is visible though rarely dominant. **Concurrency limits.** A shard participates in at most one migration at a time, so a cluster of *n* shards runs at most about *n*/2 migrations concurrently. That is a hard ceiling on how fast a cluster can rebalance, and it is why adding a shard to a very large cluster can take days to fill. ## Controlling when and how hard it hits **Balancer active window.** The most common control: confine migrations to a quiet period by upserting an `activeWindow` into the balancer settings document. The balancer will not *start* new migrations outside the window. ```javascript use config db.settings.updateOne( { _id: "balancer" }, { $set: { activeWindow: { start: "01:00", stop: "05:00" } } }, { upsert: true } ) ``` **Per-collection control.** `sh.disableBalancing("app.events")` stops migrations for one collection while leaving the rest of the cluster balanced — useful during a bulk load or a heavy backfill. `sh.enableBalancing()` restores it. **Cluster-wide stop.** `sh.stopBalancer()` and `sh.startBalancer()`, with `sh.isBalancerRunning()` to confirm the current round has finished before you begin maintenance such as a backup. **Secondary throttling.** The `_secondaryThrottle` setting makes each migration write on the recipient wait for a write concern rather than firing as fast as the disks allow, trading migration speed for replication headroom. `_waitForDelete` makes the balancer wait for the donor's range deletion to finish before starting the next migration, which keeps the orphan backlog from growing. ## Diagnosing migration pain Look at `config.changelog` for `moveChunk.start` / `moveChunk.commit` entries to see migration volume and duration. Check each shard's `config.rangeDeletions` for a growing cleanup backlog. Correlate replication lag on the recipient's secondaries with migration timestamps. If latency spikes line up with migrations, the fix is scheduling and throttling — not turning the balancer off permanently, which just lets skew accumulate until the eventual rebalance is far more painful.