config-database.txt

.. index:: internals; config database
.. index:: sharding; config database
.. _config-database:

===============
Config Database
===============

.. default-domain:: mongodb

The ``config`` database supports :term:`sharded cluster`
operation. See the :doc:`/sharding` section of this manual for full
documentation of sharded clusters.

.. important:: Consider the schema of the ``config`` database
   *internal* and may change between releases of MongoDB. The
   ``config`` database is not a dependable API, and users should not
   write data to the ``config`` database in the course of normal
   operation or maintenance.

.. warning:: Modification of the ``config`` database on a functioning
   system may lead to instability or inconsistent data sets. If you
   must modify the ``config`` database, use :program:`mongodump` to
   create a full backup of the ``config`` database.

To access the ``config`` database, connect to a :program:`mongos`
instance in a sharded cluster, and use the following helper:

.. code-block:: javascript

   use config

You can return a list of the collections, with the following helper:

.. code-block:: javascript

   show collections

Collections
-----------

.. if we add a collection to the config database here, also update the
   list on the sharding-internals page.

.. data:: config

.. data:: config.changelog

   .. include:: /includes/admonition-config-db-is-internal.rst

   The :data:`~config.changelog` collection stores a document for each change to
   the metadata of a sharded collection.

   .. example::

      The following example displays a single record of a chunk split
      from a :data:`~config.changelog` collection:

      .. code-block:: javascript

         {
          "_id" : "<hostname>-<timestamp>-<increment>",
          "server" : "<hostname><:port>",
          "clientAddr" : "127.0.0.1:63381",
          "time" : ISODate("2012-12-11T14:09:21.039Z"),
          "what" : "split",
          "ns" : "<database>.<collection>",
          "details" : {
             "before" : {
                "min" : {
                   "<database>" : { $minKey : 1 }
                },
                "max" : {
                   "<database>" : { $maxKey : 1 }
                },
                "lastmod" : Timestamp(1000, 0),
                "lastmodEpoch" : ObjectId("000000000000000000000000")
             },
             "left" : {
                "min" : {
                   "<database>" : { $minKey : 1 }
                },
                "max" : {
                   "<database>" : "<value>"
                },
                "lastmod" : Timestamp(1000, 1),
                "lastmodEpoch" : ObjectId(<...>)
             },
             "right" : {
                "min" : {
                   "<database>" : "<value>"
                },
                "max" : {
                   "<database>" : { $maxKey : 1 }
                },
                "lastmod" : Timestamp(1000, 2),
                "lastmodEpoch" : ObjectId("<...>")
             }
          }
         }

   Each document in the :data:`~config.changelog` collection contains the
   following fields:

   .. data:: config.changelog._id

      The value of ``changelog._id`` is:
      ``<hostname>-<timestamp>-<increment>``.

   .. data:: config.changelog.server

      The hostname of the server that holds this data.

   .. data:: config.changelog.clientAddr

      A string that holds the address of the client, a
      :program:`mongos` instance that initiates this change.

   .. data:: config.changelog.time

      A :term:`ISODate` timestamp that reflects when the change
      occurred.

   .. data:: config.changelog.what

      Reflects the type of change recorded. Possible values are:

      - ``dropCollection``
      - ``dropCollection.start``
      - ``dropDatabase``
      - ``dropDatabase.start``
      - ``moveChunk.start``
      - ``moveChunk.commit``
      - ``split``
      - ``multi-split``

   .. data:: config.changelog.ns

      Namespace where the change occurred.

   .. data:: config.changelog.details

      A :term:`document` that contains  additional details regarding
      the change. The structure of the :data:`~config.changelog.details`
      document depends on the type of change.

.. data:: config.chunks

   .. include:: /includes/admonition-config-db-is-internal.rst

   The :data:`~config.chunks` collection stores a document for each chunk in
   the cluster.  Consider the following example of a document for a
   chunk named ``records.pets-animal_\"cat\"``:

   .. code-block:: javascript

      {
         "_id" : "mydb.foo-a_\"cat\"",
         "lastmod" : Timestamp(1000, 3),
         "lastmodEpoch" : ObjectId("5078407bd58b175c5c225fdc"),
         "ns" : "mydb.foo",
         "min" : {
               "animal" : "cat"
         },
         "max" : {
               "animal" : "dog"
         },
         "shard" : "shard0004"
      }

   These documents store the range of values for the shard key that
   describe the chunk in the ``min`` and ``max`` fields. Additionally
   the ``shard`` field identifies the shard in the cluster that "owns"
   the chunk.

.. data:: config.collections

   .. include:: /includes/admonition-config-db-is-internal.rst

   The :data:`~config.collections` collection stores a document for each sharded collection
   in the cluster. Given a collection named ``pets``
   in the ``records`` database, a document in the :data:`~config.collections`
   collection would resemble the following:

   .. code-block:: javascript

      {
         "_id" : "records.pets",
         "lastmod" : ISODate("1970-01-16T15:00:58.107Z"),
         "dropped" : false,
         "key" : {
               "a" : 1
         },
         "unique" : false,
         "lastmodEpoch" : ObjectId("5078407bd58b175c5c225fdc")
      }

.. data:: config.databases

   .. include:: /includes/admonition-config-db-is-internal.rst

   The :data:`~config.databases` collection stores a document for each
   database in the cluster, and tracks if the database has sharding
   enabled. :data:`~config.databases` represents each database in a
   distinct document. When a databases have sharding enabled, the
   ``primary`` field holds the name of the :term:`primary shard`.

   .. code-block:: javascript

      { "_id" : "admin", "partitioned" : false, "primary" : "config" }
      { "_id" : "mydb", "partitioned" : true, "primary" : "shard0000" }

.. data:: config.lockpings

   .. include:: /includes/admonition-config-db-is-internal.rst

   The :data:`~config.lockpings` collection keeps track of the active components
   in the sharded cluster. Given a cluster with a :program:`mongos`
   running on ``example.com:30000``, the document in the
   :data:`~config.lockpings` collection would resemble:

   .. code-block:: javascript

      { "_id" : "example.com:30000:1350047994:16807", "ping" : ISODate("2012-10-12T18:32:54.892Z") }

.. data:: config.locks

   .. include:: /includes/admonition-config-db-is-internal.rst

   The :data:`~config.locks` collection stores a distributed lock. This
   ensures that only one :program:`mongos` instance can perform
   administrative tasks on the cluster at once. The :program:`mongos`
   acting as :term:`balancer` takes a lock by inserting a document
   resembling the following into the ``locks`` collection.

   .. code-block:: javascript

      {
          "_id" : "balancer",
          "process" : "example.net:40000:1350402818:16807",
          "state" : 2,
          "ts" : ObjectId("507daeedf40e1879df62e5f3"),
          "when" : ISODate("2012-10-16T19:01:01.593Z"),
          "who" : "example.net:40000:1350402818:16807:Balancer:282475249",
          "why" : "doing balance round"
      }

   If a :program:`mongos` holds the balancer lock, the ``state`` field
   has a value of ``2``, which means that balancer is active. The ``when`` field
   indicates when the balancer began the current operation.

   .. versionchanged:: 2.0
      The value of the ``state`` field was ``1`` before MongoDB 2.0.

.. data:: config.mongos

   .. include:: /includes/admonition-config-db-is-internal.rst

   The :data:`~config.mongos` collection stores a document for each
   :program:`mongos` instance affiliated with the
   cluster. :program:`mongos` instances send pings to all members of
   the cluster every 30 seconds so the cluster can verify that the
   :program:`mongos` is active. The ``ping`` field shows the time of
   the last ping, while the ``up`` field reports the uptime of the
   :program:`mongos` as of the last ping. The cluster maintains this
   collection for reporting purposes.

   The following document shows the status of the :program:`mongos`
   running on ``example.com:30000``.

   .. code-block:: javascript

      { "_id" : "example.com:30000", "ping" : ISODate("2012-10-12T17:08:13.538Z"), "up" : 13699, "waiting" : true }

.. data:: config.settings

   .. include:: /includes/admonition-config-db-is-internal.rst

   The :data:`~config.settings` collection holds the following
   sharding configuration settings:

   - Chunk size. To change chunk size,
     see :doc:`/tutorial/modify-chunk-size-in-sharded-cluster`.

   - Balancer status. To change status,
     see :ref:`sharding-balancing-disable-temporarily`.

   The following is an example ``settings`` collection:

   .. code-block:: javascript

      { "_id" : "chunksize", "value" : 64 }
      { "_id" : "balancer", "stopped" : false }

.. data:: config.shards

   .. include:: /includes/admonition-config-db-is-internal.rst

   The :data:`~config.shards` collection represents each shard in the cluster
   in a separate document. If the shard is a replica set, the
   ``host`` field displays the name of the replica set, then a slash, then
   the hostname, as in the following example:

   .. code-block:: javascript

      { "_id" : "shard0000", "host" : "shard1/localhost:30000" }

   If the shard has :ref:`tags <tag-aware-sharding>` assigned, this
   document has a ``tags`` field, that holds an array of the tags, as
   in the following example:

   .. code-block:: javascript

      { "_id" : "shard0001", "host" : "localhost:30001", "tags": [ "NYC" ] }

.. data:: config.tags

   .. include:: /includes/admonition-config-db-is-internal.rst

   The :data:`~config.tags` collection holds documents for each tagged
   shard key range in the cluster. The documents in the
   :data:`~config.tags` collection resemble the following:

   .. code-block:: javascript

      {
          "_id" : { "ns" : "records.users", "min" : { "zipcode" : "10001" } },
          "ns" : "records.users",
          "min" : { "zipcode" : "10001" },
          "max" : { "zipcode" : "10281" },
          "tag" : "NYC"
      }

.. data:: config.version

   .. include:: /includes/admonition-config-db-is-internal.rst

   The :data:`~config.version` collection holds the current metadata version number. This
   collection contains only one document:

   To access the :data:`~config.version` collection you must use the
   :method:`db.getCollection()` method. For example, to display the
   collection's document:

   .. code-block:: javascript

      mongos> db.getCollection("version").find()
      { "_id" : 1, "version" : 3 }

.. note::

   Like all databases in MongoDB, the ``config`` database contains a
   :data:`system.indexes <<database>.system.indexes>` collection
   contains metadata for all indexes in the database for information
   on indexes, see :doc:`/indexes`.