ApsaraDB for MongoDB:Transactions and Read/Write Concern

Basic information

MongoDB transaction APIs are similar to those in relational databases, so the learning curve is minimal.

The following example demonstrates a complete transaction with the startTransaction/abortTransaction/commitTransaction APIs, along with session and readConcern/writeConcern settings.

// Create collections.
db.getSiblingDB("mydb1").foo.insertOne(
    {abc: 0},
    { writeConcern: { w: "majority", wtimeout: 2000 } }
)
db.getSiblingDB("mydb2").bar.insertOne(
   {xyz: 0},
   { writeConcern: { w: "majority", wtimeout: 2000 } }
)
// Start a session.
session = db.getMongo().startSession( { readPreference: { mode: "primary" } } );
coll1 = session.getDatabase("mydb1").foo;
coll2 = session.getDatabase("mydb2").bar;
// Start a transaction.
session.startTransaction( { readConcern: { level: "local" }, writeConcern: { w: "majority" } } );
// Perform operations in the transaction.
try {
   coll1.insertOne( { abc: 1 } );
   coll2.insertOne( { xyz: 999 } );
} catch (error) {
   // Abort the transaction if an error occurs.
   session.abortTransaction();
   throw error;
}
// Commit the transaction.
session.commitTransaction();
session.endSession();

Key behaviors of transactions:

• Each transaction must be associated with a session. A session supports only one active transaction at a time. Ending a session rolls back any active transaction.

• A distributed transaction can span multiple documents, collections, and databases.

• A transaction can read its own uncommitted writes, but these writes are not visible to operations outside the transaction.

• Writes are not replicated to secondary nodes until the transaction commits. After commit, writes are automatically applied to all secondary nodes.

• Transactions lock documents they modify, blocking other operations until completion. If a lock cannot be acquired within 5 milliseconds (default), the transaction aborts with a write conflict. This timeout is controlled by the maxTransactionLockRequestTimeoutMillis parameter.

• Transactions automatically retry on transient errors such as temporary network interruptions. This retry is transparent to the client.

• A transaction running longer than 60 seconds is forcibly aborted. This timeout is controlled by the transactionLifetimeLimitSeconds parameter.

Limits

• You cannot create new collections or indexes in a distributed transaction.

• Transactions cannot write to capped collections.

• Transactions cannot use the `snapshot` read concern to read from capped collections. This limit applies to MongoDB 5.0 and later.

• In a transaction, you cannot read from or write to collections in the config/admin/local databases.

• Transactions cannot write to system collections, such as collections in the system.* format.

• Transactions do not support explain.

• You cannot use getMore inside a transaction to read cursors created outside the transaction. Similarly, you cannot use getMore outside a transaction to read cursors created inside it.

• The first operation in a transaction cannot be a command such as killCursors or hello.

• You cannot run non-CRUD commands inside a transaction. Examples include listCollections, listIndexes, createUser, getParameter, and count.

• For distributed transactions, you cannot set the writeConcernMajorityJournalDefault parameter on shards to false.

• Distributed transactions do not support shards with arbiters.

Best practices

Kernel bug risks

Long-running or oversized transactions place significant load on the WiredTiger cache. From the start of the oldest uncommitted transaction, WiredTiger must maintain data and state for all subsequent writes. Active transactions share the same snapshot, so new writes accumulate in the cache throughout the transaction's lifetime and cannot be evicted until the transaction commits or aborts. An overloaded cache (usage and dirty usage exceeding thresholds) causes database stuttering, increased latency, full CPU utilization, and potential deadlocks. Related issues: SERVER-50365 and SERVER-51281.

ApsaraDB for MongoDB recommends upgrading to MongoDB 5.0 or later for applications that heavily use transactions.

Basic information

Read Concern controls consistency and isolation with the following levels:

• "local": Default for reads against primary or secondary nodes. Reads from the local node and may return data that is later rolled back.

• "available": Default for reads against secondaries in a sharded cluster. May return data that is later rolled back. Does not check shard version and may return orphaned documents. Provides the lowest access latency.

• "majority": Reads data acknowledged by a majority of replica set members. This data will not be rolled back.

• "linearizable": The strictest level. Waits for all preceding writes to be acknowledged by a majority of nodes. Lowest performance; only available on the primary.

• "snapshot": Reads from a data snapshot acknowledged by a majority of nodes. Can be associated with a specific point in time using atClusterTime.

Usage notes:

• The latest data on a single mongod node does not necessarily represent the most recent data in the replica set, regardless of Read Concern level.

• Different Read Concern levels can be specified per operation. MongoDB 4.4+ also supports a server-side default, which operation-level settings override.

• Read Concern is ignored when reading from the local database. All data in the local database is readable regardless of the level.

• Distributed transactions support only three Read Concern levels: "local", "majority", and "snapshot".

• Causally consistent sessions must use the "majority" Read Concern level.

Best practices

Basic information

Write Concern uses the following format. Full reference: Write Concern.

{ w: <value>, j: <boolean>, wtimeout: <number> }

• Write Concern controls data persistence guarantees at these levels:

  • {w: 0}: No acknowledgment. Does not confirm completion; data loss may occur.

  • {w: 1}: Acknowledges the write in memory. Default before MongoDB 5.0. Data loss can still occur because data is not yet persisted to disk.

  • {j: true}: Journal acknowledgment. Confirms the write is flushed to the write-ahead log (WAL) on persistent storage. The write will not be lost.

  • { w: "majority" }: Majority acknowledgment. Default for MongoDB 5.0+. Waits for the write to replicate to a majority of nodes. The data will not be rolled back.

  • Replica acknowledgment: Waits for replication to a specified number of nodes before acknowledging.

  • Custom acknowledgment: You can use the settings.getLastErrorModes parameter to specify other custom acknowledgment methods using tags.

Usage notes:

• Write Concern can be specified for any write operation or transaction. If omitted, the default is used.

  Note

  In MongoDB 5.0+, the default global Write Concern for a standard three-member replica set changed from {w:1} to {w:"majority"}. This may cause performance degradation after upgrading.

• Hidden nodes, delayed nodes, and other voting nodes with a priority of 0 in a replica set can all count towards a "majority" acknowledgment.

• Different Write Concern levels can be specified per operation. MongoDB 4.4+ also supports a server-side default, which operation-level settings override.

• When you write to the local database, any specified Write Concern is ignored.

• Causally consistent sessions must use the "majority" Write Concern.

Best practices