listDatabases

Definition

  • listDatabases
  • The listDatabases command provides a list of allexisting databases along with basic statistics about them. ThelistDatabases must run against the admin database,as in the following example:
  1. db.adminCommand( { listDatabases: 1 } )

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

The listDatabases command can take the followingoptional fields:

FieldTypeDescriptionfilterdocumentOptional. A query predicate that determines which databases are listed.

You can specify a condition on any of the fields in the output oflistDatabases:

  • name
  • sizeOnDisk
  • empty
  • shards

New in version 3.6.

nameOnlybooleanOptional. A flag to indicate whether the command should return just thedatabase names, or return both database names and size information.

Returning size information requires locking each database one at atime, while returning only names does not require locking any database.

The default value is false, so listDatabases returnsthe name and size information of each database.

New in version 3.6.

authorizedDatabasesbooleanOptional. A flag that determines which databases are returned based on theuser privileges when access control is enabled.

  • If authorizedDatabases is unspecified, and
    • If the user has listDatabases action on thecluster resource, listDatabases command returns alldatabases.
    • If the user does not have listDatabases action onthe cluster:
      • For MongoDB 4.0.6+, listDatabases command returnsonly the databases for which the user has privileges(including databases for which the user has privileges onspecific collections).
      • For MongoDB 4.0.5, listDatabases command returnsonly the databases for which the user has thefind action on the database resource (and notthe collection resource).
  • If authorizedDatabases is true,
    • For MongoDB 4.0.6+, listDatabases command returnsonly the databases for which the user has privileges(including databases for which the user has privileges onspecific collections).
    • For MongoDB 4.0.5, listDatabases command returnsonly the databases for which the user has the findaction on the database resource (and not the collectionresource).
  • If authorizedDatabases is false, and

New in version 4.0.5.

Output

listDatabases returns a document that contains:

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

Behavior

When authentication is enabled:

show dbs

For mongo shell version 4.0.6+ connected to earlierversions of MongoDB deployment (e.g. 3.6.10),

  • If the user has listDatabases action on the clusterresource, show dbs returns all databases.
  • If the user does not have listDatabases action onthe cluster resource, show dbs returns only the databases forwhich the user has privileges (including those databases for whichthe 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 commandreturns different values based on the privileges assigned tothe user who executes the command and theauthorizedDatabases command option:

  • If authorizedDatabases is unspecified, and
    • If the user has listDatabases action on thecluster resource, listDatabases command returns alldatabases.
    • If the user does not have listDatabases action onthe cluster, listDatabases command returns only thedatabases for which the user has privileges (including databasesfor which the user has privileges on specific collections).
  • If authorizedDatabases is true, listDatabasescommand returns only the databases for which the user hasprivileges (including databases for which the user has privilegeson specific collections).
  • If authorizedDatabases is false, and

For MongoDB 4.0.5, the listDatabases commandreturns different values based on the privileges assigned tothe user who executes the command and theauthorizedDatabases command option:

  • If authorizedDatabases is unspecified, and
    • If the user has listDatabases action on thecluster resource, listDatabases command returns alldatabases.
    • If the user does not have listDatabases action onthe cluster, listDatabases command returns only thedatabases for which the user has the find actionon the database resource (and not the collection resource).
  • If authorizedDatabases is true, listDatabasescommand returns only the databases for which the user has thefind action on the database resource (and not thecollection resource).
  • If authorizedDatabases is false, and

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

  • If the user has the listDatabases privilegeaction on the cluster, the listDatabases commandreturns a list of all existing databases.
  • If the user does not have the listDatabasesprivilege action on the cluster, thelistDatabases command only returns a list ofdatabases for which the user has the findaction.

Client Disconnection

Starting in MongoDB 4.2, if the client that issued the listDatabasesdisconnects before the operation completes, MongoDB marksthe listDatabases for termination (i.e. killOp on theoperation).

Examples

List Database Names and Sizes

Run listDatabases against the admin database:

  1. db.adminCommand( { listDatabases: 1 } )

The following is an example of a listDatabases result:

  1. {
  2.    "databases" : [
  3.       {
  4.          "name" : "admin",
  5.          "sizeOnDisk" : 83886080,
  6.          "empty" : false
  7.       },
  8.       {
  9.          "name" : "local",
  10.          "sizeOnDisk" : 83886080,
  11.          "empty" : false
  12.       },
  13.       {
  14.          "name" : "test",
  15.          "sizeOnDisk" : 83886080,
  16.          "empty" : false
  17.       }
  18.    ],
  19.    "totalSize" : 251658240,
  20.    "ok" : 1
  21. }

List Database Names Only

New in version 3.6.

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

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

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

  1. {
  2.    "databases" : [
  3.       {
  4.          "name" : "admin"
  5.       },
  6.       {
  7.          "name" : "local"
  8.       },
  9.       {
  10.          "name" : "test"
  11.       }
  12.    ],
  13.    "ok" : 1
  14. }

List Databases That Match the Filter

New in version 3.6.

Run listDatabases against the admin database. Specifythe filter option to only list databases that match the specified filter criteria.

For example, the following specifies a filter such thatlistDatabases only returns information on databases whosename matches the specified regular expression:

  1. 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 summarydocument if nameOnly: false, and
  • excludes the local database.

Each element in the shards embedded document consists of a fieldwhose key gives the name of a collection on that shard, and whose valuerepresents the collection’s size in bytes.

The sizeOnDisk field represents the total size of alllisted collections.

For example:

  1. {
  2.   "databases" : [
  3.     {
  4.       "name" : "admin",
  5.       "sizeOnDisk" : 16384,
  6.       "empty" : false,
  7.       "shards" : {
  8.         "config" : 16384
  9.       }
  10.     },
  11.     {
  12.       "name" : "config",
  13.       "sizeOnDisk" : 176128,
  14.       "empty" : false,
  15.       "shards" : {
  16.         "clients" : 28672,
  17.         "patients" : 8192,
  18.         "config" : 139264
  19.       }
  20.     },
  21.     {
  22.       "name" : "test",
  23.       "sizeOnDisk" : 12288,
  24.       "empty" : false,
  25.       "shards" : {
  26.         "clients" : 12288
  27.       }
  28.     }
  29.   ],
  30.   "totalSize" : 204800,
  31.   "totalSizeMb" : 0,
  32.   "ok" : 1
  33. }

See also

Use Database Commands.