-
Notifications
You must be signed in to change notification settings - Fork 1.7k
/
transactions-production-consideration.txt
297 lines (208 loc) · 9.89 KB
/
transactions-production-consideration.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
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
.. _production-considerations:
=========================
Production Considerations
=========================
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: twocols
The following page lists some production considerations for running
transactions. These apply whether you run transactions on replica sets
or sharded clusters. For running transactions on sharded clusters, see
also the :doc:`/core/transactions-sharded-clusters` for additional
considerations that are specific to sharded clusters.
Availability
------------
- MongoDB supports multi-document transactions on replica sets.
- Distributed transactions add support for multi-document transactions on
sharded clusters and incorporates the existing support for
multi-document transactions on replica sets.
.. note:: Distributed Transactions and Multi-Document Transactions
The two terms are synonymous. Distributed transactions refer to
multi-document transactions on sharded clusters and replica sets.
Multi-document transactions (whether on sharded clusters or replica sets) are
also known as distributed transactions.
Feature Compatibility
---------------------
To use transactions, the :ref:`featureCompatibilityVersion <view-fcv>`
for all members of the deployment must be at least:
.. list-table::
:header-rows: 1
* - Deployment
- Minimum ``featureCompatibilityVersion``
* - Replica Set
- ``4.0``
* - Sharded Cluster
- ``4.2``
To check the fCV for a member, connect to the member and run the
following command:
.. code-block:: javascript
db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )
For more information, see the
:dbcommand:`setFeatureCompatibilityVersion` reference page.
.. _transaction-limit:
Runtime Limit
-------------
.. note::
To configure maximum transaction lifetimes in {+atlas+},
see :atlas:`Set Transaction Lifetime </cluster-additional-settings/#set-transaction-lifetime>`
in the Atlas documentation.
By default, a transaction must have a runtime of less than one minute.
You can modify this limit using
:parameter:`transactionLifetimeLimitSeconds` for the
:binary:`~bin.mongod` instances. For sharded clusters, the parameter
must be modified for all shard replica set members. Transactions that
exceeds this limit are considered expired and will be aborted by a
periodic cleanup process.
For sharded clusters, you can also specify a ``maxTimeMS`` limit on
``commitTransaction``. For more information, see :ref:`Sharded Clusters
Transactions Time Limit <transactions-sharded-clusters-time-limit>`.
.. _txn-oplog-size-limit:
Oplog Size Limit
----------------
MongoDB creates as many oplog entries as necessary to the encapsulate all write
operations in a transaction, instead of a single entry for all write operations
in the transaction. This removes the 16MB total size limit for a transaction
imposed by the single oplog entry for all its write operations. Although the
total size limit is removed, each oplog entry still must be within the
BSON document size limit of 16MB.
WiredTiger Cache
----------------
To prevent storage cache pressure from negatively impacting the
performance:
- When you abandon a transaction, abort the transaction.
- When you encounter an error during individual operation in the
transaction, abort and retry the transaction.
The :parameter:`transactionLifetimeLimitSeconds` also ensures that
expired transactions are aborted periodically to relieve storage cache
pressure.
.. note::
If you have an uncommitted transaction that causes excessive pressure
on the :ref:`WiredTiger cache <storage-wiredtiger>`, the transaction
aborts and returns a :term:`write conflict` error.
If a transaction is too large to ever fit in the WiredTiger cache,
the transaction aborts and returns a ``TransactionTooLargeForCache``
error.
Transactions and Security
-------------------------
- If running with :ref:`access control <authorization>`, you must
have :ref:`privileges <built-in-roles>` for the
:ref:`operations in the transaction <transactions-operations>`.
- If running with :ref:`auditing <auditing>`, operations in an
aborted transaction are still audited. However, there is no audit
event that indicates that the transaction aborted.
.. _transactions-disabled-wcmajority:
Shard Configuration Restriction
-------------------------------
.. include:: /includes/extracts/transactions-shards-wcmajority-disabled.rst
Sharded Clusters and Arbiters
-----------------------------
.. include:: /includes/extracts/transactions-arbiters.rst
.. _txns-locks:
Acquiring Locks
---------------
By default, transactions wait up to ``5`` milliseconds to acquire locks
required by the operations in the transaction. If the transaction
cannot acquire its required locks within the ``5`` milliseconds, the
transaction aborts.
Transactions release all locks upon abort or commit.
.. include:: /includes/extracts/transactions-operations-catalog-tip.rst
Lock Request Timeout
~~~~~~~~~~~~~~~~~~~~
.. note::
{+atlas+} clusters restrict the use of the :dbcommand:`setParameter`
command. For more information, see :ref:`<unsupported-commands>` in
the Atlas documentation.
To modify your Atlas cluster parameters, contact
:atlas:`Atlas Support </support>`.
You can use the :parameter:`maxTransactionLockRequestTimeoutMillis`
parameter to adjust how long transactions wait to acquire locks.
Increasing :parameter:`maxTransactionLockRequestTimeoutMillis` allows
operations in the transactions to wait the specified time to acquire
the required locks. This can help obviate transaction aborts on
momentary concurrent lock acquisitions, like fast-running metadata
operations. However, this could possibly delay the abort of deadlocked
transaction operations.
You can also use operation-specific timeout by setting
:parameter:`maxTransactionLockRequestTimeoutMillis` to ``-1``.
.. _txn-prod-considerations-ddl:
Pending DDL Operations and Transactions
---------------------------------------
If a multi-document transaction is in progress, new DDL operations that
affect the same database(s) or collection(s) wait behind the
transaction. While these pending DDL operations exist, new transactions
that access the same database(s) or collection(s) as the pending DDL
operations cannot obtain the required locks and and will abort after
waiting :parameter:`maxTransactionLockRequestTimeoutMillis`. In
addition, new non-transaction operations that access the same
database(s) or collection(s) will block until they reach their
``maxTimeMS`` limit.
Consider the following scenarios:
DDL Operation That Requires a Collection Lock
While an in-progress transaction is performing various CRUD operations
on the ``employees`` collection in the ``hr`` database, an
administrator issues the :method:`db.collection.createIndex()` DDL
operation against the ``employees`` collection.
:method:`~db.collection.createIndex()` requires an exclusive
collection lock on the collection.
Until the in-progress transaction completes, the
:method:`~db.collection.createIndex()` operation must wait to obtain
the lock. Any new transaction that affects the ``employees``
collection and starts while the :method:`~db.collection.createIndex()`
is pending must wait until after
:method:`~db.collection.createIndex()` completes.
The pending :method:`~db.collection.createIndex()` DDL operation does
not affect transactions on other collections in the ``hr`` database.
For example, a new transaction on the ``contractors`` collection in
the ``hr`` database can start and complete as normal.
DDL Operation That Requires a Database Lock
While an in-progress transaction is performing various CRUD operations
on the ``employees`` collection in the ``hr`` database, an
administrator issues the :dbcommand:`renameCollection` DDL operation
to rename the ``vendors.contractors`` collection to
``hr.contractors``. ``renameCollection`` requires a database lock on
the target database (``hr``) when it differs from the source database
(``vendors``).
Until the in-progress transaction completes, the
``renameCollection`` operation must wait to obtain the
lock. Any new transaction that affects the ``hr`` database or *any*
of its collections and starts while the ``renameCollection`` is
pending must wait until after ``renameCollection`` completes.
In either scenario, if the DDL operation remains pending for more than
:parameter:`maxTransactionLockRequestTimeoutMillis`, pending
transactions waiting behind that operation abort. That is, the value of
:parameter:`maxTransactionLockRequestTimeoutMillis` must at least cover
the time required for the in-progress transaction *and* the pending DDL
operation to complete.
.. seealso::
- :ref:`transactions-write-conflicts`
- :ref:`transactions-stale-reads`
- :ref:`faq-concurrency-database-lock`
- :ref:`faq-concurrency-collection-lock`
.. _transactions-write-conflicts:
In-progress Transactions and Write Conflicts
--------------------------------------------
.. include:: /includes/extracts/transactions-write-conflict.rst
.. seealso::
- :ref:`txns-locks`
- :ref:`txn-prod-considerations-ddl`
- :data:`$currentOp output <$currentOp.prepareReadConflicts>`
.. _transactions-stale-reads:
In-progress Transactions and Stale Reads
----------------------------------------
.. include:: /includes/extracts/transactions-stale-reads.rst
In-progress Transactions and Chunk Migration
--------------------------------------------
.. include:: /includes/extracts/transactions-chunk-migration.rst
.. seealso::
:serverstatus:`shardingStatistics.countDonorMoveChunkLockTimeout`
.. _transactions-prod-consideration-outside-reads:
Outside Reads During Commit
---------------------------
.. include:: /includes/extracts/transactions-multi-shard-block-external-reads.rst
Additional Information
----------------------
.. seealso::
:doc:`/core/transactions-sharded-clusters`