Transactions

Amazon DocumentDB (with MongoDB compatibility) now supports MongoDB 4.0 compatibility including transactions. You can perform transactions across multiple documents, statements, collections, and databases. Transactions simplify application development by enabling you to perform atomic, consistent, isolated, and durable (ACID) operations across one or more documents within an Amazon DocumentDB cluster. Common use cases for transactions include financial processing, fulfilling and managing orders, and building multi-player games.

There is no additional cost for transactions. You only pay for the read and write IOs that you consume as part of the transactions.

Requirements

To use the transactions feature, you need to meet the following requirements:

  • You must be using the Amazon DocumentDB 4.0 engine.
  • You must use a driver compatible with MongoDB 4.0 or greater.

Best Practices

Here are some best practices so that you can get the most using transactions with Amazon DocumentDB.

  • Always commit or abort the transaction after it is complete. Leaving a transaction in an incomplete state ties up database resources and can cause write conflicts.
  • It is recommended to keep transactions to the smallest number of commands needed. If you have transactions with multiple statements that can be divided up into multiple smaller transactions, it is advisable to do so to reduce the likelihood of a timeout. Always aim to create short transactions, not long-running reads.

Limitations

  • Amazon DocumentDB does not support cursors within a transaction.
  • Amazon DocumentDB cannot create new collections in a transaction and cannot query/update against non-existing collections.
  • Document-level write locks are subject to a 1 minute timeout, which is not configurable by the user.
  • No support for retryable writes, retryable commit and retryable abort.
  • Each Amazon DocumentDB instance has an upper bound limit on the number of concurrent transaction open on the instance at one time. For the limits, please see Instance Limits.
  • For a given transaction, the transaction log size must be less than 32MB.
  • Amazon DocumentDB does support count() within a transactions, but not all drivers support this capability. An alternative is to use the countDocuments() API, which translates the count query into an aggregation query on the client side.
  • Transactions have a one minute execution limit and sessions have a 30-minute timeout. If a transaction times out, it will be aborted, and any subsequent commands issued within the session for the existing transaction will yield the following error:

```

  1. WriteCommandError({
  2. "ok" : 0,
  3. "operationTime" : Timestamp(1603491424, 627726),
  4. "code" : 251,
  5. "errmsg" : "Given transaction number 0 does not match any in-progress transactions."
  6. }) ```

Monitoring and Diagnostics

With the support for transactions in Amazon DocumentDB 4.0, additional CloudWatch metrics were added to help you monitor your transactions.

New CloudWatch Metrics

  • DatabaseTransactions: The number of open transactions taken at a one-minute period.
  • DatabaseTransactionsAborted: The number of aborted transactions taken at a one-minute period.
  • DatabaseTransactionsMax: The maximum number of open transactions in a one-minute period.
  • TransactionsAborted: The number of transactions aborted on an instance in a one-minute period.
  • TransactionsCommitted: The number of transactions committed on an instance in a one-minute period.
  • TransactionsOpen: The number of transactions open on an instance taken at a one-minute period.
  • TransactionsOpenMax: The maximum number of transactions open on an instance in a one-minute period.
  • TransactionsStarted: The number of transactions started on an instance in a one-minute period.

Note

For more CloudWatch metrics for Amazon DocumentDB, go to Monitoring Amazon DocumentDB with CloudWatch.

Additionally, new fields were added to both currentOp lsid, transactionThreadId, and a new state for “idle transaction” and serverStatus transactions: currentActive, currentInactive, currentOpen, totalAborted, totalCommitted, and totalStarted.

Transaction Isolation Level

When starting a transaction, you have the ability to specify the both the readConcern and writeConcern as shown in the example below:

mySession.startTransaction({readConcern: {level: 'snapshot'}, writeConcern: {w: 'majority'}});

For readConcern, Amazon DocumentDB supports snapshot isolation by default. If a readConcern of local, available, or majority are specified, Amazon DocumentDB will upgrade the readConcern level to snapshot. Amazon DocumentDB does not support the linearizable readConcern and specifying such a read concern will result in an error.

For writeConcern, Amazon DocumentDB supports majority by default and a write quorum is achieved when four copies of the data are persisted across three AZs. If a lower writeConcern is specified, Amazon DocumentDB will upgrade the writeConcern to majority. Further, all Amazon DocumentDB writes are journaled and journaling cannot be disabled.

Use Cases

In this section, we will walk through two use cases for transactions: multi-statement and multi-collection.

Multi-Statement Transactions

Amazon DocumentDB transactions are multi-statement, which means you can write a transaction that spans multiple statements with an explicit commit or rollback. You can group insert, update, update, and findAndModify actions as a single atomic operation.

A common use case for multi-statement transactions is a debit-credit transaction. For example: you owe a friend money for clothes. Thus, you need to debit (withdraw) $500 from your account and credit $500 (deposit) to your friend’s account. To perform that operation, you perform both the debt and credit operations within a single transaction to ensure atomicity. Doing so prevents scenarios where $500 is debited from your account, but not credited to your friend’s account. Here’s what this use case would look like:


2. // *** Transfer $500 from Alice to Bob inside a transaction: Success Scenario***
3. // Setup bank account for Alice and Bob. Each have $1000 in their account

5. var databaseName = "bank";
6. var collectionName = "account";
7. var amountToTransfer = 500;

9. var session = db.getMongo().startSession({causalConsistency: false});
10. var bankDB = session.getDatabase(databaseName);
11. var accountColl = bankDB[collectionName];
12. accountColl.drop();

14. accountColl.insert({name: "Alice", balance: 1000});
15. accountColl.insert({name: "Bob", balance: 1000});

17. session.startTransaction();

19. // deduct $500 from Alice's account
20. var aliceBalance = accountColl.find({"name": "Alice"}).next().balance;
21. var newAliceBalance = aliceBalance - amountToTransfer;
22. accountColl.update({"name": "Alice"},{"$set": {"balance": newAliceBalance}});
23. var findAliceBalance = accountColl.find({"name": "Alice"}).next().balance;

25. // add $500 to Bob's account
26. var bobBalance = accountColl.find({"name": "Bob"}).next().balance;
27. var newBobBalance = bobBalance + amountToTransfer;
28. accountColl.update({"name": "Bob"},{"$set": {"balance": newBobBalance}});
29. var findBobBalance = accountColl.find({"name": "Bob"}).next().balance;

31. session.commitTransaction();

33. accountColl.find();

35. // *** Transfer $500 from Alice to Bob inside a transaction: Failure Scenario***

37. // Setup bank account for Alice and Bob. Each have $1000 in their account
38. var databaseName = "bank";
39. var collectionName = "account";
40. var amountToTransfer = 500;

42. var session = db.getMongo().startSession({causalConsistency: false});
43. var bankDB = session.getDatabase(databaseName);
44. var accountColl = bankDB[collectionName];
45. accountColl.drop();

47. accountColl.insert({name: "Alice", balance: 1000});
48. accountColl.insert({name: "Bob", balance: 1000});

50. session.startTransaction();

52. // deduct $500 from Alice's account
53. var aliceBalance = accountColl.find({"name": "Alice"}).next().balance;
54. var newAliceBalance = aliceBalance - amountToTransfer;
55. accountColl.update({"name": "Alice"},{"$set": {"balance": newAliceBalance}});
56. var findAliceBalance = accountColl.find({"name": "Alice"}).next().balance;

58. session.abortTransaction();

Multi-Collection Transactions

Our transactions are also multi-collection, which means they can be used to perform multiple operations within a single transaction and across multiple collections. This provides a consistent view of data and maintains your data’s integrity. When you commit the commands as a single <>, the transactions are all-or-nothing executions—in that, they will either all succeed or all fail.

Here is an example of multi-collection transactions, using the same scenario and data from the example for multi-statement transactions.


2. // *** Transfer $500 from Alice to Bob inside a transaction: Success Scenario***

4. // Setup bank account for Alice and Bob. Each have $1000 in their account
5. var amountToTransfer = 500;
6. var collectionName = "account";

8. var session = db.getMongo().startSession({causalConsistency: false});
9. var accountCollInBankA = session.getDatabase("bankA")[collectionName];
10. var accountCollInBankB = session.getDatabase("bankB")[collectionName];

12. accountCollInBankA.drop();
13. accountCollInBankB.drop();

15. accountCollInBankA.insert({name: "Alice", balance: 1000});
16. accountCollInBankB.insert({name: "Bob", balance: 1000});

18. session.startTransaction();

20. // deduct $500 from Alice's account
21. var aliceBalance = accountCollInBankA.find({"name": "Alice"}).next().balance;
22. var newAliceBalance = aliceBalance - amountToTransfer;
23. accountCollInBankA.update({"name": "Alice"},{"$set": {"balance": newAliceBalance}});
24. var findAliceBalance = accountCollInBankA.find({"name": "Alice"}).next().balance;

26. // add $500 to Bob's account
27. var bobBalance = accountCollInBankB.find({"name": "Bob"}).next().balance;
28. var newBobBalance = bobBalance + amountToTransfer;
29. accountCollInBankB.update({"name": "Bob"},{"$set": {"balance": newBobBalance}});
30. var findBobBalance = accountCollInBankB.find({"name": "Bob"}).next().balance;

32. session.commitTransaction();

34. accountCollInBankA.find(); // Alice holds $500 in bankA
35. accountCollInBankB.find(); // Bob holds $1500 in bankB

37. // *** Transfer $500 from Alice to Bob inside a transaction: Failure Scenario***

39. // Setup bank account for Alice and Bob. Each have $1000 in their account
40. var collectionName = "account";
41. var amountToTransfer = 500;

43. var session = db.getMongo().startSession({causalConsistency: false});
44. var accountCollInBankA = session.getDatabase("bankA")[collectionName];
45. var accountCollInBankB = session.getDatabase("bankB")[collectionName];

47. accountCollInBankA.drop();
48. accountCollInBankB.drop();

50. accountCollInBankA.insert({name: "Alice", balance: 1000});
51. accountCollInBankB.insert({name: "Bob", balance: 1000});

53. session.startTransaction();

55. // deduct $500 from Alice's account
56. var aliceBalance = accountCollInBankA.find({"name": "Alice"}).next().balance;
57. var newAliceBalance = aliceBalance - amountToTransfer;
58. accountCollInBankA.update({"name": "Alice"},{"$set": {"balance": newAliceBalance}});
59. var findAliceBalance = accountCollInBankA.find({"name": "Alice"}).next().balance;

61. // add $500 to Bob's account
62. var bobBalance = accountCollInBankB.find({"name": "Bob"}).next().balance;
63. var newBobBalance = bobBalance + amountToTransfer;
64. accountCollInBankB.update({"name": "Bob"},{"$set": {"balance": newBobBalance}});
65. var findBobBalance = accountCollInBankB.find({"name": "Bob"}).next().balance;

67. session.abortTransaction();

69. accountCollInBankA.find(); // Alice holds $1000 in bankA
70. accountCollInBankB.find(); // Bob holds $1000 in bankB

Transaction API Examples for Callback API

The callback API is only available for 4.2+ drivers.

Javascript

The following code demonstrates how to utilize the Amazon DocumentDB transaction API with Javascript.


1. // *** Transfer $500 from Alice to Bob inside a transaction: Success ***
2. // Setup bank account for Alice and Bob. Each have $1000 in their account
3. var databaseName = "bank";
4. var collectionName = "account";
5. var amountToTransfer = 500;

7. var session = db.getMongo().startSession({causalConsistency: false});
8. var bankDB = session.getDatabase(databaseName);
9. var accountColl = bankDB[collectionName];
10. accountColl.drop();

12. accountColl.insert({name: "Alice", balance: 1000});
13. accountColl.insert({name: "Bob", balance: 1000});

15. session.startTransaction();

17. // deduct $500 from Alice's account
18. var aliceBalance = accountColl.find({"name": "Alice"}).next().balance;
19. assert(aliceBalance >= amountToTransfer);
20. var newAliceBalance = aliceBalance - amountToTransfer;
21. accountColl.update({"name": "Alice"},{"$set": {"balance": newAliceBalance}});
22. var findAliceBalance = accountColl.find({"name": "Alice"}).next().balance;
23. assert.eq(newAliceBalance, findAliceBalance);

25. // add $500 to Bob's account
26. var bobBalance = accountColl.find({"name": "Bob"}).next().balance;
27. var newBobBalance = bobBalance + amountToTransfer;
28. accountColl.update({"name": "Bob"},{"$set": {"balance": newBobBalance}});
29. var findBobBalance = accountColl.find({"name": "Bob"}).next().balance;
30. assert.eq(newBobBalance, findBobBalance);

32. session.commitTransaction();

34. accountColl.find();

Node.js

The following code demonstrates how to utilize the Amazon DocumentDB transaction API with Node.js.


1. // Node.js callback API:

3. const bankDB = await mongoclient.db("bank");
4. var accountColl = await bankDB.createCollection("account");
5. var amountToTransfer = 500;

7. const session = mongoclient.startSession({causalConsistency: false});
8. await accountColl.drop();

10. await accountColl.insertOne({name: "Alice", balance: 1000}, { session });
11. await accountColl.insertOne({name: "Bob", balance: 1000}, { session });

13. const transactionOptions = {
14. readConcern: { level: 'snapshot' },
15. writeConcern: { w: 'majority' }
16. };

18. // deduct $500 from Alice's account
19. var aliceBalance = await accountColl.findOne({name: "Alice"}, {session});
20. assert(aliceBalance.balance >= amountToTransfer);
21. var newAliceBalance = aliceBalance - amountToTransfer;
22. session.startTransaction(transactionOptions);
23. await accountColl.updateOne({name: "Alice"}, {$set: {balance: newAliceBalance}}, {session });
24. await session.commitTransaction();
25. aliceBalance = await accountColl.findOne({name: "Alice"}, {session});
26. assert(newAliceBalance == aliceBalance.balance);

28. // add $500 to Bob's account
29. var bobBalance = await accountColl.findOne({name: "Bob"}, {session});
30. var newBobBalance = bobBalance.balance + amountToTransfer;
31. session.startTransaction(transactionOptions);
32. await accountColl.updateOne({name: "Bob"}, {$set: {balance: newBobBalance}}, {session });
33. await session.commitTransaction();
34. bobBalance = await accountColl.findOne({name: "Bob"}, {session});
35. assert(newBobBalance == bobBalance.balance);

C#

The following code demonstrates how to utilize the Amazon DocumentDB transaction API with C#.


1. // C# Callback API

3. var dbName = "bank";
4. var collName = "account";
5. var amountToTransfer = 500;

7. using (var session = client.StartSession(new ClientSessionOptions{CausalConsistency = false}))
8. {
9. var bankDB = client.GetDatabase(dbName);
10. var accountColl = bankDB.GetCollection<BsonDocument>(collName);
11. bankDB.DropCollection(collName);
12. accountColl.InsertOne(session, new BsonDocument { {"name", "Alice"}, {"balance", 1000 } });
13. accountColl.InsertOne(session, new BsonDocument { {"name", "Bob"}, {"balance", 1000 } });

15. // start transaction
16. var transactionOptions = new TransactionOptions(
17. readConcern: ReadConcern.Snapshot,
18. writeConcern: WriteConcern.WMajority);
19. var result = session.WithTransaction(
20. (sess, cancellationtoken) =>
21. {
22. // deduct $500 from Alice's account
23. var aliceBalance = accountColl.Find(sess, Builders<BsonDocument>.Filter.Eq("name", "Alice")).FirstOrDefault().GetValue("balance");
24. Debug.Assert(aliceBalance >= amountToTransfer);
25. var newAliceBalance = aliceBalance.AsInt32 - amountToTransfer;
26. accountColl.UpdateOne(sess, Builders<BsonDocument>.Filter.Eq("name", "Alice"),
27. Builders<BsonDocument>.Update.Set("balance", newAliceBalance));
28. aliceBalance = accountColl.Find(sess, Builders<BsonDocument>.Filter.Eq("name", "Alice")).FirstOrDefault().GetValue("balance");
29. Debug.Assert(aliceBalance == newAliceBalance);

31. // add $500 from Bob's account
32. var bobBalance = accountColl.Find(sess, Builders<BsonDocument>.Filter.Eq("name", "Bob")).FirstOrDefault().GetValue("balance");
33. var newBobBalance = bobBalance.AsInt32 + amountToTransfer;
34. accountColl.UpdateOne(sess, Builders<BsonDocument>.Filter.Eq("name", "Bob"),
35. Builders<BsonDocument>.Update.Set("balance", newBobBalance));
36. bobBalance = accountColl.Find(sess, Builders<BsonDocument>.Filter.Eq("name", "Bob")).FirstOrDefault().GetValue("balance");
37. Debug.Assert(bobBalance == newBobBalance);

39. return "Transaction committed";
40. }, transactionOptions);
41. // check values outside of transaction
42. var aliceNewBalance = accountColl.Find(Builders<BsonDocument>.Filter.Eq("name", "Alice")).FirstOrDefault().GetValue("balance");
43. var bobNewBalance = accountColl.Find(Builders<BsonDocument>.Filter.Eq("name", "Bob")).FirstOrDefault().GetValue("balance");
44. Debug.Assert(aliceNewBalance ==  500);
45. Debug.Assert(bobNewBalance ==  1500);
46. }

Ruby

The following code demonstrates how to utilize the Amazon DocumentDB transaction API with Ruby.


1. // Ruby Callback API

3. dbName = "bank"
4. collName = "account"
5. amountToTransfer = 500

7. session = client.start_session(:causal_consistency=> false)
8. bankDB = Mongo::Database.new(client, dbName)
9. accountColl = bankDB[collName]
10. accountColl.drop()

12. accountColl.insert_one({"name"=>"Alice", "balance"=>1000})
13. accountColl.insert_one({"name"=>"Bob", "balance"=>1000})

15. # start transaction
16. session.with_transaction(read_concern: {level: :snapshot}, write_concern: {w: :majority}) do
17. # deduct $500 from Alice's account
18. aliceBalance = accountColl.find({"name"=>"Alice"}, :session=> session).first['balance']
19. assert aliceBalance >= amountToTransfer
20. newAliceBalance = aliceBalance - amountToTransfer
21. accountColl.update_one({"name"=>"Alice"}, { "$set" => {"balance"=>newAliceBalance} }, :session=> session)
22. aliceBalance = accountColl.find({"name"=>>"Alice"}, :session=> session).first['balance']
23. assert_equal(newAliceBalance, aliceBalance)

25. # add $500 from Bob's account
26. bobBalance = accountColl.find({"name"=>"Bob"}, :session=> session).first['balance']
27. newBobBalance = bobBalance + amountToTransfer
28. accountColl.update_one({"name"=>"Bob"}, { "$set" => {"balance"=>newBobBalance} }, :session=> session)
29. bobBalance = accountColl.find({"name"=>"Bob"}, :session=> session).first['balance']
30. assert_equal(newBobBalance, bobBalance)
31. end

33. # check results outside of transaction
34. aliceBalance = accountColl.find({"name"=>"Alice"}).first['balance']
35. bobBalance = accountColl.find({"name"=>"Bob"}).first['balance']
36. assert_equal(aliceBalance, 500)
37. assert_equal(bobBalance, 1500)

39. session.end_session

Go

The following code demonstrates how to utilize the Amazon DocumentDB transaction API with Go.


1. // Go - Callback API
2. type Account struct {
3. Name string
4. Balance  int
5. }

7. ctx := context.TODO()

9. dbName := "bank"
10. collName := "account"
11. amountToTransfer := 500

13. session, err := client.StartSession(options.Session().SetCausalConsistency(false))
14. assert.NilError(t, err)
15. defer session.EndSession(ctx)

17. bankDB := client.Database(dbName)
18. accountColl := bankDB.Collection(collName)
19. accountColl.Drop(ctx)

21. _, err = accountColl.InsertOne(ctx, bson.M{"name" : "Alice", "balance":1000})
22. _, err = accountColl.InsertOne(ctx, bson.M{"name" : "Bob", "balance":1000})

24. transactionOptions := options.Transaction().SetReadConcern(readconcern.Snapshot()).
25. SetWriteConcern(writeconcern.New(writeconcern.WMajority()))
26. _, err = session.WithTransaction(ctx, func(sessionCtx mongo.SessionContext) (interface{}, error) {
27. var result Account
28. // deduct $500 from Alice's account
29. err = accountColl.FindOne(sessionCtx, bson.M{"name": "Alice"}).Decode(&result)
30. aliceBalance := result.Balance
31. newAliceBalance := aliceBalance - amountToTransfer
32. _, err = accountColl.UpdateOne(sessionCtx, bson.M{"name": "Alice"}, bson.M{"$set": bson.M{"balance": newAliceBalance}})
33. err = accountColl.FindOne(sessionCtx, bson.M{"name": "Alice"}).Decode(&result)
34. aliceBalance = result.Balance
35. assert.Equal(t, aliceBalance, newAliceBalance)

37. // add $500 to Bob's account
38. err = accountColl.FindOne(sessionCtx, bson.M{"name": "Bob"}).Decode(&result)
39. bobBalance := result.Balance
40. newBobBalance := bobBalance + amountToTransfer
41. _, err = accountColl.UpdateOne(sessionCtx, bson.M{"name": "Bob"}, bson.M{"$set": bson.M{"balance": newBobBalance}})
42. err = accountColl.FindOne(sessionCtx, bson.M{"name": "Bob"}).Decode(&result)
43. bobBalance = result.Balance
44. assert.Equal(t, bobBalance, newBobBalance)

46. if err != nil {
47. return nil, err
48. }
49. return "transaction committed", err
50. }, transactionOptions)

52. // check results outside of transaction
53. var result Account
54. err = accountColl.FindOne(ctx, bson.M{"name": "Alice"}).Decode(&result)
55. aliceNewBalance := result.Balance
56. err = accountColl.FindOne(ctx, bson.M{"name": "Bob"}).Decode(&result)
57. bobNewBalance := result.Balance
58. assert.Equal(t, aliceNewBalance, 500)
59. assert.Equal(t, bobNewBalance, 1500)
60. // Go - Core API
61. type Account struct {
62. Name string
63. Balance  int
64. }

66. func transferMoneyWithRetry(sessionContext mongo.SessionContext, accountColl *mongo.Collection, t *testing.T) error {
67. amountToTransfer := 500

69. transactionOptions := options.Transaction().SetReadConcern(readconcern.Snapshot()).
70. SetWriteConcern(writeconcern.New(writeconcern.WMajority()))
71. if err := sessionContext.StartTransaction(transactionOptions); err != nil {
72. panic(err)
73. }

75. var result Account
76. // deduct $500 from Alice's account
77. err := accountColl.FindOne(sessionContext, bson.M{"name": "Alice"}).Decode(&result)
78. aliceBalance := result.Balance
79. newAliceBalance := aliceBalance - amountToTransfer
80. _, err = accountColl.UpdateOne(sessionContext, bson.M{"name": "Alice"}, bson.M{"$set": bson.M{"balance": newAliceBalance}})
81. if err != nil {
82. sessionContext.AbortTransaction(sessionContext)
83. }
84. err = accountColl.FindOne(sessionContext, bson.M{"name": "Alice"}).Decode(&result)
85. aliceBalance = result.Balance
86. assert.Equal(t, aliceBalance, newAliceBalance)

88. // add $500 to Bob's account
89. err = accountColl.FindOne(sessionContext, bson.M{"name": "Bob"}).Decode(&result)
90. bobBalance := result.Balance
91. newBobBalance := bobBalance + amountToTransfer
92. _, err = accountColl.UpdateOne(sessionContext, bson.M{"name": "Bob"}, bson.M{"$set": bson.M{"balance": newBobBalance}})
93. if err != nil {
94. sessionContext.AbortTransaction(sessionContext)
95. }
96. err = accountColl.FindOne(sessionContext, bson.M{"name": "Bob"}).Decode(&result)
97. bobBalance = result.Balance
98. assert.Equal(t, bobBalance, newBobBalance)

100. err = sessionContext.CommitTransaction(sessionContext)
101. return err
102. }

104. func doTransactionWithRetry(t *testing.T) {
105. ctx := context.TODO()

107. dbName := "bank"
108. collName := "account"
109. bankDB := client.Database(dbName)
110. accountColl := bankDB.Collection(collName)

112. client.UseSessionWithOptions(ctx, options.Session().SetCausalConsistency(false), func(sessionContext mongo.SessionContext) error {
113. accountColl.Drop(ctx)
114. accountColl.InsertOne(sessionContext, bson.M{"name" : "Alice", "balance":1000})
115. accountColl.InsertOne(sessionContext, bson.M{"name" : "Bob", "balance":1000})
116. for {
117. err := transferMoneyWithRetry(sessionContext, accountColl, t)
118. if err == nil {
119. println("transaction committed")
120. return nil
121. }
122. if mongoErr := err.(mongo.CommandError); mongoErr.HasErrorLabel("TransientTransactionError") {
123. continue
124. }
125. println("transaction failed")
126. return err
127. }
128. })

130. // check results outside of transaction
131. var result Account
132. accountColl.FindOne(ctx, bson.M{"name": "Alice"}).Decode(&esult)
133. aliceBalance := result.Balance
134. assert.Equal(t, aliceBalance, 500)
135. accountColl.FindOne(ctx, bson.M{"name": "Bob"}).Decode(&result)
136. bobBalance := result.Balance
137. assert.Equal(t, bobBalance, 1500)
138. }

Java

The following code demonstrates how to utilize the Amazon DocumentDB transaction API with Java.


1. // Java (sync) - Callback API
2. MongoDatabase bankDB = mongoClient.getDatabase("bank");
3. MongoCollection accountColl = bankDB.getCollection("account");
4. accountColl.drop();
5. int amountToTransfer = 500;

7. // add sample data
8. accountColl.insertOne(new Document("name", "Alice").append("balance", 1000));
9. accountColl.insertOne(new Document("name", "Bob").append("balance", 1000));

11. TransactionOptions txnOptions = TransactionOptions.builder()
12. .readConcern(ReadConcern.SNAPSHOT)
13. .writeConcern(WriteConcern.MAJORITY)
14. .build();
15. ClientSessionOptions sessionOptions = ClientSessionOptions.builder().causallyConsistent(false).build();
16. try ( ClientSession clientSession = mongoClient.startSession(sessionOptions) ) {
17. clientSession.withTransaction(new TransactionBody<Void>() {
18. @Override
19. public Void execute() {
20. // deduct $500 from Alice's account
21. List<Document> documentList = new ArrayList<>();
22. accountColl.find(clientSession, new Document("name", "Alice")).into(documentList);
23. int aliceBalance = (int) documentList.get(0).get("balance");
24. int newAliceBalance = aliceBalance - amountToTransfer;

26. accountColl.updateOne(clientSession, new Document("name", "Alice"), new Document("$set", new Document("balance", newAliceBalance)));

28. // check Alice's new balance
29. documentList = new ArrayList<>();
30. accountColl.find(clientSession, new Document("name", "Alice")).into(documentList);
31. int updatedBalance = (int) documentList.get(0).get("balance");
32. Assert.assertEquals(updatedBalance, newAliceBalance);

34. // add $500 to Bob's account
35. documentList = new ArrayList<>();
36. accountColl.find(clientSession, new Document("name", "Bob")).into(documentList);
37. int bobBalance = (int) documentList.get(0).get("balance");
38. int newBobBalance = bobBalance + amountToTransfer;

40. accountColl.updateOne(clientSession, new Document("name", "Bob"), new Document("$set", new Document("balance", newBobBalance)));

42. // check Bob's new balance
43. documentList = new ArrayList<>();
44. accountColl.find(clientSession, new Document("name", "Bob")).into(documentList);
45. updatedBalance = (int) documentList.get(0).get("balance");
46. Assert.assertEquals(updatedBalance, newBobBalance);

48. return null;
49. }
50. }, txnOptions);
51. }

C

The following code demonstrates how to utilize the Amazon DocumentDB transaction API with C.


1. // Sample Code for C with Callback

3. #include <bson.h>
4. #include <mongoc.h>
5. #include <stdio.h>
6. #include <string.h>
7. #include <assert.h>

9. typedef struct {
10. int64_t balance;
11. bson_t *account;
12. bson_t *opts;
13. mongoc_collection_t *collection;
14. } ctx_t;

16. bool callback_session (mongoc_client_session_t *session, void *ctx, bson_t **reply, bson_error_t *error)
17. {
18. bool r = true;
19. ctx_t *data = (ctx_t *) ctx;
20. bson_t local_reply;
21. bson_t *selector = data->account;
22. bson_t *update = BCON_NEW ("$set", "{", "balance", BCON_INT64 (data->balance), "}");

24. mongoc_collection_update_one (data->collection, selector, update, data->opts, &local_reply, error);

26. *reply = bson_copy (&local_reply);
27. bson_destroy (&local_reply);
28. bson_destroy (update);
29. return r;
30. }

32. void test_callback_money_transfer(mongoc_client_t* client, mongoc_collection_t* collection, int amount_to_transfer){

34. bson_t reply;
35. bool r = true;
36. const bson_t *doc;
37. bson_iter_t iter;
38. ctx_t alice_ctx;
39. ctx_t bob_ctx;
40. bson_error_t error;

42. // find query
43. bson_t *alice_query = bson_new ();
44. BSON_APPEND_UTF8(alice_query, "name", "Alice");

46. bson_t *bob_query = bson_new ();
47. BSON_APPEND_UTF8(bob_query, "name", "Bob");

49. // create session
50. // set causal consistency to false
51. mongoc_session_opt_t *session_opts = mongoc_session_opts_new ();
52. mongoc_session_opts_set_causal_consistency (session_opts, false);
53. // start the session
54. mongoc_client_session_t *client_session = mongoc_client_start_session (client, session_opts, &error);

56. // add session to options
57. bson_t *opts = bson_new();
58. mongoc_client_session_append (client_session, opts, &error);

60. // deduct 500 from Alice
61. // find account balance of Alice
62. mongoc_cursor_t *cursor = mongoc_collection_find_with_opts (collection, alice_query, NULL, NULL);
63. mongoc_cursor_next (cursor, &doc);
64. bson_iter_init (&iter, doc);
65. bson_iter_find (&iter, "balance");
66. int64_t alice_balance = (bson_iter_value (&iter))->value.v_int64;
67. assert(alice_balance >= amount_to_transfer);
68. int64_t new_alice_balance = alice_balance - amount_to_transfer;

70. // set variables which will be used by callback function
71. alice_ctx.collection = collection;
72. alice_ctx.opts = opts;
73. alice_ctx.balance = new_alice_balance;
74. alice_ctx.account = alice_query;

76. // callback
77. r = mongoc_client_session_with_transaction (client_session, &callback_session, NULL, &alice_ctx, &reply, &error);
78. assert(r);

80. // find account balance of Alice after transaction
81. cursor = mongoc_collection_find_with_opts (collection, alice_query, NULL, NULL);
82. mongoc_cursor_next (cursor, &doc);
83. bson_iter_init (&iter, doc);
84. bson_iter_find (&iter, "balance");
85. alice_balance = (bson_iter_value (&iter))->value.v_int64;
86. assert(alice_balance == new_alice_balance);
87. assert(alice_balance == 500);

89. // add 500 to bob's balance
90. // find account balance of Bob
91. cursor = mongoc_collection_find_with_opts (collection, bob_query, NULL, NULL);
92. mongoc_cursor_next (cursor, &doc);
93. bson_iter_init (&iter, doc);
94. bson_iter_find (&iter, "balance");
95. int64_t bob_balance = (bson_iter_value (&iter))->value.v_int64;
96. int64_t new_bob_balance = bob_balance + amount_to_transfer;

98. bob_ctx.collection = collection;
99. bob_ctx.opts = opts;
100. bob_ctx.balance = new_bob_balance;
101. bob_ctx.account = bob_query;

103. // set read & write concern
104. mongoc_read_concern_t *read_concern = mongoc_read_concern_new ();
105. mongoc_write_concern_t *write_concern = mongoc_write_concern_new ();
106. mongoc_transaction_opt_t *txn_opts = mongoc_transaction_opts_new ();

108. mongoc_write_concern_set_w(write_concern, MONGOC_WRITE_CONCERN_W_MAJORITY);
109. mongoc_read_concern_set_level(read_concern, MONGOC_READ_CONCERN_LEVEL_SNAPSHOT);
110. mongoc_transaction_opts_set_write_concern (txn_opts, write_concern);
111. mongoc_transaction_opts_set_read_concern (txn_opts, read_concern);

113. // callback
114. r = mongoc_client_session_with_transaction (client_session, &callback_session, txn_opts, &bob_ctx, &reply, &error);
115. assert(r);

117. // find account balance of Bob after transaction
118. cursor = mongoc_collection_find_with_opts (collection, bob_query, NULL, NULL);
119. mongoc_cursor_next (cursor, &doc);
120. bson_iter_init (&iter, doc);
121. bson_iter_find (&iter, "balance");
122. bob_balance = (bson_iter_value (&iter))->value.v_int64;
123. assert(bob_balance == new_bob_balance);
124. assert(bob_balance == 1500);

126. // cleanup
127. bson_destroy(alice_query);
128. bson_destroy(bob_query);
129. mongoc_client_session_destroy(client_session);
130. bson_destroy(opts);
131. mongoc_transaction_opts_destroy(txn_opts);
132. mongoc_read_concern_destroy(read_concern);
133. mongoc_write_concern_destroy(write_concern);
134. mongoc_cursor_destroy(cursor);
135. bson_destroy(doc);
136. }
137. int main(int argc, char* argv[]) {
138. mongoc_init ();
139. mongoc_client_t* client = mongoc_client_new (<connection uri>);
140. bson_error_t error;

142. // connect to bank db
143. mongoc_database_t *database = mongoc_client_get_database (client, "bank");
144. // access account collection
145. mongoc_collection_t* collection = mongoc_client_get_collection(client, "bank", "account");
146. // set amount to transfer
147. int64_t amount_to_transfer = 500;
148. // delete the collection if already existing
149. mongoc_collection_drop(collection, &error);

151. // open Alice account
152. bson_t *alice_account = bson_new ();
153. BSON_APPEND_UTF8(alice_account, "name", "Alice");
154. BSON_APPEND_INT64(alice_account, "balance", 1000);

156. // open Bob account
157. bson_t *bob_account = bson_new ();
158. BSON_APPEND_UTF8(bob_account, "name", "Bob");
159. BSON_APPEND_INT64(bob_account, "balance", 1000);

161. bool r = true;

163. r = mongoc_collection_insert_one(collection, alice_account, NULL, NULL, &error);
164. if (!r) {printf("Error encountered:%s", error.message);}
165. r = mongoc_collection_insert_one(collection, bob_account, NULL, NULL, &error);
166. if (!r) {printf("Error encountered:%s", error.message);}

168. test_callback_money_transfer(client, collection, amount_to_transfer);

170. }

Python

The following code demonstrates how to utilize the Amazon DocumentDB transaction API with Python.


1. // Sample Python code with callback api

3. import pymongo

5. def callback(session, balance, query):
6. collection.update_one(query, {'$set': {"balance": balance}}, session=session)

8. client = pymongo.MongoClient(<connection uri>)
9. rc_snapshot = pymongo.read_concern.ReadConcern('snapshot')
10. wc_majority = pymongo.write_concern.WriteConcern('majority')

12. # To start, drop and create an account collection and insert balances for both Alice and Bob
13. collection = client.get_database("bank").get_collection("account")
14. collection.drop()
15. collection.insert_one({"_id": 1, "name": "Alice", "balance": 1000})
16. collection.insert_one({"_id": 2, "name": "Bob", "balance": 1000})

18. amount_to_transfer = 500

20. # deduct 500 from Alice's account
21. alice_balance = collection.find_one({"name": "Alice"}).get("balance")
22. assert alice_balance >= amount_to_transfer
23. new_alice_balance = alice_balance - amount_to_transfer

25. with client.start_session({'causalConsistency':False}) as session:
26. session.with_transaction(lambda s: callback(s, new_alice_balance, {"name": "Alice"}), read_concern=rc_snapshot, write_concern=wc_majority)

28. updated_alice_balance = collection.find_one({"name": "Alice"}).get("balance")
29. assert updated_alice_balance == new_alice_balance

31. # add 500 to Bob's account
32. bob_balance = collection.find_one({"name": "Bob"}).get("balance")
33. assert bob_balance >= amount_to_transfer
34. new_bob_balance = bob_balance + amount_to_transfer

36. with client.start_session({'causalConsistency':False}) as session:
37. session.with_transaction(lambda s: callback(s, new_bob_balance, {"name": "Bob"}), read_concern=rc_snapshot, write_concern=wc_majority)

39. updated_bob_balance = collection.find_one({"name": "Bob"}).get("balance")
40. assert updated_bob_balance == new_bob_balance
41. Sample Python code with Core api
42. import pymongo

44. client = pymongo.MongoClient(<connection_string>)
45. rc_snapshot = pymongo.read_concern.ReadConcern('snapshot')
46. wc_majority = pymongo.write_concern.WriteConcern('majority')

48. # To start, drop and create an account collection and insert balances for both Alice and Bob
49. collection = client.get_database("bank").get_collection("account")
50. collection.drop()
51. collection.insert_one({"_id": 1, "name": "Alice", "balance": 1000})
52. collection.insert_one({"_id": 2, "name": "Bob", "balance": 1000})

54. amount_to_transfer = 500

56. # deduct 500 from Alice's account
57. alice_balance = collection.find_one({"name": "Alice"}).get("balance")
58. assert alice_balance >= amount_to_transfer
59. new_alice_balance = alice_balance - amount_to_transfer

61. with client.start_session({'causalConsistency':False}) as session:
62. session.start_transaction(read_concern=rc_snapshot, write_concern=wc_majority)
63. collection.update_one({"name": "Alice"}, {'$set': {"balance": new_alice_balance}}, session=session)
64. session.commit_transaction()

66. updated_alice_balance = collection.find_one({"name": "Alice"}).get("balance")
67. assert updated_alice_balance == new_alice_balance

69. # add 500 to Bob's account
70. bob_balance = collection.find_one({"name": "Bob"}).get("balance")
71. assert bob_balance >= amount_to_transfer
72. new_bob_balance = bob_balance + amount_to_transfer

74. with client.start_session({'causalConsistency':False}) as session:
75. session.start_transaction(read_concern=rc_snapshot, write_concern=wc_majority)
76. collection.update_one({"name": "Bob"}, {'$set': {"balance": new_bob_balance}}, session=session)
77. session.commit_transaction()

79. updated_bob_balance = collection.find_one({"name": "Bob"}).get("balance")
80. assert updated_bob_balance == new_bob_balance

Transaction API Examples for Core API

Javascript

The following code demonstrates how to utilize the Amazon DocumentDB transaction API with Javascript.


1. // *** Transfer $500 from Alice to Bob inside a transaction: Success ***
2. // Setup bank account for Alice and Bob. Each have $1000 in their account
3. var databaseName = "bank";
4. var collectionName = "account";
5. var amountToTransfer = 500;

7. var session = db.getMongo().startSession({causalConsistency: false});
8. var bankDB = session.getDatabase(databaseName);
9. var accountColl = bankDB[collectionName];
10. accountColl.drop();

12. accountColl.insert({name: "Alice", balance: 1000});
13. accountColl.insert({name: "Bob", balance: 1000});

15. session.startTransaction();

17. // deduct $500 from Alice's account
18. var aliceBalance = accountColl.find({"name": "Alice"}).next().balance;
19. assert(aliceBalance >= amountToTransfer);
20. var newAliceBalance = aliceBalance - amountToTransfer;
21. accountColl.update({"name": "Alice"},{"$set": {"balance": newAliceBalance}});
22. var findAliceBalance = accountColl.find({"name": "Alice"}).next().balance;
23. assert.eq(newAliceBalance, findAliceBalance);

25. // add $500 to Bob's account
26. var bobBalance = accountColl.find({"name": "Bob"}).next().balance;
27. var newBobBalance = bobBalance + amountToTransfer;
28. accountColl.update({"name": "Bob"},{"$set": {"balance": newBobBalance}});
29. var findBobBalance = accountColl.find({"name": "Bob"}).next().balance;
30. assert.eq(newBobBalance, findBobBalance);

32. session.commitTransaction();

34. accountColl.find();

C#

The following code demonstrates how to utilize the Amazon DocumentDB transaction API with C#.


1. // C# Core API

3. public void TransferMoneyWithRetry(IMongoCollection<bSondocument> accountColl, IClientSessionHandle session)
4. {
5. var amountToTransfer = 500;

7. // start transaction
8. var transactionOptions = new TransactionOptions(
9. readConcern: ReadConcern.Snapshot,
10. writeConcern: WriteConcern.WMajority);
11. session.StartTransaction(transactionOptions);
12. try
13. {
14. // deduct $500 from Alice's account
15. var aliceBalance = accountColl.Find(session, Builders<bSondocument>.Filter.Eq("name", "Alice")).FirstOrDefault().GetValue("balance");
16. Debug.Assert(aliceBalance >= amountToTransfer);
17. var newAliceBalance = aliceBalance.AsInt32 - amountToTransfer;
18. accountColl.UpdateOne(session, Builders<bSondocument>.Filter.Eq("name", "Alice"),
19. Builders<bSondocument>.Update.Set("balance", newAliceBalance));
20. aliceBalance = accountColl.Find(session, Builders<bSondocument>.Filter.Eq("name", "Alice")).FirstOrDefault().GetValue("balance");
21. Debug.Assert(aliceBalance == newAliceBalance);

23. // add $500 from Bob's account
24. var bobBalance = accountColl.Find(session, Builders<bSondocument>.Filter.Eq("name", "Bob")).FirstOrDefault().GetValue("balance");
25. var newBobBalance = bobBalance.AsInt32 + amountToTransfer;
26. accountColl.UpdateOne(session, Builders<bSondocument>.Filter.Eq("name", "Bob"),
27. Builders<bSondocument>.Update.Set("balance", newBobBalance));
28. bobBalance = accountColl.Find(session, Builders<bSondocument>.Filter.Eq("name", "Bob")).FirstOrDefault().GetValue("balance");
29. Debug.Assert(bobBalance == newBobBalance);

31. }
32. catch (Exception e)
33. {
34. session.AbortTransaction();
35. throw;
36. }

38. session.CommitTransaction();
39. }

41. }
42. public void DoTransactionWithRetry(MongoClient client)
43. {
44. var dbName = "bank";
45. var collName = "account";
46. using (var session = client.StartSession(new ClientSessionOptions{CausalConsistency = false}))
47. {
48. try
49. {
50. var bankDB = client.GetDatabase(dbName);
51. var accountColl = bankDB.GetCollection<bSondocument>(collName);
52. bankDB.DropCollection(collName);
53. accountColl.InsertOne(session, new BsonDocument { {"name", "Alice"}, {"balance", 1000 } });
54. accountColl.InsertOne(session, new BsonDocument { {"name", "Bob"}, {"balance", 1000 } });

56. while(true) {
57. try
58. {
59. TransferMoneyWithRetry(accountColl, session);
60. break;
61. }
62. catch (MongoException e)
63. {
64. if(e.HasErrorLabel("TransientTransactionError"))
65. {
66. continue;
67. }
68. else
69. {
70. throw;
71. }
72. }
73. }

75. // check values outside of transaction
76. var aliceNewBalance = accountColl.Find(Builders<bSondocument>.Filter.Eq("name", "Alice")).FirstOrDefault().GetValue("balance");
77. var bobNewBalance = accountColl.Find(Builders<bSondocument>.Filter.Eq("name", "Bob")).FirstOrDefault().GetValue("balance");
78. Debug.Assert(aliceNewBalance ==  500);
79. Debug.Assert(bobNewBalance ==  1500);
80. }
81. catch (Exception e)
82. {
83. Console.WriteLine("Error running transaction: " + e.Message);
84. }
85. }
86. }

Ruby

The following code demonstrates how to utilize the Amazon DocumentDB transaction API with Ruby.


1. # Ruby Core API

3. def transfer_money_w_retry(session, accountColl)
4. amountToTransfer = 500

6. session.start_transaction(read_concern: {level: :snapshot}, write_concern: {w: :majority})
7. # deduct $500 from Alice's account
8. aliceBalance = accountColl.find({"name"=>"Alice"}, :session=> session).first['balance']
9. assert aliceBalance >= amountToTransfer
10. newAliceBalance = aliceBalance - amountToTransfer
11. accountColl.update_one({"name"=>"Alice"}, { "$set" => {"balance"=>newAliceBalance} }, :session=> session)
12. aliceBalance = accountColl.find({"name"=>"Alice"}, :session=> session).first['balance']
13. assert_equal(newAliceBalance, aliceBalance)

15. # add $500 to Bob's account
16. bobBalance = accountColl.find({"name"=>"Bob"}, :session=> session).first['balance']
17. newBobBalance = bobBalance + amountToTransfer
18. accountColl.update_one({"name"=>"Bob"}, { "$set" => {"balance"=>newBobBalance} }, :session=> session)
19. bobBalance = accountColl.find({"name"=>"Bob"}, :session=> session).first['balance']
20. assert_equal(newBobBalance, bobBalance)

22. session.commit_transaction

24. end

26. def do_txn_w_retry(client)
27. dbName = "bank"
28. collName = "account"

30. session = client.start_session(:causal_consistency=> false)
31. bankDB = Mongo::Database.new(client, dbName)
32. accountColl = bankDB[collName]
33. accountColl.drop()

35. accountColl.insert_one({"name"=>"Alice", "balance"=>1000})
36. accountColl.insert_one({"name"=>"Bob", "balance"=>1000})

38. begin
39. transferMoneyWithRetry(session, accountColl)
40. puts "transaction committed"
41. rescue Mongo::Error => e
42. if e.label?('TransientTransactionError')
43. retry
44. else
45. puts "transaction failed"
46. raise
47. end
48. end

50. # check results outside of transaction
51. aliceBalance = accountColl.find({"name"=>"Alice"}).first['balance']
52. bobBalance = accountColl.find({"name"=>"Bob"}).first['balance']
53. assert_equal(aliceBalance, 500)
54. assert_equal(bobBalance, 1500)

56. end

Java

The following code demonstrates how to utilize the Amazon DocumentDB transaction API with Java.


1. // Java (sync) - Core API

3. public void transferMoneyWithRetry() {
4. // connect to server
5. MongoClientURI mongoURI = new MongoClientURI(uri);
6. MongoClient mongoClient = new MongoClient(mongoURI);

8. MongoDatabase bankDB = mongoClient.getDatabase("bank");
9. MongoCollection accountColl = bankDB.getCollection("account");
10. accountColl.drop();

12. // insert some sample data
13. accountColl.insertOne(new Document("name", "Alice").append("balance", 1000));
14. accountColl.insertOne(new Document("name", "Bob").append("balance", 1000));

16. while (true) {
17. try {
18. doTransferMoneyWithRetry(accountColl, mongoClient);
19. break;
20. } catch (MongoException e) {
21. if (e.hasErrorLabel(MongoException.TRANSIENT_TRANSACTION_ERROR_LABEL)) {
22. continue;
23. } else {
24. throw e;
25. }
26. }
27. }
28. }

30. public void doTransferMoneyWithRetry(MongoCollection accountColl, MongoClient mongoClient) {
31. int amountToTransfer = 500;

33. TransactionOptions txnOptions = TransactionOptions.builder()
34. .readConcern(ReadConcern.SNAPSHOT)
35. .writeConcern(WriteConcern.MAJORITY)
36. .build();
37. ClientSessionOptions sessionOptions = ClientSessionOptions.builder().causallyConsistent(false).build();
38. try ( ClientSession clientSession = mongoClient.startSession(sessionOptions) ) {
39. clientSession.startTransaction(txnOptions);

41. // deduct $500 from Alice's account
42. List<Document> documentList = new ArrayList<>();
43. accountColl.find(clientSession, new Document("name", "Alice")).into(documentList);
44. int aliceBalance = (int) documentList.get(0).get("balance");
45. Assert.assertTrue(aliceBalance >= amountToTransfer);
46. int newAliceBalance = aliceBalance - amountToTransfer;
47. accountColl.updateOne(clientSession, new Document("name", "Alice"), new Document("$set", new Document("balance", newAliceBalance)));

49. // check Alice's new balance
50. documentList = new ArrayList<>();
51. accountColl.find(clientSession, new Document("name", "Alice")).into(documentList);
52. int updatedBalance = (int) documentList.get(0).get("balance");
53. Assert.assertEquals(updatedBalance, newAliceBalance);

55. // add $500 to Bob's account
56. documentList = new ArrayList<>();
57. accountColl.find(clientSession, new Document("name", "Bob")).into(documentList);
58. int bobBalance = (int) documentList.get(0).get("balance");
59. int newBobBalance = bobBalance + amountToTransfer;
60. accountColl.updateOne(clientSession, new Document("name", "Bob"), new Document("$set", new Document("balance", newBobBalance)));

62. // check Bob's new balance
63. documentList = new ArrayList<>();
64. accountColl.find(clientSession, new Document("name", "Bob")).into(documentList);
65. updatedBalance = (int) documentList.get(0).get("balance");
66. Assert.assertEquals(updatedBalance, newBobBalance);

68. // commit transaction
69. clientSession.commitTransaction();
70. }
71. }
72. // Java (async) -- Core API
73. public void transferMoneyWithRetry() {
74. // connect to the server
75. MongoClient mongoClient = MongoClients.create(uri);

77. MongoDatabase bankDB = mongoClient.getDatabase("bank");
78. MongoCollection accountColl = bankDB.getCollection("account");
79. SubscriberLatchWrapper<Void> dropCallback = new SubscriberLatchWrapper<>();
80. mongoClient.getDatabase("bank").drop().subscribe(dropCallback);
81. dropCallback.await();

83. // insert some sample data
84. SubscriberLatchWrapper<InsertOneResult> insertionCallback = new SubscriberLatchWrapper<>();
85. accountColl.insertOne(new Document("name", "Alice").append("balance", 1000)).subscribe(insertionCallback);
86. insertionCallback.await();

88. insertionCallback = new SubscriberLatchWrapper<>();
89. accountColl.insertOne(new Document("name", "Bob").append("balance", 1000)).subscribe(insertionCallback);;
90. insertionCallback.await();

92. while (true) {
93. try {
94. doTransferMoneyWithRetry(accountColl, mongoClient);
95. break;
96. } catch (MongoException e) {
97. if (e.hasErrorLabel(MongoException.TRANSIENT_TRANSACTION_ERROR_LABEL)) {
98. continue;
99. } else {
100. throw e;
101. }
102. }
103. }
104. }

106. public void doTransferMoneyWithRetry(MongoCollection accountColl, MongoClient mongoClient) {
107. int amountToTransfer = 500;

109. // start the transaction
110. TransactionOptions txnOptions = TransactionOptions.builder()
111. .readConcern(ReadConcern.SNAPSHOT)
112. .writeConcern(WriteConcern.MAJORITY)
113. .build();
114. ClientSessionOptions sessionOptions = ClientSessionOptions.builder().causallyConsistent(false).build();

116. SubscriberLatchWrapper<ClientSession> sessionCallback = new SubscriberLatchWrapper<>();
117. mongoClient.startSession(sessionOptions).subscribe(sessionCallback);
118. ClientSession session = sessionCallback.get().get(0);
119. session.startTransaction(txnOptions);

121. // deduct $500 from Alice's account
122. SubscriberLatchWrapper<Document> findCallback = new SubscriberLatchWrapper<>();
123. accountColl.find(session, new Document("name", "Alice")).first().subscribe(findCallback);
124. Document documentFound = findCallback.get().get(0);
125. int aliceBalance = (int) documentFound.get("balance");
126. int newAliceBalance = aliceBalance - amountToTransfer;

128. SubscriberLatchWrapper<UpdateResult> updateCallback = new SubscriberLatchWrapper<>();
129. accountColl.updateOne(session, new Document("name", "Alice"), new Document("$set", new Document("balance", newAliceBalance))).subscribe(updateCallback);
130. updateCallback.await();

132. // check Alice's new balance
133. findCallback = new SubscriberLatchWrapper<>();
134. accountColl.find(session, new Document("name", "Alice")).first().subscribe(findCallback);
135. documentFound = findCallback.get().get(0);
136. int updatedBalance = (int) documentFound.get("balance");
137. Assert.assertEquals(updatedBalance, newAliceBalance);

139. // add $500 to Bob's account
140. findCallback = new SubscriberLatchWrapper<>();
141. accountColl.find(session, new Document("name", "Bob")).first().subscribe(findCallback);
142. documentFound = findCallback.get().get(0);
143. int bobBalance = (int) documentFound.get("balance");
144. int newBobBalance = bobBalance + amountToTransfer;

146. updateCallback = new SubscriberLatchWrapper<>();
147. accountColl.updateOne(session, new Document("name", "Bob"), new Document("$set", new Document("balance", newBobBalance))).subscribe(updateCallback);
148. updateCallback.await();

150. // check Bob's new balance
151. findCallback = new SubscriberLatchWrapper<>();
152. accountColl.find(session, new Document("name", "Bob")).first().subscribe(findCallback);
153. documentFound = findCallback.get().get(0);
154. updatedBalance = (int) documentFound.get("balance");
155. Assert.assertEquals(updatedBalance, newBobBalance);

157. // commit the transaction
158. SubscriberLatchWrapper<Void> transactionCallback = new SubscriberLatchWrapper<>();
159. session.commitTransaction().subscribe(transactionCallback);
160. transactionCallback.await();
161. }

163. public class SubscriberLatchWrapper<T> implements Subscriber<T> {

165. /**
166. * A Subscriber that stores the publishers results and provides a latch so can block on completion.
167. *
168. * @param <T> The publishers result type
169. */
170. private final List<T> received;
171. private final List<RuntimeException> errors;
172. private final CountDownLatch latch;
173. private volatile Subscription subscription;
174. private volatile boolean completed;

176. /**
177. * Construct an instance
178. */
179. public SubscriberLatchWrapper() {
180. this.received = new ArrayList<>();
181. this.errors = new ArrayList<>();
182. this.latch = new CountDownLatch(1);
183. }

185. @Override
186. public void onSubscribe(final Subscription s) {
187. subscription = s;
188. subscription.request(Integer.MAX_VALUE);
189. }

191. @Override
192. public void onNext(final T t) {
193. received.add(t);
194. }

196. @Override
197. public void onError(final Throwable t) {
198. if (t instanceof RuntimeException) {
199. errors.add((RuntimeException) t);
200. } else {
201. errors.add(new RuntimeException("Unexpected exception", t));
202. }
203. onComplete();
204. }

206. @Override
207. public void onComplete() {
208. completed = true;
209. subscription.cancel();
210. latch.countDown();
211. }

213. /**
214. * Get received elements
215. *
216. * @return the list of received elements
217. */
218. public List<T> getReceived() {
219. return received;
220. }

222. /**
223. * Get received elements.
224. *
225. * @return the list of receive elements
226. */
227. public List<T> get() {
228. return await().getReceived();
229. }

231. /**
232. * Await completion or error
233. *
234. * @return this
235. */
236. public SubscriberLatchWrapper<T> await() {
237. subscription.request(Integer.MAX_VALUE);
238. try {
239. if (!latch.await(300, TimeUnit.SECONDS)) {
240. throw new MongoTimeoutException("Publisher onComplete timed out for 300 seconds");
241. }
242. } catch (InterruptedException e) {
243. throw new MongoInterruptedException("Interrupted waiting for observeration", e);
244. }
245. if (!errors.isEmpty()) {
246. throw errors.get(0);
247. }
248. return this;
249. }

251. public boolean getCompleted() {
252. return this.completed;
253. }

255. public void close() {
256. subscription.cancel();
257. received.clear();
258. }
259. }

C

The following code demonstrates how to utilize the Amazon DocumentDB transaction API with C.


1. // Sample C code with core session

3. bool core_session(mongoc_client_session_t *client_session, mongoc_collection_t* collection, bson_t *selector, int64_t balance){
4. bool r = true;
5. bson_error_t error;
6. bson_t *opts = bson_new();
7. bson_t *update = BCON_NEW ("$set", "{", "balance", BCON_INT64 (balance), "}");

9. // set read & write concern
10. mongoc_read_concern_t *read_concern = mongoc_read_concern_new ();
11. mongoc_write_concern_t *write_concern = mongoc_write_concern_new ();
12. mongoc_transaction_opt_t *txn_opts = mongoc_transaction_opts_new ();

14. mongoc_write_concern_set_w(write_concern, MONGOC_WRITE_CONCERN_W_MAJORITY);
15. mongoc_read_concern_set_level(read_concern, MONGOC_READ_CONCERN_LEVEL_SNAPSHOT);
16. mongoc_transaction_opts_set_write_concern (txn_opts, write_concern);
17. mongoc_transaction_opts_set_read_concern (txn_opts, read_concern);

19. mongoc_client_session_start_transaction (client_session, txn_opts, &error);
20. mongoc_client_session_append (client_session, opts, &error);

22. r = mongoc_collection_update_one (collection, selector, update, opts, NULL, &error);

24. mongoc_client_session_commit_transaction (client_session, NULL, &error);
25. bson_destroy (opts);
26. mongoc_transaction_opts_destroy(txn_opts);
27. mongoc_read_concern_destroy(read_concern);
28. mongoc_write_concern_destroy(write_concern);
29. bson_destroy (update);
30. return r;
31. }

33. void test_core_money_transfer(mongoc_client_t* client, mongoc_collection_t* collection, int amount_to_transfer){

35. bson_t reply;
36. bool r = true;
37. const bson_t *doc;
38. bson_iter_t iter;
39. bson_error_t error;

41. // find query
42. bson_t *alice_query = bson_new ();
43. BSON_APPEND_UTF8(alice_query, "name", "Alice");

45. bson_t *bob_query = bson_new ();
46. BSON_APPEND_UTF8(bob_query, "name", "Bob");

48. // create session
49. // set causal consistency to false
50. mongoc_session_opt_t *session_opts = mongoc_session_opts_new ();
51. mongoc_session_opts_set_causal_consistency (session_opts, false);
52. // start the session
53. mongoc_client_session_t *client_session = mongoc_client_start_session (client, session_opts, &error);

55. // add session to options
56. bson_t *opts = bson_new();
57. mongoc_client_session_append (client_session, opts, &error);

59. // deduct 500 from Alice
60. // find account balance of Alice
61. mongoc_cursor_t *cursor = mongoc_collection_find_with_opts (collection, alice_query, NULL, NULL);
62. mongoc_cursor_next (cursor, &doc);
63. bson_iter_init (&iter, doc);
64. bson_iter_find (&iter, "balance");
65. int64_t alice_balance = (bson_iter_value (&iter))->value.v_int64;
66. assert(alice_balance >= amount_to_transfer);
67. int64_t new_alice_balance = alice_balance - amount_to_transfer;

69. // core
70. r = core_session (client_session, collection, alice_query, new_alice_balance);
71. assert(r);

73. // find account balance of Alice after transaction
74. cursor = mongoc_collection_find_with_opts (collection, alice_query, NULL, NULL);
75. mongoc_cursor_next (cursor, &doc);
76. bson_iter_init (&iter, doc);
77. bson_iter_find (&iter, "balance");
78. alice_balance = (bson_iter_value (&iter))->value.v_int64;
79. assert(alice_balance == new_alice_balance);
80. assert(alice_balance == 500);

82. // add 500 to Bob's balance
83. // find account balance of Bob
84. cursor = mongoc_collection_find_with_opts (collection, bob_query, NULL, NULL);
85. mongoc_cursor_next (cursor, &doc);
86. bson_iter_init (&iter, doc);
87. bson_iter_find (&iter, "balance");
88. int64_t bob_balance = (bson_iter_value (&iter))->value.v_int64;
89. int64_t new_bob_balance = bob_balance + amount_to_transfer;

91. //core
92. r = core_session (client_session, collection, bob_query, new_bob_balance);
93. assert(r);

95. // find account balance of Bob after transaction
96. cursor = mongoc_collection_find_with_opts (collection, bob_query, NULL, NULL);
97. mongoc_cursor_next (cursor, &doc);
98. bson_iter_init (&iter, doc);
99. bson_iter_find (&iter, "balance");
100. bob_balance = (bson_iter_value (&iter))->value.v_int64;
101. assert(bob_balance == new_bob_balance);
102. assert(bob_balance == 1500);

104. // cleanup
105. bson_destroy(alice_query);
106. bson_destroy(bob_query);
107. mongoc_client_session_destroy(client_session);
108. bson_destroy(opts);
109. mongoc_cursor_destroy(cursor);
110. bson_destroy(doc);
111. }

113. int main(int argc, char* argv[]) {
114. mongoc_init ();
115. mongoc_client_t* client = mongoc_client_new (<connection uri>);
116. bson_error_t error;

118. // connect to bank db
119. mongoc_database_t *database = mongoc_client_get_database (client, "bank");
120. // access account collection
121. mongoc_collection_t* collection = mongoc_client_get_collection(client, "bank", "account");
122. // set amount to transfer
123. int64_t amount_to_transfer = 500;
124. // delete the collection if already existing
125. mongoc_collection_drop(collection, &error);

127. // open Alice account
128. bson_t *alice_account = bson_new ();
129. BSON_APPEND_UTF8(alice_account, "name", "Alice");
130. BSON_APPEND_INT64(alice_account, "balance", 1000);

132. // open Bob account
133. bson_t *bob_account = bson_new ();
134. BSON_APPEND_UTF8(bob_account, "name", "Bob");
135. BSON_APPEND_INT64(bob_account, "balance", 1000);

137. bool r = true;

139. r = mongoc_collection_insert_one(collection, alice_account, NULL, NULL, &error);
140. if (!r) {printf("Error encountered:%s", error.message);}
141. r = mongoc_collection_insert_one(collection, bob_account, NULL, NULL, &error);
142. if (!r) {printf("Error encountered:%s", error.message);}

144. test_core_money_transfer(client, collection, amount_to_transfer);

146. }

Scala

The following code demonstrates how to utilize the Amazon DocumentDB transaction API with Scala.


1. // Scala Core API
2. def transferMoneyWithRetry(sessionObservable: SingleObservable[ClientSession] , database: MongoDatabase ): Unit = {
3. val accountColl = database.getCollection("account")
4. var amountToTransfer = 500

6. var transactionObservable: Observable[ClientSession] = sessionObservable.map(clientSession => {
7. clientSession.startTransaction()

9. // deduct $500 from Alice's account
10. var aliceBalance = accountColl.find(clientSession, Document("name" -> "Alice")).await().head.getInteger("balance")
11. assert(aliceBalance >= amountToTransfer)
12. var newAliceBalance = aliceBalance - amountToTransfer
13. accountColl.updateOne(clientSession, Document("name" -> "Alice"), Document("$set" -> Document("balance" -> newAliceBalance))).await()
14. aliceBalance = accountColl.find(clientSession, Document("name" -> "Alice")).await().head.getInteger("balance")
15. assert(aliceBalance == newAliceBalance)

17. // add $500 to Bob's account
18. var bobBalance = accountColl.find(clientSession, Document("name" -> "Bob")).await().head.getInteger("balance")
19. var newBobBalance = bobBalance + amountToTransfer
20. accountColl.updateOne(clientSession, Document("name" -> "Bob"), Document("$set" -> Document("balance" -> newBobBalance))).await()
21. bobBalance = accountColl.find(clientSession, Document("name" -> "Bob")).await().head.getInteger("balance")
22. assert(bobBalance == newBobBalance)

24. clientSession
25. })

27. transactionObservable.flatMap(clientSession => clientSession.commitTransaction()).await()
28. }

30. def doTransactionWithRetry(): Unit = {
31. val client: MongoClient = MongoClientWrapper.getMongoClient()
32. val database: MongoDatabase = client.getDatabase("bank")
33. val accountColl = database.getCollection("account")
34. accountColl.drop().await()

36. val sessionOptions = ClientSessionOptions.builder().causallyConsistent(false).build()
37. var  sessionObservable: SingleObservable[ClientSession] = client.startSession(sessionOptions)
38. accountColl.insertOne(Document("name" -> "Alice", "balance" -> 1000)).await()
39. accountColl.insertOne(Document("name" -> "Bob", "balance" -> 1000)).await()

41. var retry = true
42. while (retry) {
43. try {
44. transferMoneyWithRetry(sessionObservable, database)
45. println("transaction committed")
46. retry = false
47. }
48. catch {
49. case e: MongoException if e.hasErrorLabel(MongoException.TRANSIENT_TRANSACTION_ERROR_LABEL) => {
50. println("retrying transaction")
51. }
52. case other: Throwable => {
53. println("transaction failed")
54. retry = false
55. throw other

57. }
58. }
59. }

61. // check results outside of transaction
62. assert(accountColl.find(Document("name" -> "Alice")).results().head.getInteger("balance") == 500)
63. assert(accountColl.find(Document("name" -> "Bob")).results().head.getInteger("balance") == 1500)

65. accountColl.drop().await()

67. }

Supported Commands

Command Supported
abortTransaction Yes
commitTransaction Yes
endSessions Yes
killSession Yes
killAllSession Yes
killAllSessionsByPattern No
refreshSessions No
startSession Yes

Unsupported Capabilities

Methods Stages or Commands
db.collection.aggregate() $collStats $currentOp $indexStats $listSessions $out
db.collection.count() db.collection.countDocuments() $where $near $nearSphere
db.collection.insert() insert is not supported if it is not run against an existing collection. This method is supported if it targets a pre-existing collection.

Sessions

MongoDB sessions are a framework that is used to support retryable writes, causal consistency, transactions, and manage operations across shards. When a session is created, a logical session identifier (lsid) is generated by the client and is used to tag all operations within that session when sending commands to the server.

Amazon DocumentDB supports the use of sessions to enable transactions, but does not support causal consistency or retryable writes.

When utilizing transactions within Amazon DocumentDB, a transaction will be initiated from within a session using the session.startTransaction() API and a session supports a single transaction at a time. Similarly, transactions are completed using either the commit (session.commitTransaction()) or abort (session.abortTransaction()) APIs.

Causal consistency

Causal consistency guarantees that within a single client session the client will observe read-after-write consistency, monatomic reads/writes, and writes will follow reads and these guarantees apply across all instances in a cluster, not just the primary. Amazon DocumentDB does not support causal consistency and the following statement will result in an error.


2. var mySession = db.getMongo().startSession();
3. var mySessionObject = mySession.getDatabase('test').getCollection('account');

5. mySessionObject.updateOne({"_id": 2}, {"$inc": {"balance": 400}});
6. //Result:{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

8. mySessionObject.find()
9. //Error: error: {
10. //         "ok" : 0,
11. //         "code" : 303,
12. //         "errmsg" : "Feature not supported: 'causal consistency'",
13. //         "operationTime" : Timestamp(1603461817, 493214)
14. //}

16. mySession.endSession()

You can disable causal consistency within a session. Please note, doing so will enable you to utilize the session framework, but will not provide causal consistency guarantees for reads. When using Amazon DocumentDB, reads from the primary will be read-after-write consistent and reads from the replica instances will be eventually consistent. Transactions are the primary use case for utilizing sessions.


2. var mySession = db.getMongo().startSession({causalConsistency: false});
3. var mySessionObject = mySession.getDatabase('test').getCollection('account');

5. mySessionObject.updateOne({"_id": 2}, {"$inc": {"balance": 400}});
6. //Result:{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

8. mySessionObject.find()
9. //{ "_id" : 1, "name" : "Bob", "balance" : 100 }
10. //{ "_id" : 2, "name" : "Alice", "balance" : 1700 }

Retryable writes

Retryable writes is a capability in which the client will attempt to retry write operations, one time, when network errors occur or if the client is unable to find the primary. In Amazon DocumentDB, retryable writes are not supported and must be disabled. You can disabled it with the command (retryWrites=false) in the connection string. Below is an example:


1. mongodb://chimera:<insertYourPassword>@docdb-2019-01-29-02-57-28.cluster-ccuszbx3pn5e.us-east-1.docdb.amazonaws.com:27017/?ssl=true&ssl_ca_certs=rds-combined-ca-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false

Transaction Errors

When using transactions, there are scenarios that can yeld an error that states that a transaction number does not match any in progress transaction.

The error can be generated in at least two different scenarios:

  • After the one-minute transaction timeout.
  • After an instance restart (due to patching, crash recovery, etc.), it is possible to receive this error even in cases where the transaction successfully committed. During an instance restart, the database can’t tell the difference between a transaction that successfully completed versus a transaction that aborted. In other words, the transaction completion state is ambiguous.

The best way to handle this error is to make transactional updates idempotent — for example, by using the $set mutator instead of an increment/decrement operation. See below:


1. { "ok" : 0,
2. "operationTime" : Timestamp(1603938167, 1),
3. "code" : 251,
4. "errmsg" : "Given transaction number 1 does not match any in-progress transactions."
5. }