- MongoDB CRUD Operations >
- Retryable Writes
Retryable Writes¶
On this page
New in version 3.6.
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 sets or sharded cluster.
Prerequisites¶
Retryable writes have the following requirements:
- Supported Deployment Topologies
- Retryable writes require a replica set or sharded cluster, and do not support standalone instances.
- Supported Storage Engine
Retryable writes require a storage engine supporting document-level locking, such as the WiredTiger or in-memory storage engines.
MMAPv1 Storage Engine does not support retryable writes.
- 3.6+ MongoDB Drivers
Clients require MongoDB drivers updated for MongoDB 3.6 or greater:
Java 3.6+
Python 3.6+
C 1.9+
C# 2.5+
Node 3.0+
Ruby 2.5+
Perl 2.0+
PHPC 1.4+
Scala 2.2+
- MongoDB Version
- The MongoDB version of every node in the cluster must be
3.6
or greater, and thefeatureCompatibilityVersion
of each node in the cluster must be3.6
or greater. SeesetFeatureCompatibilityVersion
for more information on thefeatureCompatibilityVersion
flag. - Write Acknowledgment
- Write operations issued with a Write Concern of
0
are not retryable.
Retryable Writes and Multi-Document Transactions¶
New in version 4.0.
The transaction commit and abort operations
are 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 to
true
.
The write operations inside the transaction are not individually
retryable, regardless of whether retryWrites
is set to
true
.
For more information on transactions, see Transactions.
Enabling Retryable Writes¶
MongoDB 3.6 introduced support for Retryable Writes, but most
official MongoDB 3.6 and 4.0-compatible drivers disable this feature
by default. For such drivers, retryable writes can be enabled per
connection by including the retryWrites=true
option in the connection string
for that connection (see below). Refer to the
MongoDB Driver Documentation to determine
the correct default state of retryWrites
for your
specific driver and version.
- MongoDB Drivers
To enable retryable writes in MongoDB drivers, add the
retryWrites
option to your connection string:mongo
shellTo enable retryable writes in the
mongo
shell, use the--retryWrites
command line option:
Retryable Write Operations¶
The following write operations are retryable when issued with
acknowledged write concern; e.g., Write Concern
cannot be {w: 0}
.
Note
The write operations inside the transactions are not individually retryable.
Methods | Descriptions |
---|---|
Insert operations. | |
Single-document update operations. | |
Single document delete operations. | |
findAndModify operations. All findAndModify operations
are single document operations. |
|
|
Bulk write operations that only consist of the single-document
write operations. A retryable bulk operation can include any
combination of the specified write operations but cannot include
any multi-document write operations, such as updateMany . |
|
Bulk write operations that only consist of the single-document
write operations. A retryable bulk operation can include any
combination of the specified write operations but cannot include
any multi-document write operations, such as update which
specifies true for the multi option. |
Behavior¶
Persistent Network Errors¶
MongoDB retryable writes make only one retry attempt. This helps address transient network errors and replica set elections, but not persistent network errors.
Failover Period¶
If the driver cannot find a healthy primary in the destination
replica set or sharded cluster shard, the drivers wait
serverSelectionTimeoutMS
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.
Diagnostics¶
New in version 3.6.3.
The serverStatus
command, and its mongo
shell helper db.serverStatus()
includes statistics on
retryable writes in the transactions
section.
Retryable Writes Against local
Database¶
You cannot perform write operations to collections in the local
database with retryable writes enabled.
The official MongoDB 3.6 and 4.0-compatible drivers disable retryable writes by
default. To explicitly disable retryable writes, specify
retryWrites=false
in the
connection string for the MongoDB cluster.