Production Considerations

The following page lists some production considerations for runningtransactions. These apply whether you run transactions on replica setsor sharded clusters. For running transactions on sharded clusters, seealso the Production Considerations (Sharded Clusters) for additionalconsiderations that are specific to sharded clusters.

Availability

• In version 4.0, MongoDB supports multi-document transactions onreplica sets.

• In version 4.2, MongoDB introduces distributed transactions,which adds support for multi-document transactions on shardedclusters and incorporates the existing support formulti-document transactions on replica sets.

To use transactions on MongoDB 4.2 deployments(replica sets andsharded clusters), clients must use MongoDB drivers updated forMongoDB 4.2.

Feature Compatibility

To use transactions, the featureCompatibilityVersionfor all members of the deployment must be at least:

To check the fCV for a member, connect to the member and run thefollowing command:

db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )

For more information, see thesetFeatureCompatibilityVersion reference page.

Runtime Limit

By default, a transaction must have a runtime of less than one minute.You can modify this limit usingtransactionLifetimeLimitSeconds for themongod instances. For sharded clusters, the parametermust be modified for all shard replica set members. Transactions thatexceeds this limit are considered expired and will be aborted by aperiodic cleanup process.

For sharded clusters, you can also specify a maxTimeMS limit oncommitTransaction. For more information, see Sharded ClustersTransactions Time Limit.

Oplog Size Limit

• Starting in version 4.2,
• MongoDB creates as many oplog entries as necessary to theencapsulate all write operations in a transaction, instead of asingle entry for all write operations in the transaction. Thisremoves the 16MB total size limit for a transaction imposed by thesingle oplog entry for all its write operations. Although the totalsize limit is removed, each oplog entry still must be within theBSON document size limit of 16MB.
• In version 4.0,
• MongoDB creates a single oplog (operations log) entry at the time of commit if thetransaction contains any write operations. That is, the individualoperations in the transactions do not have a corresponding oplogentry. Instead, a single oplog entry contains all of the writeoperations within a transaction. The oplog entry for the transactionmust be within the BSON document size limit of 16MB.

WiredTiger Cache

To prevent storage cache pressure from negatively impacting theperformance:

• When you abandon a transaction, abort the transaction.
• When you encounter an error during individual operation in thetransaction, abort and retry the transaction.

The transactionLifetimeLimitSeconds also ensures thatexpired transactions are aborted periodically to relieve storage cachepressure.

Transactions and Security

• If running with access control, you musthave privileges for theoperations in the transaction.
• If running with auditing, operations in anaborted transaction are still audited. However, there is no auditevent that indicates that the transaction aborted.

Shard Configuration Restriction

You cannot run transactions on a sharded cluster that has a shardwith writeConcernMajorityJournalDefault set to false(such as a shard with a voting member that uses the in-memorystorage engine).

Sharded Clusters and Arbiters

Transactions whose write operations span multiple shards will errorand abort if any transaction operation reads from or writes to ashard that contains an arbiter.

See also 3-Member Primary-Secondary-Arbiter Architecture for transaction restrictions on shards thathave disabled read concern majority.

3-Member Primary-Secondary-Arbiter Architecture

For a three-member replica set with a primary-secondary-arbiter (PSA)architecture or a sharded cluster with a three-member PSA shards, youmay have disabled read concern “majority” to avoid cache pressure.

• On sharded clusters,
• • If a transaction involves a shard that has disabled readconcern “majority”, you cannotuse read concern "snapshot" for the transaction.You can only use read concern "local" or"majority" for the transaction. If you use readconcern "snapshot", the transaction errors andaborts.

readConcern level 'snapshot' is not supported in sharded clusters when enableMajorityReadConcern=false.

• Transactions whose write operations span multiple shards willerror and abort if any of the transaction’s read or writeoperations involves a shard that has disabled read concern"majority".

• On replica set,
• You can specify read concern "local" or"majority" or "snapshot" even inthe replica set has disabled read concern “majority”.

However, if you are planning to transition to a sharded cluster withdisabled read concern majority shards, you may wish to avoid usingread concern "snapshot".

Tip

To check if read concern “majority” is disabled, You can rundb.serverStatus() on the mongod instancesand check the storageEngine.supportsCommittedReadsfield. If false, read concern “majority” is disabled.

See also

• —enableMajorityReadConcern false
• replication.enableMajorityReadConcern: false.

Acquiring Locks

By default, transactions wait up to 5 milliseconds to acquire locksrequired by the operations in the transaction. If the transactioncannot acquire its required locks within the 5 milliseconds, thetransaction aborts.

Transactions release all locks upon abort or commit.

Tip

When creating or dropping a collection immediately beforestarting a transaction, if the collection is accessed within thetransaction, issue the create or drop operation with writeconcern "majority" to ensure that the transactioncan acquire the required locks.

Lock Request Timeout

You can use the maxTransactionLockRequestTimeoutMillisparameter to adjust how long transactions wait to acquire locks.Increasing maxTransactionLockRequestTimeoutMillis allowsoperations in the transactions to wait the specified time to acquirethe required locks. This can help obviate transaction aborts onmomentary concurrent lock acquisitions, like fast-running metadataoperations. However, this could possibly delay the abort of deadlockedtransaction operations.

You can also use operation-specific timeout by settingmaxTransactionLockRequestTimeoutMillis to -1.

Pending DDL Operations and Transactions

Multi-document transactions acquire exclusive locks on the collections whichthey access. New DDL operations that require locks on those collections or theirparent databases must wait until the transaction releases its locks. While thesepending DDL operations exist, new transactions that access the samecollection(s) as the pending DDL operations cannot obtain the required locks andand will abort after waitingmaxTransactionLockRequestTimeoutMillis. In addition, newnon-transaction operations that access the same collection(s) will block untilthey 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 theemployees collection in the hr database, an administrator issues thedb.collection.createIndex() DDL operation against theemployees collection. createIndex() requires anexclusive collection lock on the collection.

Until the in-progress transaction completes, thecreateIndex() operation must wait to obtainthe lock. Any new transaction that affects the employeescollection and starts while the createIndex()is pending must wait until aftercreateIndex() completes.

The pending createIndex() DDL operation does notaffect transactions on other collections in the hr database. For example,a new transaction on the contractors collection in the hr database canstart and complete as normal.

• DDL Operation That Requires a Database Lock
• While an in-progress transaction is performing various CRUD operations on theemployees collection in the hr database, an administrator issues thecollMod DDL operation against the contractors collection inthe same database. collMod requires a database lock onthe parent hr database.

Until the in-progress transaction completes, the collModoperation must wait to obtain the lock. Any new transaction thataffects the hr database or any of its collections and startswhile the collMod is pending must wait until aftercollMod completes.

In either scenario, if the DDL operation remains pending for more thanmaxTransactionLockRequestTimeoutMillis, pendingtransactions waiting behind that operation abort. That is, the value ofmaxTransactionLockRequestTimeoutMillis must at least coverthe time required for the in-progress transaction and the pending DDLoperation to complete.

See also

• In-progress Transactions and Write Conflicts
• In-progress Transactions and Stale Reads
• Which administrative commands lock the database?
• Which administrative commands lock a collection?

In-progress Transactions and Write Conflicts

If a transaction is in progress and a writeoutside the transaction modifies a document that an operation in thetransaction later tries to modify, the transaction aborts because ofa write conflict.

If a transaction is in progress and has taken a lockto modify a document, when a write outside the transaction tries tomodify the same document, the write waits until the transaction ends.

See also

• Acquiring Locks
• Pending DDL Operations and Transactions
• $currentOp output

In-progress Transactions and Stale Reads

Read operations inside a transaction can return stale data. That is,read operations inside a transaction are not guaranteed to seewrites performed by other committed transactions ornon-transactional writes. Forexample, consider the following sequence: 1) a transaction isin-progress 2) a write outside the transaction deletes a document 3)a read operation inside the transaction is able to read thenow-deleted document since the operation is using a snapshot frombefore the write.

To avoid stale reads inside transactions for a single document, youcan use the db.collection.findOneAndUpdate() method. Forexample:

session.startTransaction( { readConcern: { level: "snapshot" }, writeConcern: { w: "majority" } } );
 
employeesCollection = session.getDatabase("hr").employees;
 
employeeDoc = employeesCollection.findOneAndUpdate(
   { _id: 1, employee: 1, status: "Active" },
   { $set: { employee: 1 } },
   { returnNewDocument: true }
);

• If the employee document has changed outside the transaction, thenthe transaction aborts.
• If the employee document has not changed, the transaction returnsthe document and locks the document.

In-progress Transactions and Chunk Migration

Chunk migration acquiresexclusive collection locks during certain stages.

If an ongoing transaction has a lock on a collection and a chunkmigration that involves that collection starts, these migration stagesmust wait for the transaction to release the locks on the collection,thereby impacting the performance of chunk migrations.

If a chunk migration interleaves with a transaction (for instance, if atransaction starts while a chunk migration is already in progress andthe migration completes before the transaction takes a lock on thecollection), the transaction errors during the commit and aborts.

Depending on how the two operations interleave, some sample errorsinclude (the error messages have been abbreviated):

• an error from cluster data placement change … migration commit in progress for <namespace>
• Cannot find shardId the chunk belonged to at cluster time …

See also

shardingStatistics.countDonorMoveChunkLockTimeout

Outside Reads During Commit

During the commit for a transaction, outside read operations may tryto read the same documents that will be modified by the transaction.If the transaction writes to multiple shards, then during the commitattempt across the shards

• Outside reads that use read concern snapshot or"linearizable", or are part of causally consistentsessions (i.e. include afterClusterTime)wait for all writes of a transaction to be visible.
• Outside reads using other read concerns do not wait for all writesof a transaction to be visible but instead read thebefore-transaction version of the documents available.

Errors

Use of MongoDB 4.0 Drivers

To use transactions on MongoDB 4.2 deployments(replica sets and shardedclusters), clients must use MongoDB drivers updated for MongoDB4.2.

On sharded clusters with multiple mongos instances,performing transactions with drivers updated for MongoDB 4.0 (insteadof MongoDB 4.2) will fail and can result in errors, including:

Note

Your driver may return a different error. Refer to your driver’sdocumentation for details.

Additional Information

See also

Production Considerations (Sharded Clusters)