- Sharding >
- Sharded Cluster Tutorials >
- Sharded Cluster Maintenance Tutorials >
- Manage Sharded Cluster Balancer
Manage Sharded Cluster Balancer¶
On this page
This page describes common administrative procedures related to balancing. For an introduction to balancing, see Sharded Collection Balancing. For lower level information on balancing, see Cluster Balancer.
Check the Balancer State¶
The following command checks if the balancer is enabled (i.e. that the balancer is allowed to run). The command does not check if the balancer is active (i.e. if it is actively balancing chunks).
To see if the balancer is enabled in your cluster, issue the following command, which returns a boolean:
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 the Balancer Lock¶
To see if the balancer process is active in your cluster, do the following:
Issue the following command to switch to the Config Database:
Use the following query to return the balancer lock:
When this command returns, you will see output like the following:
This output confirms that:
Schedule the Balancing Window¶
In some situations, particularly when your data set grows slowly and a migration can impact performance, it’s useful to be able to ensure that the balancer is active only at certain times. Use the following procedure to specify a window during which the balancer will be able to migrate chunks:
Issue the following command to switch to the Config Database:
Issue the following operation to ensure the balancer is not in the
stopped
state:The balancer will not activate if in the
stopped
state or outside theactiveWindow
timeframe.Use an operation modeled on the following
update()
operation to modify the balancer’s window: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 from00
-23
. - For
MM
value, use minute values ranging from00
-59
.
The start and stop times will be evaluated relative to the time zone of each individual
mongos
instance in the sharded cluster. If yourmongos
instances are physically located in different time zones, use a common time zone (e.g. GMT) to ensure that the balancer window is interpreted correctly.For instance, running the following will force the balancer to run between 11PM and 6AM local time only:
- For
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, issue the following sequence of operations:
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:
Issue the following operation to disable the balancer:
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:Optionally, to verify no migrations are in progress after disabling, issue the following operation in the
mongo
shell:
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:
Enable the Balancer¶
Use this procedure if you have disabled the balancer and are ready to re-enable it:
Issue one of the following operations to enable the balancer:
From the
mongo
shell, issue:From a driver that does not have the
sh.startBalancer()
helper, issue the following from theconfig
database:
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:
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:
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:
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:
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.