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.

Connect to any mongos in the cluster using the mongo shell.
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:

Connect to any mongos in the cluster using the mongo shell.
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.
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 that does not have the sh.stopBalancer() or sh.setBalancerState() helpers, issue the following command from the config database:

db.settings.update( { _id: "balancer" }, { $set : { stopped: true } } ,  { upsert: true } )

Enable the Balancer¶

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

Connect to any mongos in the cluster using the mongo shell.
Issue one of the following operations to enable the balancer:

From the mongo shell, issue:
```
sh.setBalancerState(true)
```
From a driver that does not have the sh.startBalancer() helper, issue the following from the config database:
```
db.settings.update( { _id: "balancer" }, { $set : { stopped: false } } , { upsert: true } )
```

Disable Balancing During Backups¶

If MongoDB migrates a chunk during a backup, you can end with an inconsistent snapshot of your sharded cluster. Never run a backup while the balancer is active. To ensure that the balancer is inactive during your backup operation:

Set the balancing window so that the balancer is inactive during the backup. Ensure that the backup can complete while you have the balancer disabled.
manually disable the balancer for the duration of the backup procedure.

If you turn the balancer off while it is in the middle of a balancing round, the shut down is not instantaneous. The balancer completes the chunk move in-progress and then ceases all further balancing rounds.

Before starting a backup operation, confirm that the balancer is not active. You can use the following command to determine if the balancer is active:

!sh.getBalancerState() && !sh.isBalancerRunning()

When the backup procedure is complete you can reactivate the balancer process.

Disable Balancing on a Collection¶

You can disable balancing for a specific collection with the sh.disableBalancing() method. You may want to disable the balancer for a specific collection to support maintenance operations or atypical workloads, for example, during data ingestions or data exports.

When you disable balancing on a collection, MongoDB will not interrupt in progress migrations.

To disable balancing on a collection, connect to a mongos with the mongo shell and call the sh.disableBalancing() method.

For example:

sh.disableBalancing("students.grades")

The sh.disableBalancing() method accepts as its parameter the full namespace of the collection.

Enable Balancing on a Collection¶

You can enable balancing for a specific collection with the sh.enableBalancing() method.

When you enable balancing for a collection, MongoDB will not immediately begin balancing data. However, if the data in your sharded collection is not balanced, MongoDB will be able to begin distributing the data more evenly.

To enable balancing on a collection, connect to a mongos with the mongo shell and call the sh.enableBalancing() method.

For example:

sh.enableBalancing("students.grades")

The sh.enableBalancing() method accepts as its parameter the full namespace of the collection.

Confirm Balancing is Enabled or Disabled¶

To confirm whether balancing for a collection is enabled or disabled, query the collections collection in the config database for the collection namespace and check the noBalance field. For example:

db.getSiblingDB("config").collections.findOne({_id : "students.grades"}).noBalance;

This operation will return a null error, true, false, or no output:

A null error indicates the collection namespace is incorrect.
If the result is true, balancing is disabled.
If the result is false, balancing is enabled currently but has been disabled in the past for the collection. Balancing of this collection will begin the next time the balancer runs.
If the operation returns no output, balancing is enabled currently and has never been disabled in the past for this collection. Balancing of this collection will begin the next time the balancer runs.

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

Change Replication Behavior for Chunk Migration¶

Secondary Throttle¶

During chunk migration (initiated either automatically via the balancer or manually via moveChunk command), the _secondaryThrottle value determines when the balancer proceeds with the next document in the chunk:

If true, each document move during chunk migration propagates to at least one secondary before the balancer proceeds with the next document. This is equivalent to a write concern of { w: 2 }.

Note

The writeConcern field in the balancer configuration document allows you to specify a different write concern semantics with the _secondaryThrottle option.
If false, the balancer does not wait for replication to a secondary and instead continues with the next document.

Starting in MongoDB 3.4, for WiredTiger, the default value _secondaryThrottle is false for all chunk migrations.

The default value remains true for MMAPv1.

To change the balancer’s _secondaryThrottle and writeConcern values, connect to a mongos instance and directly update the _secondaryThrottle value in the settings collection of the config database. For example, from a mongo shell connected to a mongos, issue the following command:

use config
db.settings.update(
   { "_id" : "balancer" },
   { $set : { "_secondaryThrottle" : true ,
              "writeConcern": { "w": "majority" } } },
   { upsert : true }
)

The effects of changing the _secondaryThrottle and writeConcern value may not be immediate. To ensure an immediate effect, stop and restart the balancer to enable the selected value of _secondaryThrottle. See Manage Sharded Cluster Balancer for details.

For more information on the replication behavior during various steps of chunk migration, see Chunk Migration and Replication.

Wait for Delete¶

The _waitForDelete setting of the balancer and the moveChunk command affects how the balancer migrates multiple chunks from a shard. By default, the balancer does not wait for the on-going migration’s delete phase to complete before starting the next chunk migration. To have the delete phase block the start of the next chunk migration, you can set the _waitForDelete to true.

For details on chunk migration, see Chunk Migration. For details on the chunk migration queuing behavior, see Asynchronous Chunk Migration Cleanup.

The _waitForDelete is generally for internal testing purposes. To change the balancer’s _waitForDelete value:

Connect to a mongos instance.

Update the _waitForDelete value in the settings collection of the config database. For example:

use config
db.settings.update(
   { "_id" : "balancer" },
   { $set : { "_waitForDelete" : true } },
   { upsert : true }
)

Once set to true, to revert to the default behavior:

Connect to a mongos instance.

Update or unset the _waitForDelete field in the settings collection of the config database:

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

Change the Maximum Storage Size for a Given Shard¶

By default shards have no constraints in storage size. However, you can set a maximum storage size for a given shard in the sharded cluster. When selecting potential destination shards, the balancer ignores shards where a migration would exceed the configured maximum storage size.

The shards collection in the config database stores configuration data related to shards.

{ "_id" : "shard0000", "host" : "shard1.example.com:27100" }
{ "_id" : "shard0001", "host" : "shard2.example.com:27200" }

To limit the storage size for a given shard, use the db.collection.updateOne() method with the $set operator to create the maxSize field and assign it an integer value. The maxSize field represents the maximum storage size for the shard in megabytes.

The following operation sets a maximum size on a shard of 1024 megabytes:

config = db.getSiblingDB("config")
config.shards.updateOne( { "_id" : "<shard>"}, { $set : { "maxSize" : 1024 } } )

This value includes the mapped size of all data files on the shard, including the local and admin databases.

By default, maxSize is not specified, allowing shards to consume the total amount of available space on their machines if necessary.

You can also set maxSize when adding a shard.

To set maxSize when adding a shard, set the addShard command’s maxSize parameter to the maximum size in megabytes. The following command run in the mongo shell adds a shard with a maximum size of 125 megabytes:

config = db.getSiblingDB("config")
config.runCommand( { addshard : "example.net:34008", maxSize : 125 } )

← Sharded Cluster Balancer Migrate Chunks in a Sharded Cluster →

Manage Sharded Cluster Balancer¶

Check the Balancer State¶

Check if Balancer is Running¶

Configure Default Chunk Size¶

Schedule the Balancing Window¶

Connect to mongos using the mongo shell.¶

Switch to the Config Database.¶

Ensure that the balancer is not stopped.¶

Modify the balancer’s window.¶

Remove a Balancing Window Schedule¶

Disable the Balancer¶

Enable the Balancer¶

Disable Balancing During Backups¶

Disable Balancing on a Collection¶

Enable Balancing on a Collection¶

Confirm Balancing is Enabled or Disabled¶

Change Replication Behavior for Chunk Migration¶

Secondary Throttle¶

Wait for Delete¶

Change the Maximum Storage Size for a Given Shard¶

Connect to `mongos` using the `mongo` shell.¶

Ensure that the balancer is not `stopped`.¶