Session.withTransaction()
On this page
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
Note
This command is supported in all MongoDB Atlas clusters. For information on all commands, see Unsupported Commands.
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.
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.