Session.withTransaction()

Definition

Session.withTransaction( <function> [, <options> ] )

New in mongosh v1.1.0

Runs a specified lambda function within a transaction. If there is an error, the method retries the:

• commit operation, if there is a failure to commit.

• entire transaction, if the error permits.

The Session.withTransaction() method accepts the transaction options.

Returns:	The value produced by the callback function.

Important

mongosh Method

This page documents a mongosh method. This is not the documentation for database commands or language-specific drivers, such as Node.js.

For the database command, see the commitTransaction command.

For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.

Compatibility

This method is available in deployments hosted in the following environments:

• MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

• MongoDB Enterprise: The subscription-based, self-managed version of MongoDB

• MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Behavior

The Node.js driver has a version of Session.withTransaction() that is known as the Callback API. The Callback API also accepts an callback, however the return type for the Node.js method must be a Promise. The mongosh Session.withTransaction() method does not require a Promise. Example -------

The following example creates the balances collection and uses a transaction to transfer money between two customers.

Create the balances collection:

use accounts
db.balances.insertMany( [
  { customer: "Pat", balance: Decimal128( "35.88" ) },
  { customer: "Sasha", balance: Decimal128( "5.23" ) }
] )

Initialize some variables that are used in the transaction:

var fromAccount = "Pat"
var toAccount = "Sasha"
var transferAmount = 1
var dbName = "accounts"
var collectionName = "balances"

Start a session, then run a transaction to update the accounts:

var session = db.getMongo().startSession( { readPreference: { mode: "primary" } } );
session.withTransaction( async() => {
   const sessionCollection = session.getDatabase(dbName).getCollection(collectionName);
   // Check needed values
   var checkFromAccount = sessionCollection.findOne(
      {
         "customer": fromAccount,
         "balance": { $gte: transferAmount }
      }
   )
   if( checkFromAccount === null ){
      throw new Error( "Problem with sender account" )
   }
   var checkToAccount = sessionCollection.findOne(
      { "customer": toAccount }
   )
   if( checkToAccount === null ){
      throw new Error( "Problem with receiver account" )
   }
   // Transfer the funds
   sessionCollection.updateOne(
      { "customer": toAccount },
      { $inc: { "balance": transferAmount } }
   )
   sessionCollection.updateOne(
      { "customer": fromAccount },
      { $inc: { "balance": -1 * transferAmount } }
   )
 } )

The lambda function includes initial checks to validate the operation before updating the balances collection.

MongoDB automatically completes the transaction.

• If both updateOne() operations succeed, Session.withTransaction() commits the transaction when the callback returns.

• If an exception is thrown inside the callback, Session.withTransaction() ends the transaction and rolls back any uncommitted changes.