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:

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 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.

Enabling Retryable Writes

MongoDB drivers do not enable retryable writes by default.

MongoDB Drivers

To enable retryable writes in MongoDB drivers, add the retryWrites option to your connection string:

copy

mongodb://localhost/?retryWrites=true

mongo shell

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

copy

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}.

Methods	Descriptions
`db.collection.insertOne()` `db.collection.insert()` `db.collection.insertMany()`	Insert operations.
`db.collection.updateOne()` `db.collection.replaceOne()` `db.collection.save()` `db.collection.update()` where `multi` is `false`	Single-document update operations.
`db.collection.deleteOne()` `db.collection.remove()` where `justOne` is `true`	Single document delete operations.
`db.collection.findAndModify()` `db.collection.findOneAndDelete()` `db.collection.findOneAndReplace()` `db.collection.findOneAndUpdate()`	`findAndModify` operations. All `findAndModify` operations are single document operations.
`db.collection.bulkWrite()` with the following write operations: insertOne updateOne replaceOne deleteOne	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` operations for: `Bulk.find.removeOne()` `Bulk.find.replaceOne()` `Bulk.find.replaceOne()`	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.