Definition
listDatabasesThe
listDatabasescommand provides a list of all existing databases along with basic statistics about them. ThelistDatabasesmust run against theadmindatabase, as in the following example:
Compatibility
This command is available in deployments hosted in the following environments:
MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud
Note
This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see Unsupported Commands.
MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB
Syntax
db.adminCommand( { listDatabases: 1 } )
The value (e.g. 1) does not affect the output of the
command.
Command Fields
The command can take the following optional fields:
Field | Type | Description |
|---|---|---|
| document | Optional. A query predicate that determines which databases are listed. You can specify a condition on any of the fields in the output of
|
| boolean | Optional. A flag to indicate whether the command should return just the database names, or return both database names and size information. Returning size information requires locking each database one at a time, while returning only names does not require locking any database. The default value is |
| boolean | Optional. A flag that determines which databases are returned based on the user privileges when access control is enabled.
For more information, see Behavior. |
| any | Optional. A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations:
A comment can be any valid BSON type (string, integer, object, array, etc). |
Behavior
When authentication is enabled,
the listDatabases command returns different values based on
the privileges assigned to the user who executes the command and the
authorizedDatabases command option:
If
authorizedDatabasesis unspecified, andIf the user has
listDatabasesaction on the cluster resource,listDatabasescommand returns all databases.If the user does not have
listDatabasesaction on the cluster,listDatabasescommand returns only the databases for which the user has privileges (including databases for which the user has privileges on specific collections).
If
authorizedDatabasesistrue,listDatabasescommand returns only the databases for which the user has privileges (including databases for which the user has privileges on specific collections).If
authorizedDatabasesisfalse, andIf the user has
listDatabasesaction on the cluster,listDatabasescommand returns all databasesIf the user does not have
listDatabasesaction on the cluster,listDatabasescommand errors with insufficient permissions.
Client Disconnection
Starting in MongoDB 4.2, if the client that issued listDatabases
disconnects before the operation completes, MongoDB marks listDatabases
for termination using killOp.
Replica Set Member State Restriction
To run on a replica set member, listDatabases operations require the member
to be in PRIMARY or SECONDARY state. If the member
is in another state, such as STARTUP2, the
operation errors.
Examples
List Database Names and Sizes
Run listDatabases against the admin database:
db.adminCommand( { listDatabases: 1 } )
The following is an example of a listDatabases result:
{ "databases" : [ { "name" : "admin", "sizeOnDisk" : 83886080, "empty" : false }, { "name" : "local", "sizeOnDisk" : 83886080, "empty" : false }, { "name" : "test", "sizeOnDisk" : 83886080, "empty" : false } ], "totalSize" : 251658240, "totalSizeMb" : 251, "ok" : 1 }
List Database Names Only
New in version 3.6.
Run listDatabases against the admin database. Specify
the nameOnly: true option:
db.adminCommand( { listDatabases: 1, nameOnly: true} )
The following is an example of a listDatabases results
when run with the nameOnly: true option:
{ "databases" : [ { "name" : "admin" }, { "name" : "local" }, { "name" : "test" } ], "ok" : 1 }
List Databases That Match the Filter
New in version 3.6.
Run listDatabases against the admin database. Specify
the filter option to only list databases that match the specified filter criteria.
For example, the following specifies a filter such that
listDatabases only returns information on databases whose
name matches the specified regular expression:
db.adminCommand( { listDatabases: 1, filter: { "name": /^rep/ } } )
Sharded Clusters
When executed against a mongos instance,
listDatabases:
adds a
shardsembedded document to each database's summary document ifnameOnly: false, andexcludes the
localdatabase.
Each element in the shards embedded document consists of a field
whose key gives the name of a collection on that shard, and whose value
represents the collection's size in bytes.
The sizeOnDisk field represents the total size of all
listed collections and indexes.
For example:
{ "databases" : [ { "name" : "admin", "sizeOnDisk" : 16384, "empty" : false, "shards" : { "config" : 16384 } }, { "name" : "config", "sizeOnDisk" : 176128, "empty" : false, "shards" : { "clients" : 28672, "patients" : 8192, "config" : 139264 } }, { "name" : "test", "sizeOnDisk" : 12288, "empty" : false, "shards" : { "clients" : 12288 } } ], "totalSize" : 204800, "totalSizeMb" : 0, "ok" : 1 }
Output
listDatabases.databasesType: Array
Array of documents, each containing information on a single database.
listDatabases.databases.sizeOnDiskType: Integer
Total size of the database files on disk, expressed in bytes.
listDatabases.databases.shardsType: Document
Each element in the
shardsdocument consists of a field whose key gives the name of a collection on that shard, and whose value represents the collection's size in bytes.shardsonly appears in the output ifnameOnly: false.See Sharded Clusters for details.