When and How MongoDB Balancer Migrates Chunks in a Sharded Cluster

Why Chunk Migration Is Needed

MongoDB sharding may require chunk migration in three main situations: (1) uneven chunk distribution across shards, prompting automatic load‑balancing; (2) removal of a shard via the removeShard command, which marks its chunks for migration; and (3) use of shard tags to direct specific key ranges to designated shards.

Who Performs the Migration

Since version 3.2, each mongos runs a background Balancer task that continuously evaluates the three scenarios. When migration is required, the Balancer issues moveChunk commands to the source shard. Users can also invoke moveChunk manually to trigger migrations.

How the Balancer Works

Only one Balancer may act at a time to avoid conflicts. Before starting, a Balancer attempts to acquire a lock stored as a special document in config.locks on the config server, using a findAndModify operation that sets the state field. The Balancer that wins the lock proceeds; others wait and retry.

Migration Steps

Step 1: Retrieve Chunk Distribution Collect metadata about each shard (including whether it is in draining state) and obtain the current chunk layout for the target collection.

Gather tag information associated with the collection.

Step 2: Check for Required Chunk Splits If the collection defines tag ranges, the Balancer verifies whether any existing chunks intersect those ranges. When an intersection is found, the chunk is split at the range's lower bound. Example:

Range (20, 80) with tag "tag0" overlaps chunk (0, 100); split at 20 → chunks (0,20) and (20,100).

The split prepares mismatched chunks for later migration.

Step 3: Migrate Chunks from Draining Shards When a shard is marked as draining (after removeShard ), the Balancer selects the shard with the fewest chunks as the destination and creates migration tasks for all chunks on the draining shard.

Step 4: Migrate Tag‑Mismatched Chunks After any necessary splits, the Balancer examines each chunk's shard tag versus the chunk's tag range. If they differ, a migration task moves the chunk to a shard whose tag matches the range.

Step 5: Load‑Balancing Migration The Balancer also compares the number of chunks on each shard. If the difference exceeds a configured threshold (e.g., when total chunks < 20 and the difference ≥ 2), it creates a task to move a chunk from the most‑loaded shard to the least‑loaded shard.

Step 6: Execute Migration Tasks All tasks generated in Steps 3–5 are executed sequentially. Disabling the Balancer disables both automatic load‑balancing and essential migrations for draining shards or tag‑based routing, so it should be turned off only with caution.

Example of Shard Tag Configuration

mongos> sh.addShardTag("shard-hz", "hangzhou")
mongos> sh.addShardTag("shard-sh", "shanghai")
mongos> sh.addTagRange("shtest.coll", {x: 1}, {x: 1000}, "hangzhou")
mongos> sh.addTagRange("shtest.coll", {x: 2000}, {x: 5000}, "shanghai")

With these tags, documents where x is in [1,1000) reside on shard-hz, and those in [2000,5000) reside on shard-sh.