listDatabases¶

On this page

Definition
Output
Examples

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 field:

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

New in version 3.6.

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.

New in version 3.6.

Output¶

listDatabases returns a document that contains:

A field named databases whose value is an array of documents, one document for each database. Each document contains:
- A name field with the database name.
- A sizeOnDisk field with the total size of the database files on disk in bytes.
- An empty field specifying whether the database has any data.
- For sharded clusters, a shards field that includes the shard and the size in bytes of the database on disk for each shard.
A field named totalSize whose value is the sum of all the sizeOnDisk fields in bytes.

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,
   "ok" : 1
}

List Database Names Only¶

New in version 3.6.

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¶

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:

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.

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
}