Config Database

The collections in the config database support:

Restrictions

Important

The schema of the config database isinternal and may change between releases of MongoDB. Theconfig database is not a dependable API, and users should notwrite data to the config database in the course of normaloperation or maintenance.

Note

You cannot perform read/write operations to the collections in theconfig database inside a multi-document transaction.

Collections to Support Sharded Cluster Operations

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

  1. use config
  2.  
  3. show collections

Note

If running with access control, ensure you have privileges thatgrant listCollections action on the database.

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

Warning

Modification of the config database on a functioningsystem may lead to instability or inconsistent data sets. If youmust modify the config database, use mongodump tocreate a full backup of the config database.

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

If the operation succeeds, the config server is available to processwrites.

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

MongoDB uses the following collections in the config databaseto support sharding:

  • config.changelog

Internal MongoDB Metadata

The config database is internal: applications andadministrators should not modify or depend upon its content in thecourse of normal operation.

The changelog collection stores a document for each change tothe metadata of a sharded collection.

Example

The following example displays a single record of a chunk splitfrom a changelog collection:

  1. {
  2.  "_id" : "<hostname>-<timestamp>-<increment>",
  3.  "server" : "<hostname><:port>",
  4.  "clientAddr" : "127.0.0.1:63381",
  5.  "time" : ISODate("2012-12-11T14:09:21.039Z"),
  6.  "what" : "split",
  7.  "ns" : "<database>.<collection>",
  8.  "details" : {
  9.     "before" : {
  10.        "min" : {
  11.           "<database>" : { $minKey : 1 }
  12.        },
  13.        "max" : {
  14.           "<database>" : { $maxKey : 1 }
  15.        },
  16.        "lastmod" : Timestamp(1000, 0),
  17.        "lastmodEpoch" : ObjectId("000000000000000000000000")
  18.     },
  19.     "left" : {
  20.        "min" : {
  21.           "<database>" : { $minKey : 1 }
  22.        },
  23.        "max" : {
  24.           "<database>" : "<value>"
  25.        },
  26.        "lastmod" : Timestamp(1000, 1),
  27.        "lastmodEpoch" : ObjectId(<...>)
  28.     },
  29.     "right" : {
  30.        "min" : {
  31.           "<database>" : "<value>"
  32.        },
  33.        "max" : {
  34.           "<database>" : { $maxKey : 1 }
  35.        },
  36.        "lastmod" : Timestamp(1000, 2),
  37.        "lastmodEpoch" : ObjectId("<...>")
  38.     }
  39.  }
  40. }

Each document in the changelog collection contains thefollowing 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, amongos instance that initiates this change.

  • config.changelog.time

  • A ISODate timestamp that reflects when the changeoccurred.

  • config.changelog.what

  • Reflects the type of change recorded. Possible values include:

    • 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 regardingthe change. The structure of the detailsdocument depends on the type of change.
  • config.chunks

Internal MongoDB Metadata

The config database is internal: applications andadministrators should not modify or depend upon its content in thecourse of normal operation.

The chunks collection stores a document for each chunk inthe cluster. Consider the following example of a document for achunk named mydb.foo-a_\"cat\":

  1. {
  2.    "_id" : "mydb.foo-a_\"cat\"",
  3.    "lastmod" : Timestamp(2, 1),
  4.    "lastmodEpoch" : ObjectId("5d8aa9fbe7a2f52c300e8e6f"),
  5.    "ns" : "mydb.foo",
  6.    "min" : {
  7.          "animal" : "cat"
  8.    },
  9.    "max" : {
  10.          "animal" : "dog"
  11.    },
  12.    "shard" : "shard0004",
  13.    "history" : [ { "validAfter" : Timestamp(1569368571, 27), "shard" : "shard0004" } ]
  14. }

These documents store the range of values for the shard key thatdescribe the chunk in the min and max fields. Additionallythe shard field identifies the shard in the cluster that “owns”the chunk.

  • config.collections

Internal MongoDB Metadata

The config database is internal: applications andadministrators should not modify or depend upon its content in thecourse of normal operation.

The collections collection stores a document for each sharded collectionin the cluster. Given a collection named petsin the records database, a document in the collectionscollection would resemble the following:

  1. {
  2.    "_id" : "records.pets",
  3.    "lastmod" : ISODate("1970-01-16T15:00:58.107Z"),
  4.    "dropped" : false,
  5.    "key" : {
  6.          "a" : 1
  7.    },
  8.    "unique" : false,
  9.    "lastmodEpoch" : ObjectId("5078407bd58b175c5c225fdc"),
  10.    "uuid" :  UUID("f8669e52-5c1b-4ea2-bbdc-a00189b341da")
  11. }
  • config.databases

Internal MongoDB Metadata

The config database is internal: applications andadministrators should not modify or depend upon its content in thecourse of normal operation.

The databases collection stores a document for eachdatabase in the cluster.

For each database, the corresponding document displays the name, thedatabase’s primary shard , the database’ssharding enabled status, and a version.

  1. { "_id" : "test", "primary" : "shardA", "partitioned" : true, "version" : { "uuid" : UUID("516a5f79-5eb9-4844-8ee9-b8e9de91b760"), "lastMod" : 1 } }
  2. { "_id" : "hr", "primary" : "shardA", "partitioned" : false, "version" : { "uuid" : UUID("8e39d61d-6259-4c33-a5ed-bcd2ae317b6f"), "lastMod" : 1 } }
  3. { "_id" : "reporting", "primary" : "shardB", "partitioned" : false, "version" : { "uuid" : UUID("07c63242-51b3-460c-865f-a67b3372d792"), "lastMod" : 1 } }

The method sh.status() returns this information in theDatabases section.

  • config.lockpings

Internal MongoDB Metadata

The config database is internal: applications andadministrators should not modify or depend upon its content in thecourse of normal operation.

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

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

Internal MongoDB Metadata

The config database is internal: applications andadministrators should not modify or depend upon its content in thecourse of normal operation.

The locks collection stores the distributed locks. Theprimary of the config server replica set takes a lock byinserting a document into the lockscollection.

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

As of version 3.4, the state field will always have a value2 to prevent any legacy mongos instances fromperforming the balancing operation. The when field specifies thetime when the config server member became the primary.

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

  1. {
  2.    "_id" : "balancer",
  3.    "state" : 2,
  4.    "ts" : ObjectId("5be0bc6cb20effa83b15baa8"),
  5.    "who" : "ConfigServer:Balancer",
  6.    "process" : "ConfigServer",
  7.    "when" : ISODate("2018-11-05T21:56:13.096Z"),
  8.    "why" : "CSRS Balancer"
  9. }

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

  • config.mongos

Internal MongoDB Metadata

The config database is internal: applications andadministrators should not modify or depend upon its content in thecourse of normal operation.

The mongos collection stores a document for eachmongos instance affiliated with thecluster. mongos instances send pings to all members ofthe cluster every 30 seconds so the cluster can verify that themongos is active. The ping field shows the time ofthe last ping, while the up field reports the uptime of themongos as of the last ping. The cluster maintains thiscollection for reporting purposes.

The following document shows the status of the mongosrunning on example.com:27017.

  1. {
  2.    "_id" : "example.com:27017",
  3.    "advisoryHostFQDNs" : [
  4.       "example.com"
  5.    ],
  6.    "mongoVersion" : "4.2.0",
  7.    "ping" : ISODate("2019-09-25T19:26:52.360Z"),
  8.    "up" : NumberLong(50),
  9.    "waiting" : true
  10. }
  • config.settings

Internal MongoDB Metadata

The config database is internal: applications andadministrators should not modify or depend upon its content in thecourse of normal operation.

The settings collection holds the followingsharding configuration settings:

Starting in MongoDB 4.2:

  1. - [<code>balancerStart</code>]($c9976ce90b549a26.md#dbcmd.balancerStart) also enables auto-splitting for the sharded cluster.
  2. - [<code>balancerStop</code>]($8535964567f61ca4.md#dbcmd.balancerStop) also disables auto-splitting for the sharded cluster.

Starting in MongoDB 4.2:

  1. - [<code>balancerStart</code>]($c9976ce90b549a26.md#dbcmd.balancerStart) also enables auto-splitting for thesharded cluster.
  2. - [<code>balancerStop</code>]($8535964567f61ca4.md#dbcmd.balancerStop) also disables auto-splitting for thesharded cluster.

The following are some example documents in the settingscollection:

  1. { "_id" : "chunksize", "value" : 64 }
  2. { "_id" : "balancer", "mode" : "full", "stopped" : false }
  3. { "_id" : "autosplit", "enabled" : true }
  • config.shards

Internal MongoDB Metadata

The config database is internal: applications andadministrators should not modify or depend upon its content in thecourse of normal operation.

The shards collection represents each shard in the clusterin a separate document, as in the following:

  1. { "_id" : "shard0000", "host" : "localhost:30000", "state" : 1 }

If the shard is a replica set, thehost field displays the name of the replica set, then a slash, thena comma-separated list of the hostnames of each member of the replica set,as in the following example:

  1. { "_id" : "shard0001", "host" : "shard0001/localhost:27018,localhost:27019,localhost:27020", "state" : 1 }

If the shard has zones assigned, thisdocument has a tags field, that holds an array of the zonesto which it is assigned, as in the following example:

  1. { "_id" : "shard0002", "host" : "localhost:30002", "state" : 1, "tags": [ "NYC" ] }
  • config.tags

Internal MongoDB Metadata

The config database is internal: applications andadministrators should not modify or depend upon its content in thecourse of normal operation.

The tags collection holds documents for each zonerange in the cluster. The documents in thetags collection resemble the following:

  1. {
  2.     "_id" : { "ns" : "records.users", "min" : { "zipcode" : "10001" } },
  3.     "ns" : "records.users",
  4.     "min" : { "zipcode" : "10001" },
  5.     "max" : { "zipcode" : "10281" },
  6.     "tag" : "NYC"
  7. }
  • config.version

Internal MongoDB Metadata

The config database is internal: applications andadministrators should not modify or depend upon its content in thecourse of normal operation.

The version collection holds the current metadata version number. Thiscollection contains only one document. For example:

  1. { "_id" : 1, "minCompatibleVersion" : 5, "currentVersion" : 6, "clusterId" : ObjectId("5d8bc01a690d8abbd2014ddd") }

To access the version collection, you must use thedb.getCollection() method. For example, to retrieve thecollection’s document:

  1. db.getCollection("version").find()

Collections to Support Sessions

New in version 3.6.

Starting in MongoDB 3.6, the config database contains theinternal collections to support causally consistent sessions for standalones, replica sets, and sharded clusters andretryable writes and transactions forreplica sets and sharded clusters.

Warning

Do not manually modify or drop these collections.

To access these collections for a mongod ormongos instance, connect mongo shell to theinstance.

  • config.system.sessions
  • The system.sessions collection stores session records that areavailable to all members of the deployment.

When a user creates a session on a mongod ormongos instance, the record of the session initiallyexists only in-memory on the instance. Periodically, the instancewill sync its cached sessions to the system.sessions collection;at which time, they are visible to all members of the deployment.

To view records in the system.sessions collection, use$listSessions.

Warning

Do not manually modify or drop the system.sessions collection.

In a sharded cluster, the system.sessions collection is sharded.When adding a shard to the sharded cluster, if the shard to addalready contains its own system.sessions collection, MongoDBdrops the new shard’s system.sessions collection during the addprocess.

  • config.transactions
  • The transactions collection stores records used to supportretryable writes and transactions for replica sets and sharded clusters.

Warning

Do not manually modify or drop the transactions collection.