Retryable writes in Amazon DocumentDB

Starting with engine version 8.0.2, Amazon DocumentDB supports retryable writes. When a write operation fails due to a transient network error or primary election, the driver can automatically retry the operation exactly once. Amazon DocumentDB deduplicates the retried write so that the operation is applied at most once, preserving idempotency.

Retryable writes require a MongoDB-compatible driver that supports the retryable writes protocol. Most current MongoDB-compatible drivers enable retryable writes by default (retryWrites=true in the connection string). If you are upgrading to engine 8.0.2 from an earlier version, you can remove retryWrites=false from your connection string to enable this feature.

Requirements

To use retryable writes, you must meet the following requirements:

• Amazon DocumentDB engine version 8.0.2 or later.

• A MongoDB-compatible driver that supports retryable writes. For the minimum version, see the documentation for your driver.

• The connection string must include retryWrites=true, or the driver must default to retryable writes (most current drivers do).

Supported operations

Retryable writes apply to write operations in which each individual write affects at most one document. Batch operations qualify, because each write within the batch is deduplicated separately.

The following write operations are retryable:

• insertOne

• insertMany

• updateOne

• deleteOne

• findOneAndUpdate

• findOneAndDelete

• findOneAndReplace

• bulkWrite (when composed of insertOne, updateOne, deleteOne, or replaceOne operations)

For insertMany and bulkWrite, each document in the batch is deduplicated individually. If a retry is needed, only the documents that were not yet applied are inserted.

Note

commitTransaction and abortTransaction are also retryable, as transaction-control commands rather than as writes. The individual writes inside a transaction are not retryable. For more information, see Limitations.

Limitations

The following limitations apply to retryable writes in Amazon DocumentDB:

• updateMany and deleteMany are not retryable.

• Writes inside multi-statement transactions are not retryable. Transaction commit and abort operations are retryable separately.

• Documents must include an _id field for retryable inserts.

• Retryable writes are available only on engine version 8.0.2 and later. On earlier engine versions, set retryWrites=false in your connection string to avoid errors.

• Write operations are not retryable on clusters that use query planner version 1.0.

• For findOneAndUpdate, findOneAndDelete, and findOneAndReplace operations that return large documents, retryable writes may increase write latency because the full result document is cached for deduplication. If write performance is critical and the returned documents are large, consider setting retryWrites=false for those workloads.

Enabling retryable writes

To enable retryable writes, include retryWrites=true in your connection string:

mongodb://<username>:<password>@<cluster-endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=true

If your driver defaults to retryWrites=true, you can remove any explicit retryWrites=false from your connection string.

For the full connection string walkthrough, see Connecting programmatically to Amazon DocumentDB.

How retryable writes work

When your application sends a write with retryWrites=true, the driver attaches a logical session ID (lsid) and a transaction number (txnNumber) to the write command. Amazon DocumentDB uses these identifiers to deduplicate writes:

• On the first attempt, Amazon DocumentDB executes the write and caches the result.

• If the driver retries the same write (same lsid and txnNumber), Amazon DocumentDB returns the cached result without re-executing the write.

• Amazon DocumentDB honors retries for 60 minutes after the original write. Drivers retry immediately, so this window is far longer than a driver needs.

If a retry arrives more than 60 minutes after the original write, Amazon DocumentDB no longer has a cached result for it and runs the write as a new operation.

Error handling

The following errors are specific to retryable writes in Amazon DocumentDB:

Error code	Name	Description
225	TransactionTooOld	A newer transaction number for the same session and statement was already committed, so this retry is too old to apply.
301	Retryable writes not supported	The write included retryable write fields, but the engine version does not support retryable writes, or the operation is not retryable. Set retryWrites=false when connecting to engine versions earlier than 8.0.2.

Migrating from retryWrites=false

If you are upgrading to engine version 8.0.2 and currently use retryWrites=false in your connection strings:

1. Upgrade your cluster to engine version 8.0.2 or later.

2. Remove retryWrites=false from your application's connection strings, or change it to retryWrites=true.

3. No application code changes are required. The driver handles retries automatically.