Balancer control for long reads (balancing window, configureCollectionBalancing, _waitForDelete)
Parent: Long-running secondary reads in sharded clusters · Published reference · snapshot 2026-10-31
↓ Facts as markdownall context files
Source-anchored research for Balancer control for long reads (balancing window, configureCollectionBalancing, _waitForDelete). Run status: COMPLETED.
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.
How it works
- A balancing window limits when the balancer may migrate chunks. Configure daily activeWindow start/stop values as HH:MM in config.settings; ensure the balancer is enabled and the permitted interval is large enough to handle the accumulated redistribution work. (low confidence) [source]
How-to and procedures
- Use db.adminCommand({configureCollectionBalancing: "db.collection", enableBalancing: false}) to disable balancing for one collection. The command dates to 5.3, but its enableBalancing field was added in 8.1; do not infer field availability from the command introduction version. (medium confidence) [source]
Problems, failure modes and limitations
- In a March 2022 first-person report for MongoDB 4.4.13, an operator found shard draining slow despite investigating _secondaryThrottle and _waitForDelete, then attributed more than 15 minutes per chunk to cleanup waiting. Treat this as a historical troubleshooting observation, not a current-version migration latency guarantee. (low confidence) [source]
- Balancer windows and configureCollectionBalancing with enableBalancing:false can limit exposure to new automatic migrations; these controls do not establish that cleanup from earlier migrations has finished (the latter is an inference from the documented migration/cleanup sequence). (medium confidence) [source]
- For MongoDB 8.2 and later, the documented default behavior terminates affected secondary reads before orphan deletion; disabling termination can instead allow missing documents. This changes how the older missing-document warning should be interpreted. (medium confidence) (verified as of 2026-10-14) [source]
Comparisons and alternatives
- The balancer normally starts its next migration without waiting for the previous migration delete phase. Setting _waitForDelete to true makes deletion block the next migration; this controls migration sequencing, rather than reserving a safe interval for long reads. (high confidence) [source]
- Extended balancing pauses can leave shards unbalanced and degrade performance. Migration itself also consumes resources, so an operational plan must allow balancing to recover rather than leaving it disabled indefinitely. (high confidence) [source]
Facts and statements
- MongoDB documents disabling the balancer and avoiding manual migrations as an alternative for protecting long-running secondary reads from migration-triggered termination. Leaving balancing disabled for extended periods can produce shard imbalance and degrade performance. (high confidence) [source]
- Window times use the config-server replica-set primary time zone for self-managed deployments and UTC for Atlas. The cached current manual also describes activeWindowDOW taking precedence over activeWindow; check the target server version before using that newer syntax. (low confidence) (verified as of 2026-10-30) [source]
- Stopping balancing does not interrupt a migration already in progress. Global sh.stopBalancer() lets the in-progress migration finish; disabling balancing on a collection also leaves in-progress migrations running. Verify migration inactivity before treating a read interval as free of migration work. (high confidence) [source]
- _waitForDelete: true bypasses orphanCleanupDelaySecs before range deletion. Current documentation warns that secondary reads may terminate during that deletion; the historical correctness bug also identifies this option as exposing secondary reads to missing migrated documents. Do not use it as long-read protection. (high confidence) [source]
- SERVER-29405 records the original motivation for delaying range deletion: queries still running on secondaries may need the donated range. SERVER-87673 later demonstrates that such a fixed delay does not protect queries that outlive it. These historical issues explain why migration scheduling and read completion must be considered together. (medium confidence) [source]
- Percona describes collection-level AutoMerger control through configureCollectionBalancing.enableAutoMerger and scheduling AutoMerger within a balancer window. This is a separate control from configureCollectionBalancing.enableBalancing; disabling automatic merging alone does not express a request to disable collection balancing. (medium confidence) [source]
Children
- No children recorded.