How to Use MongoDB Transactions in Node.js
Rate this quickstart
Developers who move from relational databases to MongoDB commonly ask, "Does MongoDB support ACID transactions? If so, how do you create a transaction?" The answer to the first question is, "Yes!"
Beginning in 4.0, MongoDB added support for multi-document ACID transactions, and, beginning in 4.2, MongoDB added support for distributed ACID transactions. If you're not familiar with what ACID transactions are or if you should be using them in MongoDB, check out my earlier post on the subject.
This post uses MongoDB 4.0, MongoDB Node.js Driver 3.3.2, and Node.js 10.16.3.
We're over halfway through the Quick Start with MongoDB and Node.js series. We began by walking through how to connect to MongoDB and perform each of the CRUD (Create, Read, Update, and Delete) operations. Then we jumped into more advanced topics like the aggregation framework.
The code we write today will use the same structure as the code we built in the first post in the series; so, if you have any questions about how to get started or how the code is structured, head back to that first post.
Now let's dive into that second question developers ask—let's discover how to create a transaction!
Want to see transactions in action? Check out the video below! It covers the same topics you'll read about in this article.
Get started with an M0 cluster on Atlas today. It's free forever, and it's the easiest way to try out the steps in this blog series.
As you may have experienced while working with MongoDB, most use cases do not require you to use multi-document transactions. When you model your data using our rule of thumb Data that is accessed together should be stored together, you'll find that you rarely need to use a multi-document transaction. In fact, I struggled a bit to think of a use case for the Airbnb dataset that would require a multi-document transaction.
After a bit of brainstorming, I came up with a somewhat plausible example. Let's say we want to allow users to create reservations in the
sample_airbnb database.We could begin by creating a collection named
users. We want users to be able to easily view their reservations when they are looking at their profiles, so we will store the reservations as embedded documents in the users collection. For example, let's say a user named Leslie creates two reservations. Her document in the users collection would look like the following:
When browsing Airbnb listings, users need to know if the listing is already booked for their travel dates. As a result, we want to store the dates the listing is reserved in the
listingsAndReviews collection. For example, the "Infinite Views" listing that Leslie reserved should be updated to list her reservation dates.Keeping these two records in sync is imperative. If we were to create a reservation in a document in the
users collection without updating the associated document in the listingsAndReviews collection, our data would be inconsistent. We can use a multi-document transaction to ensure both updates succeed or fail together.As with all posts in this MongoDB and Node.js Quick Start series, you'll need to ensure you've completed the prerequisite steps outlined in the Set up section of the first post in this series.
Note: To utilize transactions, MongoDB must be configured as a replica set or a sharded cluster. Transactions are not supported on standalone deployments. If you are using a database hosted on Atlas, you do not need to worry about this as every Atlas cluster is either a replica set or a sharded cluster. If you are hosting your own standalone deployment, follow these instructions to convert your instance to a replica set.
We'll be using the "Infinite Views" Airbnb listing we created in a previous post in this series. Hop back to the post on Creating Documents if your database doesn't currently have the "Infinite Views" listing.
The Airbnb sample dataset only has the
listingsAndReviews collection by default. To help you quickly create the necessary collection and data, I wrote usersCollection.js. Download a copy of the file, update the uri constant to reflect your Atlas connection info, and run the script by executing node usersCollection.js. The script will create three new users in the users collection: Leslie Yepp, April Ludfence, and Tom Haverdodge. If the users collection does not already exist, MongoDB will automatically create it for you when you insert the new users. The script also creates an index on the email field in the users collection. The index requires that every document in the users collection has a unique email.Now that we are set up, let's implement the functionality to store Airbnb reservations.
To make following along with this blog post easier, I've created a starter template for a Node.js script that accesses an Atlas cluster.
- Open
template.jsin your favorite code editor. - Update the Connection URI to point to your Atlas cluster. If you're not sure how to do that, refer back to the first post in this series.
- Save the file as
transaction.js.
You can run this file by executing
node transaction.js in your shell. At this point, the file simply opens and closes a connection to your Atlas cluster, so no output is expected. If you see DeprecationWarnings, you can ignore them for the purposes of this post.Let's create a helper function. This function will generate a reservation document that we will use later.
- Paste the following function in
transaction.js:
To give you an idea of what this function is doing, let me show you an example. We could call this function from inside of
main():The function would return the following:
Let's create a function whose job is to create the reservation in the database.
- Continuing to work in
transaction.js, create an asynchronous function namedcreateReservation. The function should accept aMongoClient, the user's email address, the name of the Airbnb listing, the reservation dates, and any other reservation details as parameters. - Now we need to access the collections we will update in this function. Add the following code to
createReservation(). - Let's create our reservation document by calling the helper function we created in the previous section. Paste the following code in
createReservation(). - Every transaction and its operations must be associated with a session. Beneath the existing code in
createReservation(), start a session. - We can choose to define options for the transaction. We won't get into the details of those here. You can learn more about these options in the driver documentation. Paste the following beneath the existing code in
createReservation(). - Now we're ready to start working with our transaction. Beneath the existing code in
createReservation(), open atry { }block, follow it with acatch { }block, and finish it with afinally { }block. - We can use ClientSession's withTransaction() to start a transaction, execute a callback function, and commit (or abort on error) the transaction.
withTransaction()requires us to pass a function that will be run inside the transaction. Add a call towithTransaction()inside oftry { }. Let's begin by passing an anonymous asynchronous function towithTransaction(). - The anonymous callback function we are passing to
withTransaction()doesn't currently do anything. Let's start to incrementally build the database operations we want to call from inside of that function. We can begin by adding a reservation to thereservationsarray inside of the appropriateuserdocument. Paste the following inside of the anonymous function that is being passed towithTransaction(). - Since we want to make sure that an Airbnb listing is not double-booked for any given date, we should check if the reservation date is already listed in the listing's
datesReservedarray. If so, we should abort the transaction. Aborting the transaction will rollback the update to the user document we made in the previous step. Paste the following beneath the existing code in the anonymous function. - The final thing we want to do inside of our transaction is add the reservation dates to the
datesReservedarray in thelistingsAndReviewscollection. Paste the following beneath the existing code in the anonymous function. - We'll want to know if the transaction succeeds. If
transactionResultsis defined, we know the transaction succeeded. IftransactionResultsis undefined, we know that we aborted it intentionally in our code. Beneath the definition of thetransactionResultsconstant, paste the following code. - Let's log any errors that are thrown. Paste the following inside of
catch(e){ }: - Regardless of what happens, we need to end our session. Paste the following inside of
finally { }:At this point, your function should look like the following:
Now that we've written a function that creates a reservation using a transaction, let's try it out! Let's create a reservation for Leslie at the "Infinite Views" listing for the nights of December 31, 2019 and January 1, 2020.
- Inside of
main()beneath the comment that saysMake the appropriate DB calls, call yourcreateReservation()function: - Save your file.
- Run your script by executing
node transaction.jsin your shell. - The following output will be displayed in your shell.Leslie's document in the
userscollection now contains the reservation.The "Infinite Views" listing in thelistingsAndReviewscollection now contains the reservation dates.
Today, we implemented a multi-document transaction. Transactions are really handy when you need to make changes to more than one document as an all-or-nothing operation.
Be sure you are using the correct read and write concerns when creating a transaction. See the MongoDB documentation for more information.
When you use relational databases, related data is commonly split between different tables in an effort to normalize the data. As a result, transaction usage is fairly common.
When you use MongoDB, data that is accessed together should be stored together. When you model your data this way, you will likely find that you rarely need to use transactions.
This post included many code snippets that built on code written in the first post of this MongoDB and Node.js Quick Start series. To get a full copy of the code used in today's post, visit the Node.js Quick Start GitHub Repo.
Now you're ready to try change streams and triggers. Check out the next post in this series to learn more!
Questions? Comments? We'd love to connect with you. Join the conversation on the MongoDB Community Forums.
Rate this quickstart