Transactions

const session = db.getMongo().startSession()
const accounts = session.getDatabase('bank').accounts

session.withTransaction(() => {
  accounts.updateOne({ _id: 'ada' }, { $inc: { balance: -50 } })
  accounts.updateOne({ _id: 'ben' }, { $inc: { balance: 50 } })
})
session.endSession()

• A session groups operations. Every operation inside the transaction must use the session, here through session.getDatabase(...); in drivers, pass { session } to each call.
• withTransaction starts the transaction, runs your function, and commits if it finishes. If it throws, the transaction is aborted and none of its writes are kept.
• It also retries automatically when MongoDB reports a temporary error, such as a write conflict with another transaction.
• Manual control is available with startTransaction(), commitTransaction() and abortTransaction().

• Atomicity: all the transaction's writes are applied, or none are.
• Consistency: rules such as unique indexes and validation are checked for every write.
• Isolation: other operations don't see the transaction's changes until it commits (snapshot isolation).
• Durability: with write concern majority, committed data survives the failure of a server.

Transactions should be short. By default they time out after 60 seconds, and long transactions hold resources and cause conflicts with other writes.

Throw inside the transaction function when a rule fails, and everything is rolled back:

session.withTransaction(() => {
  const from = accounts.findOne({ _id: 'ada' })
  if (from.balance < 50) throw new Error('Insufficient funds')
  // ... both updates
})

A safer pattern puts the condition in the update filter, updateOne({ _id: 'ada', balance: { $gte: 50 } }, ...), and aborts if modifiedCount is 0, so the check and the change happen together.

Two transactions that change the same document at the same time can't both win. The second one to write gets a WriteConflict error straight away, instead of waiting, and the error carries the label TransientTransactionError:

s1.startTransaction(); s2.startTransaction()
a1.updateOne({ _id: 'ada' }, { $inc: { balance: -10 } })   // session 1 writes first
a2.updateOne({ _id: 'ada' }, { $inc: { balance: -20 } })   // session 2: WriteConflict

That label means "this transaction failed, but running the whole thing again may succeed". withTransaction checks for it and retries your function automatically, which is the main reason to prefer it over calling startTransaction and commitTransaction yourself. If you manage transactions manually, you need your own retry loop.

Inside a transaction, your reads see your own uncommitted changes, but nobody else does. A balance of 0 updated to 5 reads as 5 inside the session and still 0 from any other connection until the commit.

A few operations aren't allowed inside a transaction. You can't create an index on an existing collection, for example; that fails with "Cannot create new indexes on existing collection ... in a multi-document transaction". Creating a new collection by inserting into it does work in MongoDB 4.4 and later. Do schema changes such as indexes before the transaction, as part of your deployment, rather than inside it.

Transactions also need a replica set or sharded cluster. On a single standalone server, used by many local development setups, starting one fails, so run a single-member replica set locally if your code depends on them.