Config Database

On this page

Restrictions

Collections to Support Sharded Cluster Operations
Collections to Support Sessions

The collections in the config database support:

Sharded cluster operations
Causally consistent sessions for standalones, replica sets, and sharded clusters and retryable writes for replica sets and sharded clusters.

Restrictions

Starting in MongoDB 5.0, non-transaction reads are not allowed on the config.transactions collection with the following read concerns and options:

"snapshot"
"majority" and the afterClusterTime option is set
When using a MongoDB Driver and "majority" within a causally consistent session

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.

Note

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

Collections to Support Sharded Cluster Operations

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

use config
show collections

Note

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

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.insertOne( { 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

Tip

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

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("<...>")
    },
    "owningShard" : "<value>"
 }
}

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 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 regarding the change. The structure of the details document depends on the type of change.

config.chunks

Tip

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

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

{
   "_id" : "mydb.foo-a_\"cat\"",
   "lastmod" : Timestamp(2, 1),
   "uuid": "c025d039-e626-435e-b2d2-c1d436038041",
   "min" : {
         "animal" : "cat"
   },
   "max" : {
         "animal" : "dog"
   },
   "shard" : "shard0004",
   "history" : [ { "validAfter" : Timestamp(1569368571, 27), "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

Tip

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

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("2021-07-21T15:48:15.193Z"),
   "timestamp": Timestamp(1626882495, 1),
   "key" : {
         "a" : 1
   },
   "unique" : false,
   "lastmodEpoch" : ObjectId("5078407bd58b175c5c225fdc"),
   "uuid" :  UUID("f8669e52-5c1b-4ea2-bbdc-a00189b341da")
}

config.databases

Tip

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

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 , the database's sharding enabled status, and a version.

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

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

config.lockpings

Tip

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

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

Tip

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

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.migrationCoordinators

New in version 4.4.

The migrationCoordinators collection exists on each shard and stores a document for each in-progress chunk migration from this shard to another shard. The chunk migration fails if the document cannot be written to a majority of the members of the shard's replica set.

When a migration is complete, the document describing the migration is deleted from the collection.

config.mongos

Tip

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

The mongos collection stores a document for each mongos instance affiliated with the cluster. The cluster maintains this collection for reporting purposes.

Each document in the mongos collection contains these fields:

Field	Data Type	Description
`_id`	String	The hostname and port where the `mongos` is running. The `_id` is formatted as `<hostname>:<port>`.
`advisoryHostFQDNs`	Array of strings	Array of the `mongos`'s fully qualified domain names (FQDNs).
`created`	Date	When the `mongos` was started. New in version 5.2.
`mongoVersion`	String	Version of MongoDB that the `mongos` is running.
`ping`	Date	`mongos` instances send pings to the config server every 30 seconds. This field indicates the last ping time.
`up`	NumberLong	Number of seconds the `mongos` has been up as of the last ping.
`waiting`	Boolean	As of MongoDB 3.4, this field is always `true` and is only present for backward compatibility.

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

[
   {
     _id: 'example.com:27017',
     advisoryHostFQDNs: [ "example.com" ],
     created: ISODate("2021-11-22T16:32:13.708Z"),
     mongoVersion: "5.2.0",
     ping: ISODate("2021-12-15T22:09:23.161Z"),
     up: Long("2007429"),
     waiting: true
   }
]

config.rangeDeletions

The rangeDeletions collection exists on each shard and stores a document for each chunk range that contains orphaned documents. The chunk migration fails if the document cannot be written to a majority of the members of the shard's replica set.

When the orphaned chunk range is cleaned up, the document describing the range is deleted from the collection.

config.settings

Tip

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

The settings collection holds the following sharding configuration settings:

Range size. To change range size, see Modify Range Size in a Sharded Cluster. The specified chunksize value is in megabytes.
Balancer settings. To change the balancer settings, including balancer status, see Manage Sharded Cluster Balancer.
Autosplit:
Starting in MongoDB 6.1, automatic chunk splitting is not performed. This is because of balancing policy improvements. Auto-splitting commands still exist, but do not perform an operation. For details, see Balancing Policy Changes.
In MongoDB versions earlier than 6.1:
- balancerStart also enables auto-splitting for the sharded cluster.
- balancerStop also disables auto-splitting for the sharded cluster.
- To enable or disable the autosplit flag, use the corresponding sh.enableAutoSplit() method or sh.disableAutoSplit() method.

Example documents in the settings collection:

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

config.shards

Tip

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

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

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

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

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

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

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

config.tags

Tip

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

The tags collection holds documents for each zone range in the cluster. The documents in the tags collection resemble the following:

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

config.version

Tip

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

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

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

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

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

Collections to Support Sessions

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

Warning

Do not manually modify or drop these collections.

To access these collections for a mongod or mongos instance, connect mongosh to the instance.

config.system.sessions

The system.sessions collection stores session records that are available to all members of the deployment.

When a user creates a session on a mongod or mongos instance, the record of the session initially exists only in-memory on the instance. Periodically, the instance will 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 add already contains its own system.sessions collection, MongoDB drops the new shard's system.sessions collection during the add process.
Starting in version 4.4 (and 4.2.7), MongoDB automatically splits the system.sessions collection into at least 1024 chunks and distributes the chunks uniformly across shards in the cluster.

config.transactions: The transactions collection stores records used to support retryable writes and transactions for replica sets and sharded clusters.
Warning
Do not manually modify or drop the transactions collection.

Back

Troubleshoot Sharded Clusters

Change Streams

Config Database.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-fmznk8{margin-top:-85px;position:absolute;padding-bottom:2px;}

Restrictions

Important

Note

Collections to Support Sharded Cluster Operations

Note

Warning

Tip

Internal MongoDB Metadata

Example

Tip

Internal MongoDB Metadata

Tip

Internal MongoDB Metadata

Tip

Internal MongoDB Metadata

Tip

Internal MongoDB Metadata

Tip

Internal MongoDB Metadata

Tip

Internal MongoDB Metadata

Tip

Internal MongoDB Metadata

Tip

Internal MongoDB Metadata

Tip

Internal MongoDB Metadata

Tip

Internal MongoDB Metadata

Collections to Support Sessions

Warning

Warning

Warning

Config Database