Retryable Writes (original) (raw)
Retryable writes allow MongoDB drivers to automatically retry certain write operations a single time if they encounter network errors, or if they cannot find a healthy primary in the replica set or sharded cluster.
Retryable writes have the following requirements:
Supported Deployment Topologies
Retryable writes require a replica setor sharded cluster, and do notsupport standalone instances.
Supported Storage Engine
Retryable writes require a storage engine supporting document-level locking, such as the WiredTiger orin-memory storage engines.
3.6+ MongoDB Drivers
Clients require MongoDB drivers updated for MongoDB 3.6 or greater:
| Java 3.6+Python 3.6+C 1.9+Go 1.8+ | C# 2.5+Node 3.0+Ruby 2.5+Rust 2.1+Swift 1.2+ | Perl 2.0+PHPC 1.4+Scala 2.2+C++ 3.6.6+ |
|---|
MongoDB Version
The MongoDB version of every node in the cluster must be 3.6 or greater, and the featureCompatibilityVersion of each node in the cluster must be 3.6 or greater. SeesetFeatureCompatibilityVersion for more information on the featureCompatibilityVersion flag.
Write Acknowledgment
Write operations issued with a Write Concern of 0are not retryable.
The transaction commit and abort operationsare retryable write operations. If the commit operation or the abort operation encounters an error, MongoDB drivers retry the operation a single time regardless of whether retryWrites is set tofalse.
The write operations inside the transaction are not individually retryable, regardless of value of retryWrites.
For more information on transactions, see Transactions.
MongoDB Drivers
Drivers compatible with MongoDB 4.2 and higher enableRetryable Writes by default. Earlier drivers require theretryWrites=true option. TheretryWrites=true option can be omitted in applications that use drivers compatible with MongoDB 4.2 and higher.To disable retryable writes, applications that use drivers compatible with MongoDB 4.2 and higher must includeretryWrites=false in the connection string.
Retryable writes are enabled by default in mongosh. To disable retryable writes, use the --retryWrites=false command line option:
mongosh --retryWrites=false
The following write operations are retryable when issued with acknowledged write concern; e.g., Write Concerncannot be {w: 0}.
Note
The write operations inside the transactions are not individually retryable.
MongoDB retryable writes make only one retry attempt. This helps address transient network errors andreplica set elections, but not persistent network errors.
If the driver cannot find a healthy primary in the destination replica set or sharded cluster shard, the drivers waitserverSelectionTimeoutMS milliseconds to determine the new primary before retrying. Retryable writes do not address instances where the failover period exceeds serverSelectionTimeoutMS.
Warning
If the client application becomes temporarily unresponsive for more than the localLogicalSessionTimeoutMinutes after issuing a write operation, there is a chance that when the client applications starts responding (without a restart), the write operation may be retried and applied again.
The serverStatus command, and its mongoshshell helper db.serverStatus() includes statistics on retryable writes in the transactions section.
The official MongoDB drivers enable retryable writes by default. Applications which write to the local database will encounter write errors_unless_ retryable writes are explicitly disabled.
To disable retryable writes, specifyretryWrites=false in theconnection string for the MongoDB cluster.
Starting in MongoDB 6.1, if both the first and second attempt of a retryable write fail without a single write being performed, MongoDB returns an error with the NoWritesPerformed label.
The NoWritesPerformed label differentiates the results of batch operations like insertMany(). In aninsertMany operation, one of the following outcomes can occur:
| Outcome | MongoDB Output |
|---|---|
| No documents are inserted. | Error returned with NoWritesPerformed label. |
| Partial work done. (At least one document is inserted, but not all.) | Error returned without NoWritesPerformed label. |
| All documents are inserted. | Success returned. |
Applications can use the NoWritesPerformed label to definitively determine that no documents were inserted. This error reporting lets the application maintain an accurate state of the database when handling retryable writes.
In previous versions of MongoDB, an error is returned when both the first and second attempts of a retryable write fail. However, there is no distinction made to indicate that no writes were performed.