Docs Menu
Docs Home
/
MongoDB Manual
/
MongoDB CRUD Operations

Retryable Writes

On this page

  • Prerequisites
  • Retryable Writes and Multi-Document Transactions
  • Enabling Retryable Writes
  • Retryable Write Operations
  • Behavior

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 set 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.
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. See setFeatureCompatibilityVersion for more information on the featureCompatibilityVersion 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 false.

The write operations inside the transaction are not individually retryable, regardless of value of retryWrites.

For more information on transactions, see Transactions.

Enabling Retryable Writes

MongoDB Drivers
MongoDB 3.6 introduced support for Retryable Writes, but most official MongoDB 3.6 and 4.0-compatible drivers disabled this feature by default. For such drivers, retryable writes could be enabled per connection by including the retryWrites=true option in the connection string for that connection. Refer to the MongoDB Driver Documentation to determine the correct default state of retryWrites for your specific driver and version.The official MongoDB 4.2+ compatible drivers enable Retryable Writes by default. Applications upgrading to the 4.2+ compatible drivers that require retryable writes may omit the retryWrites=true option. Applications upgrading to the 4.2+ compatible drivers that require disabling retryable writes must include retryWrites=false in the connection string.
mongo shell

To enable retryable writes in the mongo shell, use the --retryWrites command line option:

mongo --retryWrites

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.

db.collection.bulkWrite() with the following write 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.

Note

Updates to Shard Key Values

Starting in MongoDB 4.2, you can update a document's shard key value (unless the shard key field is the immutable _id field) by issuing single-document update/findAndModify operations either as a retryable write or in a transaction. For details, see Change a Document's Shard Key Value.

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

The official MongoDB 4.2-series drivers enable retryable writes by default. Applications which write to the local database will encounter write errors upon upgrading to 4.2-series drivers unless retryable writes are explicitly disabled.

To disable retryable writes, specify retryWrites=false in the connection string for the MongoDB cluster.

Back

Bulk Write Operations

Next

Retryable Reads