Docs Home → Develop Applications → MongoDB Manual
listDatabases![](/docs/v5.2/assets/link.svg)
On this page
Definition![](/docs/v5.2/assets/link.svg)
listDatabases
The
listDatabases
command provides a list of all existing databases along with basic statistics about them. ThelistDatabases
must run against theadmin
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:FieldTypeDescriptionfilter
documentOptional. 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
booleanOptional. 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
, solistDatabases
returns the name and size information of each database.New in version 3.6.
authorizedDatabases
booleanOptional. A flag that determines which databases are returned based on the user privileges when access control is enabled.
If
authorizedDatabases
is unspecified, andIf 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 thefind
action on the database resource (and not the collection resource).
If
authorizedDatabases
istrue
,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 thefind
action on the database resource (and not the collection resource).
If
authorizedDatabases
isfalse
, andIf the user has
listDatabases
action on the cluster,listDatabases
command returns all databasesIf 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
anyOptional. 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 thecommand.comment
field.
A comment can be any valid BSON type (string, integer, object, array, etc).
New in version 4.4.
Behavior![](/docs/v5.2/assets/link.svg)
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).
Client Disconnection![](/docs/v5.2/assets/link.svg)
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![](/docs/v5.2/assets/link.svg)
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![](/docs/v5.2/assets/link.svg)
List Database Names and Sizes![](/docs/v5.2/assets/link.svg)
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, "totalSizeMb" : 251, "ok" : 1 }
List Database Names Only![](/docs/v5.2/assets/link.svg)
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![](/docs/v5.2/assets/link.svg)
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![](/docs/v5.2/assets/link.svg)
When executed against a mongos
instance,
listDatabases
:
adds a
shards
embedded document to each database's summary document ifnameOnly: false
, andexcludes 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:
{ "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 }
Tip
See also:
Output![](/docs/v5.2/assets/link.svg)
listDatabases.databases
Type: Array
Array of documents, each containing information on a single database.
listDatabases.databases.sizeOnDisk
Type: Integer
Total size of the database files on disk, expressed in bytes.
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 ifnameOnly: false
.See Sharded Clusters for details.