-
Notifications
You must be signed in to change notification settings - Fork 1.7k
/
Copy pathMongo.startSession.txt
124 lines (82 loc) · 3.66 KB
/
Mongo.startSession.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
====================
Mongo.startSession()
====================
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
Definition
----------
.. method:: Mongo.startSession(<options>)
Starts a :ref:`session <sessions>` for the connection.
:binary:`~bin.mongosh` assigns the session ID to commands associated
with the session.
.. |dbcommand| replace:: :dbcommand:`startSession` command
.. include:: /includes/fact-mongosh-shell-method-alt
.. include:: /includes/client-sessions-reuse.rst
The :method:`~Mongo.startSession()` method can take a document with
session options. The options available are:
.. list-table::
:header-rows: 1
:widths: 20 80
* - Field
- Description
* - causalConsistency
- Boolean. Enables or disables :ref:`causal consistency
<causal-consistency>` for the session.
:method:`Mongo.startSession()` enables ``causalConsistency``
by default. Mutually exclusive with ``snapshot``.
After starting a session, you cannot modify its
``causalConsistency`` setting.
The session may have causal consistency enabled even
though the :method:`Mongo` connection object may have
causal consistency disabled or vice versa. To set causal
consistency on the connection object, see
:method:`Mongo.setCausalConsistency()`.
* - readConcern
- Document. Specifies the :ref:`read concern <read-concern>`.
To modify the setting after starting a session, see
:method:`Session.getOptions().setReadConcern()
<Session.getOptions()>`.
* - readPreference
- Document. Specifies the :ref:`read preference <read-preference>`.
The readPreference document contains the ``mode`` field and
the optional ``tags`` field:
.. code-block:: javascript
{ mode: <string>, tags: <array> }
To modify the setting after starting a session, see
:method:`Session.getOptions().setReadPreference()
<Session.getOptions()>`.
* - retryWrites
- Boolean. Enables or disables the ability to retry writes upon
encountering transient network errors.
If you start :binary:`~bin.mongosh` with the
:option:`--retryWrites <mongosh --retryWrites>` option, ``retryWrites`` is enabled by
default for :method:`Mongo.startSession()`.
After starting a session, you cannot modify its
``retryWrites`` setting.
* - snapshot
- Boolean. Enables :ref:`snapshot reads <read-concern-snapshot>`
for the session for MongoDB 5.0+ deployments. Mutually
exclusive with ``causalConsistency``.
* - writeConcern
- Document. Specifies the :ref:`write concern <write-concern>`.
To modify the setting after starting a session, see
:method:`Session.getOptions().setWriteConcern()
<Session.getOptions()>`.
Compatibility
-------------
.. |command| replace:: method
This method is available in deployments hosted in the following environments:
.. include:: /includes/fact-environments-atlas-only.rst
.. include:: /includes/fact-environments-atlas-support-all.rst
.. include:: /includes/fact-environments-onprem-only.rst
Examples
--------
The following starts a session with causal consistency and retryable
writes enabled on the :method:`Mongo` connection object associated with
:binary:`~bin.mongosh`'s global ``db`` variable:
.. code-block:: javascript
db = db.getMongo().startSession({retryWrites: true, causalConsistency: true}).getDatabase(db.getName());