Skip to content

Commit fb87726

Browse files
nbbeekennbbeeken
committed
DRIVERS-2533: runCommand specification
1 parent 6018dda commit fb87726

File tree

2 files changed

+184
-0
lines changed

2 files changed

+184
-0
lines changed

‎source/run-command/run-command.rst‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
===========
2+
Run Command
3+
===========
4+
5+
:Title: Run Command
6+
:Status: Implementing
7+
:Minimum Server Version: N/A
8+
9+
.. contents::
10+
11+
--------
12+
13+
Abstract
14+
========
15+
This specification defines requirements and behaviors for drivers' run command and related APIs.
16+
17+
18+
META
19+
====
20+
21+
The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”,
22+
“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this
23+
document are to be interpreted as described in `RFC 2119
24+
<https://www.ietf.org/rfc/rfc2119.txt>`_.
25+
26+
Specification
27+
=============
28+
29+
-----
30+
Terms
31+
-----
32+
Command
33+
A structure representing a BSON document that has a shape matching a supported MongoDB operation.
34+
35+
---------------------------
36+
Implementation requirements
37+
---------------------------
38+
39+
All drivers MAY offer the operations defined in the following sections.
40+
This does not preclude a driver from offering more.
41+
42+
--------------
43+
``runCommand``
44+
--------------
45+
46+
The following represents how a runCommand API SHOULD be exposed.
47+
48+
.. code:: typescript
49+
50+
interface Db {
51+
/**
52+
* Takes an argument representing an arbitrary BSON document and executes it against the server.
53+
*/
54+
runCommand(command: BSONDocument, options: RunCommandOptions): BSONDocument;
55+
}
56+
57+
interface RunCommandOptions {
58+
/**
59+
* An optional readPreference setting to apply to server selection logic.
60+
* Also to apply to the command document as the $readPreference global command argument.
61+
*
62+
* @defaultValue primary
63+
*
64+
* @see ../message/OP_MSG.rst#global-command-arguments
65+
* @see https://www.mongodb.com/docs/manual/core/read-preference/
66+
*/
67+
readPreference?: ReadPreference;
68+
69+
/**
70+
* An optional explicit client session.
71+
* The associated logical session id (`lsid`) will be applied to the command.
72+
*
73+
* @see ../sessions/driver-sessions.rst#sending-the-session-id-to-the-server-on-all-commands
74+
* @see https://www.mongodb.com/docs/manual/core/read-isolation-consistency-recency/#std-label-sessions
75+
*/
76+
session?: ClientSession;
77+
78+
/**
79+
* An optional duration the command should be permitted to run for.
80+
*
81+
* @see ../client-side-operations-timeout/client-side-operations-timeout.rst
82+
*/
83+
timeoutMS?: number;
84+
}
85+
86+
Deviations
87+
^^^^^^^^^^
88+
89+
* Drivers MAY rename their API to match the language syntax.
90+
91+
RunCommand implementation details
92+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
93+
94+
RunCommand provides a way to access MongoDB server commands directly without requiring a driver to implement a bespoke helper.
95+
The API is intended to take a document from a user, apply a number of common driver internal concerns before forwarding the command to a server.
96+
In general, a driver SHOULD avoid inspecting or modifying the user's command document in an effort to remain forward compatible with any potential server commands.
97+
98+
Drivers that have historically modified user input SHOULD strive to instead clone so modifications do not impact reusing the same input command document.
99+
100+
OP_MSG
101+
""""""
102+
103+
The ``$db`` global command argument MUST be sent on the command sent to the server and it MUST correspond to the database name the runCommand API was invoked on.
104+
105+
* See OP_MSG's section on `Global Command Arguments <https://github.com/mongodb/specifications/blob/master/source/message/OP_MSG.rst#global-command-arguments>`_
106+
107+
ReadPreference
108+
""""""""""""""
109+
110+
A driver's runCommand implementation MUST assume all commands are read operations.
111+
To facilitate selecting the server the command should be sent to a driver's runCommand MUST accept an optional Read Preference option.
112+
113+
* See Server Selection's section on `Use of read preferences with commands <https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.rst#use-of-read-preferences-with-commands>`_
114+
115+
If the provided Read Preference is NOT primary, the final command document MUST include the ``$readPreference`` global command argument.
116+
117+
* See OP_MSG's section on `Global Command Arguments <https://github.com/mongodb/specifications/blob/master/source/message/OP_MSG.rst#global-command-arguments>`_
118+
119+
Driver Sessions
120+
"""""""""""""""
121+
122+
A driver's runCommand API MUST provide an optional session option to support explicit sessions and transactions.
123+
Every ClientSession has a corresponding Logical Session ID representing the server side session ID.
124+
The LSID MUST be included under ``lsid`` in the final command sent to the server without modifying user input.
125+
126+
* See Driver Sessions' section on `Sending the session ID to the server on all commands <https://github.com/mongodb/specifications/blob/master/source/sessions/driver-sessions.rst#sending-the-session-id-to-the-server-on-all-commands>`_
127+
128+
Transactions
129+
""""""""""""
130+
131+
If RunCommand is used within a Transaction the read preference MUST be sourced from the Transaction's options.
132+
The final command sent to the server MUST include the transaction specific fields, the following is a summary:
133+
134+
* If ``runCommand`` is executing within a transaction:
135+
136+
* ``autocommit`` - The autocommit flag MUST be set to false.
137+
* ``txnNumber`` - MUST be set.
138+
139+
* If ``runCommand`` is the first operation of the transaction:
140+
141+
* ``startTransaction`` - MUST be set to true.
142+
* ``readConcern`` - MUST be set to the Transaction's readConcern setting if it is NOT the default.
143+
144+
* See Transaction's section on `Generic RunCommand helper within a transaction <https://github.com/mongodb/specifications/blob/DRIVERS-2533-runCursorCommand/source/transactions/transactions.rst#generic-runcommand-helper-within-a-transaction>`_
145+
146+
ReadConcern and WriteConcern
147+
""""""""""""""""""""""""""""
148+
149+
A RunCommand API MUST NOT support either Read Concern nor Write Concern options.
150+
Additionally, unless within a transaction the final command MUST not have any Read Concern nor Write Concern fields applied that may be inherited from client, database, or collection options.
151+
152+
* See Read Concern's section on `Generic Command Method <https://github.com/mongodb/specifications/blob/master/source/read-write-concern/read-write-concern.rst#generic-command-method>`_
153+
* See Write Concern's section on `Generic Command Method <https://github.com/mongodb/specifications/blob/master/source/read-write-concern/read-write-concern.rst#generic-command-method-1>`_
154+
155+
Retryability
156+
""""""""""""
157+
158+
All commands passed to runCommand are considered non-retryable reads.
159+
Drivers MUST NOT inspect the command to determine if it is a write and MUST NOT attach a transaction ID.
160+
161+
* See Retryable Reads' section on `Unsupported Read Operations <https://github.com/mongodb/specifications/blob/master/source/retryable-reads/retryable-reads.rst#unsupported-read-operations>`_
162+
* See Retryable Writes' section on `Behavioral Changes for Write Commands <https://github.com/mongodb/specifications/blob/master/source/retryable-writes/retryable-writes.rst#behavioral-changes-for-write-commands>`_
163+
164+
Stable API
165+
""""""""""
166+
167+
The final command MUST attach stable API fields as configured on the MongoClient.
168+
169+
* See Stable API's section on `Generic Command Helper Behaviour <https://github.com/mongodb/specifications/blob/master/source/versioned-api/versioned-api.rst#generic-command-helper>`_
170+
171+
Client Side Operations Timeout
172+
""""""""""""""""""""""""""""""
173+
174+
A driver's runCommand API MUST provide an optional timeoutMS option to support client side operations timeout.
175+
Drivers MUST NOT attempt to check the command document for the presence of a ``maxTimeMS`` field.
176+
Drivers MUST document the behavior of runCommand if a ``maxTimeMS`` field is already set on the command (ex. overwrites the field or not).
177+
178+
* See Client Side Operations Timeout's section on `runCommand <https://github.com/mongodb/specifications/blob/master/source/client-side-operations-timeout/client-side-operations-timeout.rst#runcommand>`_
179+
* See Client Side Operations Timeout's section on `runCommand behavior <https://github.com/mongodb/specifications/blob/master/source/client-side-operations-timeout/client-side-operations-timeout.rst#runcommand-behavior>`_
180+
181+
Changelog
182+
=========
183+
184+
:2023-03-28: Add run command specification.

‎source/run-command/tests/README.rst‎

Whitespace-only changes.

0 commit comments

Comments
 (0)