Edit

Share via

Use Multi-document transactions in Azure Cosmos DB for MongoDB

  • Article

APPLIES TO: MongoDB

In this article, you'll create a Mongo shell app that executes a multi-document transaction on a fixed collection in Azure Cosmos DB for MongoDB with server version 4.0.

What are multi-document transactions?

In Azure Cosmos DB for MongoDB, operations on a single document are atomic. Multi-document transactions enable applications to execute atomic operations across multiple documents. It offers "all-or-nothing" semantics to the operations. On commit, the changes made inside the transactions are persisted and if the transaction fails, all changes inside the transaction are discarded.

Multi-document transactions follow ACID semantics:

  • Atomicity: All operations treated as one​
  • Consistency: Data committed is valid​
  • Isolation: Isolated from other operations​
  • Durability: Transaction data is persisted when client is told so​

Requirements

Multi-document transactions are supported within an unsharded collection in API version 4.0. Multi-document transactions are not supported across collections or in sharded collections in 4.0. The timeout for transactions is a fixed 5 seconds.

All drivers that support wire protocol version 4.0 or greater will support Azure Cosmos DB for MongoDB multi-document transactions.

Run multi-document transactions in MongoDB shell

Note

This example does not work in the MongoSH beta (shell) embedded in MongoDB Compass.

  1. Open a command prompt, go to the directory where Mongo shell version 4.0 and higher is installed:

    cd <path_to_mongo_shell_>

  2. Create a mongo shell script connect_friends.js and add the following content

    // insert data into friends collection
db.getMongo().getDB("users").friends.insert({name:"Tom"})
db.getMongo().getDB("users").friends.insert({name:"Mike"})
// start transaction
var session = db.getMongo().startSession();
var friendsCollection = session.getDatabase("users").friends;
session.startTransaction();
// operations in transaction
try {
    friendsCollection.updateOne({ name: "Tom" }, { $set: { friendOf: "Mike" } } );
    friendsCollection.updateOne({ name: "Mike" }, { $set: { friendOf: "Tom" } } );
} catch (error) {
    // abort transaction on error
    session.abortTransaction();
    throw error;
}

// commit transaction
session.commitTransaction();

  3. Run the following command to execute the multi-document transaction. The host, port, user, and key can be found in the Azure portal.

    mongo "<HOST>:<PORT>" -u "<USER>" -p "KEY" --ssl connect_friends.js

Next steps

Explore what's new in Azure Cosmos DB for MongoDB 4.0