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 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.
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.

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.

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 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.

Examples

db.adminCommand( { listDatabases: 1 } )

{
   "databases" : [
      {
         "name" : "admin",
         "sizeOnDisk" : 83886080,
         "empty" : false
      },
      {
         "name" : "local",
         "sizeOnDisk" : 83886080,
         "empty" : false
      },
      {
         "name" : "test",
         "sizeOnDisk" : 83886080,
         "empty" : false
      }
   ],
   "totalSize" : 251658240,
   "ok" : 1
}

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

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

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

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