Prior to v3.4, the start/stopBalancer shell scripts were using the config.settings section plus the state of the balancer lock in order to set the balancer state.

In sharding 3.4, the balancer is running on the CSRS primary and it permanently holds the balancer lock in order to prevent any legacy 3.2 mongos instance from attempting to do balancing. Since the old shell scripts for start/stopBalancer relied on the state of the balancer lock to determine whether it is running, with this change these old scripts no longer work.

The new way to interact with the balancer in 3.4 is through the startBalancer/stopBalancer/balancerStatus commands. The way they work is:

• startBalancer - starts the balancer thread, but does not wait for a balancer round.
• stopBalancer - waits for any active balancer round to complete and then stops the balancer. No more balancing will occur until startBalancer is called.
• balancerStatus - returns information about the run-time status of the balancer. This information is available on both primary and secondary, but only meaningful when read from the primary:
  • mode (string) - State of the balancer. Can be one of "full" (balancer is active, but not necessarily doing balancing at this moment), "off" (balancer is stopped and will not be doing any chunk movements).
  • inBalancerRound (boolean) - indicates whether the balancer is currently actively moving chunks or sleeping.
  • numBalancerRounds (number) - indicates the number of balancer rounds which have been done since the node was last started. This value is not persisted anywhere, is reset to 0 on node restart and will remain at its last value if the node is not primary or if the balancer is stopped.

Backwards compatibility
This section is about the backwards compatibility of the start/stopBalancer shell scripts.

The 3.4 shell is backwards compatible with sharded clusters, which are running all components on 3.2 or earlier (config, shards and mongos).

The 3.2 and earlier shell is not compatible with 3.4 clusters.

For clusters which are in the process of being upgraded, the following rules apply:

If only the CSRS config server primary has been upgraded to 3.4, but not the shards and mongos, neither the old shell balancer control will work, nor the 3.4 one. In order to be able to control the balancer in this state, a one-off mongos instance needs to be spawned so the balancer control commands are available.