Config Database

The collections in the config database support:

Important

The schema of the config database is 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.

Collections to Support Sharded Cluster Operations

To access the config database and view the list of collections that support sharding operations, connect a mongo shell to a mongos instance in a sharded cluster and issue the following:

use config

show collections

The config database is mainly for internal use, and during normal operations you should never manually insert or store data in it. However, if you need to verify the write availability of the config server for a sharded cluster, you can insert a document into a test collection (after making sure that no collection of that name already exists):

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 mongodump to create a full backup of the config database.

db.testConfigServerWriteAvail.insert( { a : 1 } )

If the operation succeeds, the config server is available to process writes.

Future releases of the server may include different collections in the config database, so be careful when selecting a name for your test collection.

MongoDB uses the following collections in the config database to support sharding:

config. changelog

The 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 changelog collection:

{
 "_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 changelog collection contains the following fields:

config.changelog. _id

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

config.changelog. server

The hostname of the server that holds this data.

config.changelog. clientAddr

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

config.changelog. time

A ISODate timestamp that reflects when the change occurred.

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
config.changelog. ns

Namespace where the change occurred.

config.changelog. details

A document that contains additional details regarding the change. The structure of the details document depends on the type of change.

config. chunks

The 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\":

{
   "_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.

config. collections

The 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 collections collection would resemble the following:

{
   "_id" : "records.pets",
   "lastmod" : ISODate("1970-01-16T15:00:58.107Z"),
   "dropped" : false,
   "key" : {
         "a" : 1
   },
   "unique" : false,
   "lastmodEpoch" : ObjectId("5078407bd58b175c5c225fdc"),
   "uuid" : UUID("23f01653-53c7-4da2-aa01-ac3cbcf572d6")
}
config. databases

The databases collection stores a document for each database in the cluster. For each database, the corresponding document displays the name, the database’s primary shard, and the database’s sharding enabled status.

{ "_id" : "mydb", "primary" : "shard0000", "partitioned" : true }
config. lockpings

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

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

The locks collection stores the distributed locks. The primary of the config server replica set takes a lock by inserting a document into the locks collection.

{
   "_id" : "test.myShardedCollection",
   "state" : 2,
   "process" : "ConfigServer",
   "ts" : ObjectId("5be0b9ede46e4f441a60d891"),
   "when" : ISODate("2018-11-05T21:52:00.846Z"),
   "who" : "ConfigServer:Balancer",
   "why" : "Migrating chunk(s) in collection test.myShardedCollection"
}

As of version 3.4, the state field will always have a value 2 to prevent any legacy mongos instances from performing the balancing operation. The when field specifies the time when the config server member became the primary.

In version 3.4, when the balancer is active, the balancer takes a lock, as in the following 3.4 example:

{
   "_id" : "balancer",
   "state" : 2,
   "ts" : ObjectId("5be0bc6cb20effa83b15baa8"),
   "who" : "ConfigServer:Balancer",
   "process" : "ConfigServer",
   "when" : ISODate("2018-11-05T21:56:13.096Z"),
   "why" : "CSRS Balancer"
}

Starting in version 3.6, the balancer no longer takes a “lock”. If you have upgraded from 3.4 to 3.6, you may choose to delete any residual "_id" : "balancer" documents.

config. mongos

The mongos collection stores a document for each mongos instance affiliated with the cluster. mongos instances send pings to all members of the cluster every 30 seconds so the cluster can verify that the mongos is active. The