Skip to content

Commit 1e8a327

Browse files
blink1073blink1073
authored
DRIVERS-2789 Convert Enumerate Database Spec to Markdown (#1615)
* Rename source/enumerate-databases.rst to source/enumerate-databases.md * DRIVERS-2789 Convert Enumerate Database Spec to Markdown * update index
1 parent bf0ce7a commit 1e8a327

File tree

7 files changed

+258
-306
lines changed

7 files changed

+258
-306
lines changed

‎markdown_link_config.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@
1212
{
1313
"pattern": "^logging/logging.rst#log-severity-levels"
1414
},
15+
{
16+
"pattern": "./enumerate-indexes.rst"
17+
},
1518
{
1619
"pattern": "^https://github.com/10gen/mongo-enterprise-modules"
1720
},

‎source/client-side-operations-timeout/client-side-operations-timeout.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ The `timeoutMS` option applies to all operations defined in the following specif
9191
- [Change Streams](../change-streams/change-streams.md)
9292
- [Client Side Encryption](../client-side-encryption/client-side-encryption.md)
9393
- [Enumerating Collections](../enumerate-collections.md)
94-
- [Enumerating Databases](../enumerate-databases.rst)
94+
- [Enumerating Databases](../enumerate-databases.md)
9595
- [GridFS](../gridfs/gridfs-spec.md)
9696
- [Index Management](../index-management/index-management.md)
9797
- [Transactions](../transactions/transactions.md)

‎source/enumerate-databases.md

Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
# Enumerating Databases
2+
3+
- Status: Accepted
4+
- Minimum Server Version: 3.6
5+
6+
______________________________________________________________________
7+
8+
## Abstract
9+
10+
A driver can provide functionality to enumerate all databases on a server. This specification defines several methods
11+
for enumerating databases.
12+
13+
## META
14+
15+
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
16+
"OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
17+
18+
## Specification
19+
20+
### Terms
21+
22+
**MongoClient**\
23+
Driver object representing a connection to MongoDB. This is the root object of a driver's API and MAY
24+
be named differently in some drivers.
25+
26+
**MongoDatabase**\
27+
Driver object representing a database and the operations that can be performed on it. MAY be named
28+
differently in some drivers.
29+
30+
**Iterable**\
31+
An object or data structure that is a sequence of elements that can be iterated over. This spec is
32+
flexible on what that means as different drivers will have different requirements, types, and idioms.
33+
34+
**Document**\
35+
An object or data structure used by the driver to represent a BSON document. This spec is flexible on what
36+
that means as different drivers will have different requirements, types, and idioms.
37+
38+
### Naming Deviations
39+
40+
This specification defines names for methods. To the extent possible, drivers SHOULD use the defined names. However,
41+
where a driver or language's naming conventions would conflict, drivers SHOULD honor their existing conventions. For
42+
example, a driver may use `list_databases` instead of `listDatabases`.
43+
44+
### Filters
45+
46+
Drivers SHOULD support the `filter` option when implementing the
47+
[listDatabases](https://www.mongodb.com/docs/manual/reference/command/listDatabases/) database command. The `filter`
48+
option is a query predicate that determines which databases are listed in the command result. You can specify a
49+
condition on any of the database fields returned in the command output:
50+
51+
- `name`
52+
- `sizeOnDisk`
53+
- `empty`
54+
- `shards`
55+
56+
For example, to list only databases whose names begin with "foo":
57+
58+
```javascript
59+
db.adminCommand({listDatabases: 1, filter: {name: /^foo/}});
60+
```
61+
62+
### AuthorizedDatabases
63+
64+
MongoDB 4.0.5 added an `authorizedDatabases` boolean option to the
65+
[listDatabases](https://www.mongodb.com/docs/manual/reference/command/listDatabases/) database command, which can be
66+
used to limit the command result to only include databases the user is authorized to use. Drivers SHOULD support the new
67+
`authorizedDatabases` option when implementing the
68+
[listDatabases](https://www.mongodb.com/docs/manual/reference/command/listDatabases/) database command.
69+
70+
The possible values for `authorizedDatabases` are:
71+
72+
- unspecified (missing entirely from the command document sent to the server)
73+
- `false`
74+
- `true`
75+
76+
See the server's [listDatabases](https://www.mongodb.com/docs/manual/reference/command/listDatabases/) documentation for
77+
an explanation of what each value means.
78+
79+
### Comment
80+
81+
MongoDB 4.4 introduced a `comment` option to the `listDatabases` command. This option enables users to specify a comment
82+
as an arbitrary BSON type to help trace the operation through the database profiler, currentOp and logs. The default is
83+
to not send a value. If a comment is provided on pre-4.4 servers, the comment should still be attached and the driver
84+
should rely on the server to provide an error to the user.
85+
86+
```javascript
87+
db.getSiblingDB("admin").runCommand({listDatabases: 1, comment: "hi there"})
88+
```
89+
90+
### Driver Methods
91+
92+
If a driver already has a method to perform one of the listed tasks, there is no need to change it. Do not break
93+
backwards compatibility when adding new methods.
94+
95+
All methods SHOULD be implemented on the MongoClient object.
96+
97+
All methods MUST apply timeouts per the
98+
[Client Side Operations Timeout](./client-side-operations-timeout/client-side-operations-timeout.md) specification.
99+
100+
#### Enumerating Full Database Information
101+
102+
The [listDatabases](https://www.mongodb.com/docs/manual/reference/command/listDatabases/) database command returns an
103+
array of documents, each of which contains information about a database on the MongoDB server. Additionally, the command
104+
reports the aggregate sum of all database sizes (in bytes). Consider the following example:
105+
106+
```javascript
107+
db.getSiblingDB("admin").runCommand({listDatabases:1})
108+
{
109+
"databases" : [
110+
{
111+
"name" : "admin",
112+
"sizeOnDisk" : 83886080,
113+
"empty" : false
114+
},
115+
{
116+
"name" : "local",
117+
"sizeOnDisk" : 83886080,
118+
"empty" : false
119+
}
120+
],
121+
"totalSize" : 167772160,
122+
"ok" : 1
123+
}
124+
```
125+
126+
Drivers SHOULD implement a MongoClient method that returns an Iterable of database specifications (e.g. model object,
127+
document type), each of which correspond to an element in the databases array of the `listDatabases` command result.
128+
This method SHOULD be named `listDatabases`.
129+
130+
Drivers MAY report `totalSize` (e.g. through an additional output variable on the `listDatabases` method), but this is
131+
not necessary.
132+
133+
Drivers SHOULD support the `filter`, `authorizedDatabases` and `comment` options when implementing this method.
134+
135+
#### Enumerating Database Names
136+
137+
MongoDB 3.6 introduced a `nameOnly` boolean option to the `listDatabases` database command, which limits the command
138+
result to only include database names. Consider the following example:
139+
140+
```
141+
> db.getSiblingDB("admin").runCommand({listDatabases:1,nameOnly:true})
142+
{
143+
"databases" : [
144+
{ "name" : "admin" },
145+
{ "name" : "local" }
146+
],
147+
"ok" : 1
148+
}
149+
```
150+
151+
Drivers MAY implement a MongoClient method that returns an Iterable of strings, each of which corresponds to a name in
152+
the databases array of the `listDatabases` command result. This method SHOULD be named `listDatabaseNames`.
153+
154+
Drivers SHOULD support the `filter`, `authorizedDatabases` and `comment` options when implementing this method.
155+
156+
#### Enumerating MongoDatabase Objects
157+
158+
Drivers MAY implement a MongoClient method that returns an Iterable of MongoDatabase types, each of which corresponds to
159+
a name in the databases array of the `listDatabases` command result. This method MAY be named `listMongoDatabases`.
160+
161+
Any MongoDatabase objects returned by this method SHOULD inherit the same MongoClient options that would otherwise be
162+
inherited by selecting an individual MongoDatabase through MongoClient (e.g. read preference, write concern).
163+
164+
Drivers SHOULD specify the `nameOnly` option when executing the `listDatabases` command for this method.
165+
166+
Drivers SHOULD support the `filter`, `authorizedDatabases` and `comment` options when implementing this method.
167+
168+
### Replica Sets
169+
170+
The `listDatabases` command may be run on a secondary node. Drivers MUST run the `listDatabases` command only on the
171+
primary node in replica set topology, unless directly connected to a secondary node in Single topology.
172+
173+
## Test Plan
174+
175+
### Test Environments
176+
177+
The test plan should be executed against the following servers:
178+
179+
- Standalone
180+
- Replica set primary
181+
- Replica set secondary
182+
- Sharding router (i.e. mongos)
183+
184+
### Test Cases
185+
186+
The following scenarios should be run for each test environment:
187+
188+
- Execute the method to enumerate full database information (e.g. `listDatabases()`)
189+
- Verify that the method returns an Iterable of Document types
190+
- Verify that all databases on the server are present in the result set
191+
- Verify that the result set does not contain duplicates
192+
- Execute the method to enumerate database names (e.g. `listDatabaseNames()`)
193+
- Verify that the method returns an Iterable of strings
194+
- Verify that all databases on the server are present in the result set
195+
- Verify that the result set does not contain duplicates
196+
- Execute the method to enumerate MongoDatabase objects (e.g. `listMongoDatabases()`)
197+
- Verify that the method returns an Iterable of MongoDatabase objects
198+
- Verify that all databases on the server are present in the result set
199+
- Verify that the result set does not contain duplicates
200+
201+
## Motivation for Change
202+
203+
Although most drivers provide a `listDatabases` command helper in their API, there was previously no spec for a database
204+
enumeration. MongoDB 3.6 introduced a `nameOnly` option to the `listDatabases` database command. The driver API should
205+
to be expanded to support this option.
206+
207+
## Design Rationale
208+
209+
The design of this specification is inspired by the [Collection Enumeration](./enumerate-collections.rst) and
210+
[Index Enumeration](./enumerate-indexes.rst) specifications. Since most drivers already implement a `listDatabases`
211+
command helper in some fashion, this spec is flexible when it comes to existing APIs.
212+
213+
## Backwards Compatibility
214+
215+
There should be no backwards compatibility concerns. This specification merely deals with how to enumerate databases in
216+
future versions of MongoDB and allows flexibility for existing driver APIs.
217+
218+
## Reference Implementation
219+
220+
TBD
221+
222+
## Q & A
223+
224+
### Why is reporting the total size of all databases optional?
225+
226+
Although the `listDatabases` command provides two results, a `databases` array and `totalSize` integer, the array of
227+
database information documents is the primary result. Returning a tuple or composite result type from a `listDatabases`
228+
driver method would complicate the general use case, as opposed to an optional output argument (if supported by the
229+
language). Furthermore, the `totalSize` value can be calculated client-side by summing all `sizeOnDisk` fields in the
230+
array of database information documents.
231+
232+
## Changelog
233+
234+
- 2024-07-26: Migrated from reStructuredText to Markdown. Removed note that applied to pre-3.6 servers.
235+
236+
- 2022-10-05: Remove spec front matter and reformat changelog. Also reverts the\
237+
minimum server version to 3.6, which is
238+
where `nameOnly` and `filter` options were first introduced for `listDatabases`.
239+
240+
- 2022-08-17: Clarify the behavior of comment on pre-4.4 servers.
241+
242+
- 2022-02-01: Support comment option in listDatabases command
243+
244+
- 2022-01-19: Require that timeouts be applied per the client-side operations timeout spec.
245+
246+
- 2019-11-20: Support authorizedDatabases option in listDatabases command
247+
248+
- 2017-10-30: Support filter option in listDatabases command

0 commit comments

Comments
 (0)