Docs Menu

Docs HomeMongoDB Manual

Session.withTransaction()

On this page

  • Definition
  • Behavior
  • Example
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.

The Node.js driver has a version of Session.withTransaction()` that is known as the `Callback API <https://www.mongodb.com/docs/drivers/node/current/fundamentals/transactions/#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.

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.

Note

By default, MongoDB ends transactions that run for more than 60 seconds. If you want to extend the default timeout to experiment with transactions in mongosh, see Runtime Limit.

What is MongoDB? →
Share Feedback
© 2023 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2023 MongoDB, Inc.