Navigation
This version of the documentation is archived and no longer supported.

listDatabases

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:

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

For more information, see Behavior.

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:

show dbs

For mongo shell version 4.0.6+ 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.

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.

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,
   "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 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:

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