Docs4dev
Docs
mongodb / v3.6 / reference / tutorial-manage-sharded-cluster-balancer.html

Manage Sharded Cluster Balancer

On this page

Changed in version 3.4: The balancer process has moved from the mongos instances to the primary member of the config server replica set.

This page describes common administrative procedures related to balancing. For an introduction to balancing, see Sharded Cluster Balancer. For lower level information on balancing, see Cluster Balancer.

Important

Use the version of the mongo shell that corresponds to the version of the sharded cluster. For example, do not use a 3.2 or earlier version of mongo shell against the 3.4 sharded cluster.

Check the Balancer State

sh.getBalancerState() checks if the balancer is enabled (i.e. that the balancer is permitted to run). sh.getBalancerState() does not check if the balancer is actively balancing chunks.

To see if the balancer is enabled in your sharded cluster, issue the following command, which returns a boolean:

sh.getBalancerState()

New in version 3.0.0: You can also see if the balancer is enabled using sh.status(). The currently-enabled field indicates whether the balancer is enabled, while the currently-running field indicates if the balancer is currently running.

Check if Balancer is Running

To see if the balancer process is active in your cluster:

Important

Use the version of the mongo shell that corresponds to the version of the sharded cluster. For example, do not use a 3.2 or earlier version of mongo shell against the 3.4 sharded cluster.

  1. Connect to any mongos in the cluster using the mongo shell.

  2. Use the following operation to determine if the balancer is running:

    sh.isBalancerRunning()

Configure Default Chunk Size

The default chunk size for a sharded cluster is 64 megabytes. In most situations, the default size is appropriate for splitting and migrating chunks. For information on how chunk size affects deployments, see details, see Chunk Size.

Changing the default chunk size affects chunks that are processes during migrations and auto-splits but does not retroactively affect all chunks.

To configure default chunk size, see Modify Chunk Size in a Sharded Cluster.

Schedule the Balancing Window

In some situations, particularly when your data set grows slowly and a migration can impact performance, it is useful to ensure that the balancer is active only at certain times. The following procedure specifies the activeWindow, which is the timeframe during which the balancer will be able to migrate chunks:

1

Connect to mongos using the mongo shell.

You can connect to any mongos in the cluster.

2

Switch to the Config Database.

Issue the following command to switch to the config database.

use config
3

Ensure that the balancer is not stopped.

The balancer will not activate in the stopped state. To ensure that the balancer is not stopped, use sh.setBalancerState(), as in the following:

sh.setBalancerState( true )

The balancer will not start if you are outside of the activeWindow timeframe.

4

Modify the balancer’s window.

Set the activeWindow using update(), as in the following:

db.settings.update(
   { _id: "balancer" },
   { $set: { activeWindow : { start : "<start-time>", stop : "<stop-time>" } } },
   { upsert: true }
)

Replace <start-time> and <end-time> with time values using two digit hour and minute values (i.e. HH:MM) that specify the beginning and end boundaries of the balancing window.

  • For HH values, use hour values ranging from 00 - 23.
  • For MM value, use minute values ranging from 00 - 59.

MongoDB evaluates the start and stop times relative to the time zone of the member which is serving as a primary in the config server replica set.

Note

The balancer window must be sufficient to complete the migration of all data inserted during the day.

As data insert rates can change based on activity and usage patterns, it is important to ensure that the balancing window you select will be sufficient to support the needs of your deployment.

Do not use the sh.startBalancer() method when you have set an activeWindow.

Remove a Balancing Window Schedule

If you have set the balancing window and wish to remove the schedule so that the balancer is always running, use $unset to clear the activeWindow, as in the following:

use config
db.settings.update({ _id : "balancer" }, { $unset : { activeWindow : true } })

Disable the Balancer

By default, the balancer may run at any time and only moves chunks as needed. To disable the balancer for a short period of time and prevent all migration, use the following procedure:

  1. Connect to any mongos in the cluster using the mongo shell.

  2. Issue the following operation to disable the balancer:

    sh.stopBalancer()

    If a migration is in progress, the system will complete the in-progress migration before stopping.

  3. To verify that the balancer will not start, issue the following command, which returns false if the balancer is disabled:

    sh.getBalancerState()

    Optionally, to verify no migrations are in progress after disabling, issue the following operation in the mongo shell:

    use config
while( sh.isBalancerRunning() ) {
          print("waiting...");
          sleep(1000);
}

Note

To disable the balancer from a driver, use the balancerStop command against the admin database, as in the following:

db.adminCommand( { balancerStop: 1 } )

Enable the Balancer

Use this procedure if you have disabled the balancer and are ready to re-enable it:

  1. Connect to any mongos in the cluster using the mongo shell.

  2. Issue one of the following operations to enable the balancer:

    From the mongo shell, issue:

    sh.setBalancerState(true)

    Note

    To enable the balancer from a driver, use the balancerStart command against the admin database, as in the following: