Docs Home → Develop Applications → MongoDB Manual
Config Database![](/docs/v5.3/assets/link.svg)
On this page
The collections in the config
database support:
Causally consistent sessions for standalones, replica sets, and sharded clusters and retryable writes for replica sets and sharded clusters.
Restrictions![](/docs/v5.3/assets/link.svg)
Starting in MongoDB 5.0, non-transaction reads are not allowed on
the config.transactions
collection with the following
read concerns and options:
"majority"
and the afterClusterTime option is setWhen 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![](/docs/v5.3/assets/link.svg)
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.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.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 namedmydb.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
andmax
fields. Additionally theshard
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 namedpets
in therecords
database, a document in thecollections
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 amongos
running onexample.com:30000
, the document in thelockpings
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 thelocks
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 value2
to prevent any legacymongos
instances from performing the balancing operation. Thewhen
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 eachmongos
instance affiliated with the cluster. The cluster maintains this collection for reporting purposes.Each document in the
mongos
collection contains these fields:FieldData TypeDescription_id
StringThe hostname and port where themongos
is running. The_id
is formatted as<hostname>:<port>
.advisoryHostFQDNs
Array of stringsArray of themongos
's fully qualified domain names (FQDNs).created
DateWhen the
mongos
was started.New in version 5.2.
mongoVersion
StringVersion of MongoDB that themongos
is running.ping
Datemongos
instances send pings to the config server every 30 seconds. This field indicates the last ping time.up
NumberLongNumber of seconds themongos
has been up as of the last ping.waiting
BooleanAs of MongoDB 3.4, this field is alwaystrue
and is only present for backward compatibility.The following document shows the status of the
mongos
running onexample.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:Chunk size. To change chunk size, see Modify Chunk 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.
Starting in MongoDB 4.2:
balancerStart
also enables auto-splitting for the sharded cluster.balancerStop
also disables auto-splitting for the sharded cluster.
Autosplit. To enable or disable the autosplit flag, use the corresponding
sh.enableAutoSplit()
method orsh.disableAutoSplit()
method.Starting in MongoDB 4.2:
balancerStart
also enables auto-splitting for the sharded cluster.balancerStop
also disables auto-splitting for the sharded cluster.
The following are some example documents in the
settings
collection:{ "_id" : "chunksize", "value" : 64 } { "_id" : "balancer", "mode" : "full", "stopped" : false } { "_id" : "autosplit", "enabled" : true }
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 thetags
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 thedb.getCollection()
method. For example, to retrieve the collection's document:db.getCollection("version").find()
Collections to Support Sessions![](/docs/v5.3/assets/link.svg)
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
ormongos
instance, the record of the session initially exists only in-memory on the instance. Periodically, the instance will sync its cached sessions to thesystem.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'ssystem.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.