Transactions
On this page
In MongoDB, an operation on a single document is atomic. Because you can use embedded documents and arrays to capture relationships between data in a single document structure instead of normalizing across multiple documents and collections, this single-document atomicity obviates the need for distributed transactions for many practical use cases.
For situations that require atomicity of reads and writes to multiple documents (in a single or multiple collections), MongoDB supports distributed transactions. With distributed transactions, transactions can be used across multiple operations, collections, databases, documents, and shards.
Transactions API
➤ Use the Select your language drop-down menu in the upper-right to set the language of the following example.
Tip
See also:
For an example in mongosh
, see
mongosh
Example.
Transactions and Atomicity
For situations that require atomicity of reads and writes to multiple documents (in a single or multiple collections), MongoDB supports distributed transactions, including transactions on replica sets and sharded clusters.
Distributed transactions are atomic. They provide an "all-or-nothing" proposition:
When a transaction commits, all data changes made in the transaction are saved and visible outside the transaction. That is, a transaction will not commit some of its changes while rolling back others.
Until a transaction commits, the data changes made in the transaction are not visible outside the transaction.
However, when a transaction writes to multiple shards, not all outside read operations need to wait for the result of the committed transaction to be visible across the shards. For example, if a transaction is committed and write 1 is visible on shard A but write 2 is not yet visible on shard B, an outside read at read concern
"local"
can read the results of write 1 without seeing write 2.When a transaction aborts, all data changes made in the transaction are discarded without ever becoming visible. For example, if any operation in the transaction fails, the transaction aborts and all data changes made in the transaction are discarded without ever becoming visible.
Important
In most cases, a distributed transaction incurs a greater performance cost over single document writes, and the availability of distributed transactions should not be a replacement for effective schema design. For many scenarios, the denormalized data model (embedded documents and arrays) will continue to be optimal for your data and use cases. That is, for many scenarios, modeling your data appropriately will minimize the need for distributed transactions.
For additional transactions usage considerations (such as runtime limit and oplog size limit), see also Production Considerations.
Tip
See also:
Transactions and Operations
Distributed transactions can be used across multiple operations, collections, databases, documents, and shards.
For transactions:
You can create collections and indexes in transactions. For details, see Create Collections and Indexes In a Transaction
The collections used in a transaction can be in different databases.
Note
You cannot create new collections in cross-shard write transactions. For example, if you write to an existing collection in one shard and implicitly create a collection in a different shard, MongoDB cannot perform both operations in the same transaction.
You cannot write to capped collections.
You cannot use read concern
"snapshot"
when reading from a capped collection. (Starting in MongoDB 5.0)You cannot read/write to collections in the
config
,admin
, orlocal
databases.You cannot write to
system.*
collections.You cannot return the supported operation's query plan using
explain
or similar commands.
For cursors created outside of a transaction, you cannot call
getMore
inside the transaction.For cursors created in a transaction, you cannot call
getMore
outside the transaction.
You cannot specify
killCursors
as the first operation in a transaction.
For a list of operations not supported in transactions, see Restricted Operations.
Tip
When creating or dropping a collection immediately before
starting a transaction, if the collection is accessed within the
transaction, issue the create or drop operation with write
concern "majority"
to ensure that the transaction
can acquire the required locks.
Tip
See also:
Create Collections and Indexes In a Transaction
You can perform the following operations inside of a distributed transaction as long as the transaction is not a cross-shard write transaction:
Create collections.
Create indexes on new empty collections created earlier in the same transaction.
When creating a collection inside a transaction:
You can implicitly create a collection, such as with:
an insert operation against a non-existing collection, or
an update/findAndModify operation with
upsert: true
against a non-existing collection.
You can explicitly create a collection using the
create
command or its helperdb.createCollection()
.
When creating an index inside a transaction [1], the index to create must be on either:
a non-existing collection. The collection is created as part of the operation.
a new empty collection created earlier in the same transaction.
[1] | You can also run db.collection.createIndex() and
db.collection.createIndexes() on existing indexes to check
for existence. These operations return successfully without creating
the index. |
Restrictions
You cannot create new collections in cross-shard write transactions. For example, if you write to an existing collection in one shard and implicitly create a collection in a different shard, MongoDB cannot perform both operations in the same transaction.
You cannot use the
$graphLookup
stage within a transaction while targeting a sharded collection.For explicit creation of a collection or an index inside a transaction, the transaction read concern level must be
"local"
. Explicit creation is through:
Tip
See also:
Count Operation
To perform a count operation within a transaction, use the
$count
aggregation stage or the $group
(with a
$sum
expression) aggregation stage.
MongoDB drivers provide a collection-level API
countDocuments(filter, options)
as a helper method that uses the
$group
with a $sum
expression
to perform a count. The count()
API is deprecated.
mongosh
provides the
db.collection.countDocuments()
helper method that uses the
$group
with a $sum
expression to perform a
count.
Distinct Operation
To perform a distinct operation within a transaction:
For unsharded collections, you can use the
db.collection.distinct()
method/thedistinct
command as well as the aggregation pipeline with the$group
stage.For sharded collections, you cannot use the
db.collection.distinct()
method or thedistinct
command.To find the distinct values for a sharded collection, use the aggregation pipeline with the
$group
stage instead. For example:Instead of
db.coll.distinct("x")
, usedb.coll.aggregate([ { $group: { _id: null, distinctValues: { $addToSet: "$x" } } }, { $project: { _id: 0 } } ]) Instead of
db.coll.distinct("x", { status: "A" })
, use:db.coll.aggregate([ { $match: { status: "A" } }, { $group: { _id: null, distinctValues: { $addToSet: "$x" } } }, { $project: { _id: 0 } } ])
The pipeline returns a cursor to a document:
{ "distinctValues" : [ 2, 3, 1 ] } Iterate the cursor to access the results document.
Informational Operations
Informational commands, such as hello
,
buildInfo
, connectionStatus
(and their
helper methods) are allowed in transactions; however, they cannot be
the first operation in the transaction.
Restricted Operations
Changed in version 4.4.
The following operations are not allowed in transactions:
Creating new collections in cross-shard write transactions. For example, if you write to an existing collection in one shard and implicitly create a collection in a different shard, MongoDB cannot perform both operations in the same transaction.
Explicit creation of collections, e.g.
db.createCollection()
method, and indexes, e.g.db.collection.createIndexes()
anddb.collection.createIndex()
methods, when using a read concern level other than"local"
.The
listCollections
andlistIndexes
commands and their helper methods.Other non-CRUD and non-informational operations, such as
createUser
,getParameter
,count
, etc. and their helpers.
Transactions and Sessions
Transactions are associated with a session
At any given time, you can have at most one open transaction for a session.
When using the drivers, each operation in the transaction must be associated with the session. Refer to your driver specific documentation for details.
If a session ends and it has an open transaction, the transaction aborts.
Read Concern/Write Concern/Read Preference
Transactions and Read Preference
Operations in a transaction use the transaction-level read preference.
Using the drivers, you can set the transaction-level read preference at the transaction start:
If the transaction-level read preference is unset, the transaction uses the session-level read preference.
If transaction-level and the session-level read preference are unset, the transaction uses the client-level read preference. By default, the client-level read preference is
primary
.
Distributed transactions that contain
read operations must use read preference primary
. All
operations in a given transaction must route to the same member.
Transactions and Read Concern
Operations in a transaction use the transaction-level read concern. That is, any read concern set at the collection and database level is ignored inside the transaction.
You can set the transaction-level read concern at the transaction start.
If the transaction-level read concern is unset, the transaction-level read concern defaults to the session-level read concern.
If transaction-level and the session-level read concern are unset, the transaction-level read concern defaults to the client-level read concern. By default, client-level read concern is
"local"
for reads against the primary. See also:
Transactions support the following read concern levels:
"local"

Read concern
"local"
returns the most recent data available from the node but can be rolled back.For transactions on sharded cluster,
"local"
read concern cannot guarantee that the data is from the same snapshot view across the shards. If snapshot isolation is required, use"snapshot"
read concern.You can create collections and indexes inside a transaction. If explicitly creating a collection or an index, the transaction must use read concern
"local"
. If you implicitly create a collection, you can use any of the read concerns available for transactions.
"majority"

If the transaction commits with write concern "majority", read concern
"majority"
returns data that has been acknowledged by a majority of the replica set members and can't be rolled back. Otherwise, read concern"majority"
provides no guarantees that read operations read majority-committed data.For transactions on sharded cluster, read concern
"majority"
can't guarantee that the data is from the same snapshot view across the shards. If snapshot isolation is required, use read concern"snapshot"
.
"snapshot"

Read concern
"snapshot"
returns data from a snapshot of majority committed data if the transaction commits with write concern "majority".If the transaction does not use write concern "majority" for the commit, the
"snapshot"
read concern provides no guarantee that read operations used a snapshot of majority-committed data.For transactions on sharded clusters, the
"snapshot"
view of the data is synchronized across shards.
Transactions and Write Concern
Transactions use the transaction-level write concern to commit the write operations. Write operations inside transactions must be issued without explicit write concern specification and use the default write concern. At commit time, the writes are then commited using the transaction-level write concern.
Tip
Do not explicitly set the write concern for the individual write operations inside a transaction. Setting write concerns for the individual write operations inside a transaction results in an error.
You can set the transaction-level write concern at the transaction start:
If the transaction-level write concern is unset, the transaction-level write concern defaults to the session-level write concern for the commit.
If the transaction-level write concern and the session-level write concern are unset, the transaction-level write concern defaults to the client-level write concern of:
w: "majority"
in MongoDB 5.0 and later, with differences for deployments containing arbiters. See Implicit Default Write Concern.
Tip
Transactions support all write concern w values, including:
w: 1

Write concern
w: 1
returns acknowledgement after the commit has been applied to the primary.Important
When you commit with
w: 1
, your transaction can be rolled back if there is a failover.When you commit with
w: 1
write concern, transaction-level"majority"
read concern provides no guarantees that read operations in the transaction read majority-committed data.When you commit with
w: 1
write concern, transaction-level"snapshot"
read concern provides no guarantee that read operations in the transaction used a snapshot of majority-committed data.
w: "majority"

Write concern
w: "majority"
returns acknowledgement after the commit has been applied to a majority (M) of voting members, meaning the commit has been applied to the primary and (M-1) voting secondaries.When you commit with
w: "majority"
write concern, transaction-level"majority"
read concern guarantees that operations have read majority-committed data. For transactions on sharded clusters, this view of the majority-committed data is not synchronized across shards.When you commit with
w: "majority"
write concern, transaction-level"snapshot"
read concern guarantees that operations have read from a synchronized snapshot of majority-committed data.
Note
Regardless of the write concern specified for the
transaction, the commit operation for a
sharded cluster transaction includes some parts that use {w:
"majority", j: true}
write concern.
The server parameter
coordinateCommitReturnImmediatelyAfterPersistingDecision
controls when transaction commit decisions are returned to the client.
The parameter was introduced in MongDB 5.0 with a default value of
true
. In MongoDB 6.1 the default value changes to false
.
When coordinateCommitReturnImmediatelyAfterPersistingDecision
is
false
, the shard transaction coordinator
waits for all members to acknowledge a multi-document transaction commit before returning the commit decision to
the client.
If you specify a "majority"
write concern for a
multi-document transaction and the
transaction fails to replicate to the calculated majority of replica set members, then the
transaction may not immediately roll back on replica set members.
The replica set will be eventually consistent. A transaction is always applied or rolled back on all
replica set members.
Regardless of the write concern specified for the
transaction, the driver applies
w: "majority"
as the write concern when
retrying commitTransaction
.
General Information
Production Considerations
For various production considerations with using transactions, see Production Considerations. In addition, for sharded clusters, see also Production Considerations (Sharded Clusters).
Arbiters
Transactions whose write operations span multiple shards will error and abort if any transaction operation reads from or writes to a shard that contains an arbiter.
Shard Configuration Restriction
You cannot run transactions on a sharded cluster that has a shard
with writeConcernMajorityJournalDefault
set to false
(such as a shard with a voting member that uses the in-memory
storage engine).
Note
Regardless of the write concern specified for the
transaction, the commit operation for a
sharded cluster transaction includes some parts that use {w:
"majority", j: true}
write concern.
Diagnostics
MongoDB provides various transactions metrics:
Source | Returns |
---|---|
db.serverStatus() methodserverStatus command | Returns transactions metrics. |
$currentOp aggregation pipeline | Returns:
|
db.currentOp() methodcurrentOp command | Returns:
|
Includes information on slow transactions, which are transactions
that exceed the operationProfiling.slowOpThresholdMs
threshold) under the TXN log component. |
Feature Compatibility Version (fCV)
To use transactions, the featureCompatibilityVersion for all members of the deployment must be at least:
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:
db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )
For more information, see the
setFeatureCompatibilityVersion
reference page.
Storage Engines
distributed transactions are supported on replica sets and sharded clusters where:
the primary uses the WiredTiger storage engine, and
the secondary members use either the WiredTiger storage engine or the in-memory storage engines.
Note
You cannot run transactions on a sharded cluster that has a shard
with writeConcernMajorityJournalDefault
set to
false
, such as a shard with a voting member that uses the
in-memory storage engine.
Limit Critical Section Wait Time
Starting in MongoDB 5.2 (and 5.0.4):
When a query accesses a shard, a chunk migration or DDL operation may hold the critical section for the collection.
To limit the time a shard waits for a critical section within a transaction, use the
metadataRefreshInTransactionMaxWaitBehindCritSecMS
parameter.
Additional Transactions Topics
To learn more about when to use transactions and if they support your use case, see the Are Transactions Right For You? presentation from MongoDB.live 2020.