With the launch of MongoDB 4.0 compatibility, Amazon DocumentDB (with MongoDB compatibility) now supports performing 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 processes, fulfilling and managing orders, and building multi-player games. In this post, I show you how to use transactions for common uses cases. To get started with Amazon DocumentDB 4.0 and transactions, see Transactions.
The need for transactions predates the modern computer by centuries. Since people have been keeping books (or tablets, if you will) to track account balances, the need to debit and credit money from one account to another has existed. When money is subtracted from one bank account and added to another bank account, it’s desirable for those two operations to exhibit a set of properties so operations behave as expected without error. Within a database, transactions are often described with the properties of being ACID:
- Atomic – All or none. Either all the operations within a transaction complete successfully, or none of them do.
- Consistent – A transaction never leaves the database in an inconsistent state.
- Isolated – Each transaction operated on the databases doesn’t interfere with other ongoing transactions.
- Durable – When the transaction is complete, the changes made to the database are permanent and durable.
To get started with transactions, I discuss four use cases to highlight some of the common scenarios for transactions and show you how to use the API using the mongo shell. To learn more about transactions in Amazon DocumentDB, see Amazon DocumentDB Quotas and Limits.
Use case 1: Multi-statement transaction
One of the canonical use cases for transactions is debiting money from one person’s account and crediting that money in another person’s account. Given that the use case deals with two operations in the database, it’s desirable that the two operations run within a transaction and follow the ACID properties. In this use case, the transaction operates on multiple documents within the same collection to transfer $400 from Sam’s bank account to Joe’s bank account. See the following code:
Use case 2: Multi-collection transaction
In addition to running transactions that operate on multiple documents in the same collection, you can run transactions across multiple collections. In the following code, I keep a user’s profile up-to-date with an order count while also placing a new order in the orders collection:
Use case 3: Stopping a transaction
The following code shows how to stop an ongoing transaction and how the resulting output doesn’t affect the end state of the database:
Use case 4: Stopping a transaction due to a write conflict
When attempting to modify a single document from two different transactions, if the data is modified by one transaction, the action can impact other transactions. When one transaction (which we refer to as transaction #2) attempts to modify data that has already been modified by another transaction (transaction #1) but not yet committed, the database throws a
WriteConflict error for transaction #2, and transaction #2 is stopped. Because you can’t have multiple transactions each updating the same data, it’s a best practice is to keep transactions small so that they don’t tie up many documents in the database. See the following code:
When developing with transactions, it’s advisable to use transactions for short UPDATE, INSERT, and DELETE use cases as opposed to long-running read queries. In Amazon DocumentDB, similar to MongoDB 4.0, transactions must complete within a minute or the transactions time out. Additionally, the
oplog entry for a single transaction must be less than 32 MB. For more information about limits, see Amazon DocumentDB Quotas and Limits. Therefore, if the business logic for a transaction can be split between multiple transactions, it’s advisable to issue multiple smaller transitions than one long transaction.
Lastly, always commit or end a transaction. Transactions that are left open use system resources, cause operations outside of the transaction to block on the completion of the transaction, and can cause write conflicts between transactions, as we showed earlier. For more best practices, see Transactions.
Support for MongoDB 4.0 compatibility and transactions allows you to perform ACID operations across one or more documents within an Amazon DocumentDB cluster. To learn more, see MongoDB 4.0 Compatibility.
About the author
Joseph Idziorek is a Principal Product Manager at Amazon Web Services.