View a markdown version of this page

Retryable writes in Amazon DocumentDB - Amazon DocumentDB
RequirementsSupported operationsLimitationsEnablingHow it worksError handlingMigration

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 are compatible with MongoDB 3.6+ drivers. Most modern MongoDB 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 driver version 3.6 or later (for example, PyMongo 3.6+, Node.js driver 3.6+, Java driver 3.6+, Go driver 1.3+, C# driver 2.7+).

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

Supported operations

The following write operations are retryable:

  • insertOne

  • insertMany

  • updateOne

  • deleteOne

  • findOneAndUpdate

  • findOneAndDelete

  • findOneAndReplace

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

  • commitTransaction

  • abortTransaction

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

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.

  • 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 version defaults to retryWrites=true (most MongoDB 4.2+ compatible drivers), you can simply remove any explicit retryWrites=false from your connection string.

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.

Error handling

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

Error code Name Description
225 TransactionTooOld A retried write arrived after the deduplication window expired. The original write was applied, but the cached result is no longer available.
301 Retryable writes not supported The write was sent with retryable write fields to an engine version that does not support retryable writes, or the operation type is not retryable. Set retryWrites=false in your connection string if 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.