Introduction to MongoDB transactions

Creating a transaction session

Transactions are typically written and executed from external applications via one of the API methods with the application language's appropriate MongoDB driver.

For the sake of demonstration, we'll walk through the creation of a transaction via the MongoDB shell. We'll work with an example database and collection to help conceptualize how transactions work in practice.

Note: If a transactions session runs for more than 60 seconds after the initial startTransaction() method, MongoDB will automatically abort the operation. This occurs because transactions are typically conducted in applications that work automatically rather than a person issuing commands in the shell. The following steps are for conceptualizing a transaction session from start to finish.

To begin, we have a simple database called literature with a collection called authors. Running a quick find() query, we can see the document structure with the author name and a title of theirs.

db.authors.find()

[
  {
    _id: ObjectId("620397dd4b871fc65c193106"),
    first_name: 'James',
    last_name: 'Joyce',
    title: 'Ulysses'
  },
  {
    _id: ObjectId("620398016ed0bb9e23785973"),
    first_name: 'William',
    last_name: 'Gibson',
    title: 'Neuromancer'
  },
  {
    _id: ObjectId("6203981d6ed0bb9e23785974"),
    first_name: 'George',
    last_name: 'Orwell',
    title: 'Homage to Catalonia'
  },
  {
    _id: ObjectId("620398516ed0bb9e23785975"),
    first_name: 'James',
    last_name: 'Baldwin',
    title: 'The Fire Next Time'
  }
]

Now that we have our database, we can show the steps to work with a transaction directly in the MongoDB shell. We'll also demonstrate how a transaction being conducted in one session may not be detectable to an outside source.

First, we need to create a session, same as you would when using the API.

var session = db.getMongo().startSession()

This newly created session variable will store the session object.

The next step is starting the transaction by calling the startTransaction() method:

session.startTransaction( 
    { "readConcern": { "level": "snapshot" },
      "writeConcern": { "w": "majority } 
     } 
)

The startTransaction() method has two options, readConcern and writeConcern. You can read in more detail about these options in MongoDB's documentation. We set the readConcern level to snapshot which returns data from a snapshot of majority committed data if the transaction commits with writeConcern "majority".

When you commit with w: "majority" write concern along with a read concern level of "snapshot", this guarantees that operations have a synchronized snapshot of majority-committed data. This configuration of write and read concern can be thought of as good defaults if no specific requirements.

The method will not return anything if successful, and if there is any error, then the transaction will need to be aborted which will be discussed shortly.

Working inside of the transaction session

Now that you have the transaction session started, you must run statements within the context of the session variable from the previous section.

It's helpful to represent your collection in a variable within the session to ease the syntax. You can do this as follows:

var authors = session.getDatabase('literature').getCollection('authors')

This newly created variable will work the as db.authors would when working in a shell outside of the transaction session. You can verify this by opening a second shell window, connecting to your cluster, and running db.authors.find(). Both statements will return the same documents.

Inside of the session, we now want to simulate what an external application might do and add a record to the database. We can do this in the following way to our authors collection:

authors.insertOne( { 
    "first_name": "Virginie", 
    "last_name": "Despentes", 
    "title": "Vernon Subutex") }
)

MongoDB will return a success:

{
  acknowledged: true,
  insertedId: ObjectId("6203a075c374636bc6976baa")
}

If we run authors.find() now in the session we'll return the previous results with our addition included:

[
  {
    _id: ObjectId("620397dd4b871fc65c193106"),
    first_name: 'James',
    last_name: 'Joyce',
    best_title: 'Ulysses'
  },
  {
    _id: ObjectId("620398016ed0bb9e23785973"),
    first_name: 'William',
    last_name: 'Gibson',
    best_title: 'Neuromancer'
  },
  {
    _id: ObjectId("6203981d6ed0bb9e23785974"),
    first_name: 'George',
    last_name: 'Orwell',
    best_title: 'Homage to Catalonia'
  },
  {
    _id: ObjectId("620398516ed0bb9e23785975"),
    first_name: 'James',
    last_name: 'Baldwin',
    best_title: 'The Fire Next Time'
  },
  {
    _id: ObjectId("6203a075c374636bc6976baa"),
    first_name: 'Virginie',
    last_name: 'Despentes',
    best_title: 'Vernon Subutex'
  }
]

Since this transaction session has still not been committed, we will not see it return the same result in a MongoDB shell existing outside of the session. To confirm, we run db.authors.find() in another MongoDB shell instance and we return the original documents.

[
  {
    _id: ObjectId("620397dd4b871fc65c193106"),
    first_name: 'James',
    last_name: 'Joyce',
    best_title: 'Ulysses'
  },
  {
    _id: ObjectId("620398016ed0bb9e23785973"),
    first_name: 'William',
    last_name: 'Gibson',
    best_title: 'Neuromancer'
  },
  {
    _id: ObjectId("6203981d6ed0bb9e23785974"),
    first_name: 'George',
    last_name: 'Orwell',
    best_title: 'Homage to Catalonia'
  },
  {
    _id: ObjectId("620398516ed0bb9e23785975"),
    first_name: 'James',
    last_name: 'Baldwin',
    best_title: 'The Fire Next Time'
  }
]

This difference demonstrates that the transaction is still currently in a state of ambiguity. It can still either succeed and be committed to the database or it could fail and be aborted. Either way, the database will end up in a consistent state. It will include the new record or incur a rollback to the same state as before the transaction session started.

We run the commitTransaction() method in the session to commit the transaction and bring the database to the new consistent state:

session.commitTransaction()

Now, the new record will exist in both instances, the MongoDB shell where the transaction session was taking place and the MongoDB shell outside of the transaction.

Aborting a transaction

Now that we have gone from starting a session all the way to committing it, we can explore the alternative result for a transaction.

This path begins the same and changes only at the commit point. If we want to discard the changes the transaction is making, then we use the abortTransaction() method as follows in the session shell:

session.abortTransaction()

This method cancels the transaction session and discards any potential changes. Instead of resulting in a new consistent state, the database rolls back the changes and stays the same as when the transaction session first started.