sh.setBalancerState.txt

=====================
sh.setBalancerState()
=====================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

Description
-----------

.. method:: sh.setBalancerState(state)

   Enables or disables the :term:`balancer`.

   .. include:: /includes/autosplit-no-operation.rst

   In MongoDB versions earlier than 6.0.3,
   :method:`sh.setBalancerState()` also enables auto-splitting if
   enabling the balancer and disables auto-splitting if disabling the
   balancer.

   Use :method:`sh.getBalancerState()` to determine if the balancer is
   currently enabled or disabled and :method:`sh.isBalancerRunning()`
   to check its current state.

   .. |dbcommand| replace:: :dbcommand:`balancerStart` and
      :dbcommand:`balancerStop` commands
   .. include:: /includes/fact-mongosh-shell-method-alt.rst


   .. important::

      You can only run :method:`sh.setBalancerState()` on a
      :binary:`~bin.mongos` instance. :method:`sh.setBalancerState()`
      errors if run on :binary:`~bin.mongod` instance.

   The :method:`sh.setBalancerState()` method has the following
   parameter:


   .. list-table::
      :header-rows: 1
      :widths: 20 20 80
   
      * - Parameter
   
        - Type
   
        - Description
   
      * - ``state``
   
        - boolean
   
        - Set this to ``true`` to enable the balancer and ``false`` to
          disable it.

          .. include:: /includes/sharding/disable-balancer-warning.rst

Compatibility
-------------

This method is available in deployments hosted in the following environments: 

.. include:: /includes/fact-environments-atlas-only.rst

.. include:: /includes/fact-environments-atlas-support-no-free.rst

.. include:: /includes/fact-environments-onprem-only.rst

Learn More
----------

- :method:`sh.enableBalancing()`
- :method:`sh.disableBalancing()`
- :method:`sh.getBalancerState()`
- :method:`sh.isBalancerRunning()`
- :method:`sh.startBalancer()`
- :method:`sh.stopBalancer()`
- :method:`sh.waitForBalancer()`
- :method:`sh.waitForBalancerOff()`