listDatabases¶

On this page

Definition
Behavior
Examples
Output

Definition¶

listDatabases¶

The listDatabases command provides a list of all existing databases along with basic statistics about them. The listDatabases must run against the admin database, as in the following example:

copy

db.adminCommand( { listDatabases: 1 } )

The value (e.g. 1) does not affect the output of the command.

The listDatabases command can take the following optional fields:

Field	Type	Description
`filter`	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 `listDatabases`: `name` `sizeOnDisk` `empty` `shards`
`nameOnly`	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 `false`, so `listDatabases` returns the name and size information of each database.
`authorizedDatabases`	boolean	Optional. A flag that determines which databases are returned based on the user privileges when access control is enabled. If `authorizedDatabases` is unspecified, and If the user has `listDatabases` action on the cluster resource, `listDatabases` command returns all databases. If the user does not have `listDatabases` action on the cluster: For MongoDB 4.0.6+, `listDatabases` command returns only the databases for which the user has privileges (including databases for which the user has privileges on specific collections). For MongoDB 4.0.5, `listDatabases` command returns only the databases for which the user has the `find` action on the database resource (and not the collection resource). If `authorizedDatabases` is `true`, For MongoDB 4.0.6+, `listDatabases` command returns only the databases for which the user has privileges (including databases for which the user has privileges on specific collections). For MongoDB 4.0.5, `listDatabases` command returns only the databases for which the user has the `find` action on the database resource (and not the collection resource). If `authorizedDatabases` is `false`, and If the user has `listDatabases` action on the cluster, `listDatabases` command returns all databases If the user does not have `listDatabases` action on the cluster, `listDatabases` command errors with insufficient permissions. For more information, see Behavior. New in version 4.0.5.
`comment`	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: mongod log messages, in the `attr.command.cursor.comment` field. Database profiler output, in the `command.comment` field. `currentOp` output, in the `command.comment` field. A comment can be any valid BSON type (string, integer, object, array, etc). New in version 4.4.

Behavior¶

When authentication is enabled:

Note

For mongosh connected to earlier versions of MongoDB deployment (e.g. 3.6.10),

If the user has listDatabases action on the cluster resource, show dbs returns all databases.
If the user does not have listDatabases action on the cluster resource, show dbs returns only the databases for which the user has privileges (including those databases for which the user has privileges on specific collections).

MongoDB 4.0.6+
MongoDB 4.0.5
MongoDB 4.0.0-4.0.4

For MongoDB 4.0.6+, the listDatabases command returns different values based on the privileges assigned to the user who executes the command and the authorizedDatabases command option:

If authorizedDatabases is unspecified, and
- If the user has listDatabases action on the cluster resource, listDatabases command returns all databases.
- If the user does not have listDatabases action on the cluster, listDatabases command returns only the databases for which the user has privileges (including databases for which the user has privileges on specific collections).
If authorizedDatabases is true, listDatabases command returns only the databases for which the user has privileges (including databases for which the user has privileges on specific collections).
If authorizedDatabases is false, and
- If the user has listDatabases action on the cluster, listDatabases command returns all databases
- If the user does not have listDatabases action on the cluster, listDatabases command errors with insufficient permissions.

For MongoDB 4.0.5, the listDatabases command returns different values based on the privileges assigned to the user who executes the command and the authorizedDatabases command option:

If authorizedDatabases is unspecified, and
- If the user has listDatabases action on the cluster resource, listDatabases command returns all databases.
- If the user does not have listDatabases action on the cluster, listDatabases command returns only the databases for which the user has the find action on the database resource (and not the collection resource).
If authorizedDatabases is true, listDatabases command returns only the databases for which the user has the find action on the database resource (and not the collection resource).
If authorizedDatabases is false, and
- If the user has listDatabases action on the cluster, listDatabases command returns all databases
- If the user does not have listDatabases action on the cluster, listDatabases command errors with insufficient permissions.

For MongoDB 4.0.0-4.0.4, the listDatabases command returns different values based on the privileges assigned to the user who executes the command.

If the user has the listDatabases privilege action on the cluster, the listDatabases command returns a list of all existing databases.
If the user does not have the listDatabases privilege action on the cluster, the listDatabases command only returns a list of databases for which the user has the find action.

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¶

Starting in MongoDB 4.4, 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.

In previous versions, the operations also run when the member is in STARTUP2. The operations wait until the member transitioned to RECOVERING.

Examples¶

List Database Names and Sizes¶

Run listDatabases against the admin database:

copy

db.adminCommand( { listDatabases: 1 } )

The following is an example of a listDatabases result:

copy

{
   "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¶

Run listDatabases against the admin database. Specify the nameOnly: true option:

copy

db.adminCommand( { listDatabases: 1, nameOnly: true} )

The following is an example of a listDatabases results when run with the nameOnly: true option:

copy

{
   "databases" : [
      {
         "name" : "admin"
      },
      {
         "name" : "local"
      },
      {
         "name" : "test"
      }
   ],
   "ok" : 1
}

List Databases That Match the Filter¶

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:

copy

db.adminCommand( { listDatabases: 1, filter: { "name": /^rep/ } } )

Sharded Clusters¶

When executed against a mongos instance, listDatabases:

adds a shards embedded document to each database’s summary document if nameOnly: false, and
excludes the local database.

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:

copy

{
  "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.databases¶

Type: Array

Array of documents, each containing information on a single database.

listDatabases.databases.name¶

Type: String

Name of the database.

listDatabases.databases.sizeOnDisk¶

Type: Integer

Total size of the database files on disk, expressed in bytes.

listDatabases.databases.empty¶

Type: Boolean

Specifies whether the database is empty.

listDatabases.databases.shards¶

Type: Document

Each element in the shards 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.

shards only appears in the output if nameOnly: false.

See Sharded Clusters for details.

listDatabases.totalSize¶

Type: Integer

Sum of all the sizeOnDisk fields in bytes.

listDatabases.totalSizeMb¶

Type: Integer

Sum of all the sizeOnDisk fields, expressed in megabytes.

listDatabases.ok¶

Type: Integer

Return value for the command. A value of 1 indicates success.

← listCollections listIndexes →