- Transactions >
- Drivers API
Drivers API¶
On this page
Callback API vs Core API¶
The Callback API:
- Starts a transaction, executes the specified operations, and commits (or aborts on error).
- Automatically incorporates error handling logic for "TransientTransactionError" and "UnknownTransactionCommitResult".
The Core API:
- Requires explicit call to start the transaction and commit the transaction.
- Does not incorporate error handling logic for "TransientTransactionError" and "UnknownTransactionCommitResult", and instead provides the flexibility to incorporate custom error handling for these errors.
Callback API¶
The new callback API incorporates logic:
- To retry the transaction as a whole if the transaction encounters a "TransientTransactionError".
- To retry the commit operation if the commit encounters an "UnknownTransactionCommitResult".
- Python
- Java (Sync)
- Node.js
- PHP
- C#
- Other
Important
- For transactions on MongoDB 4.2 deployments (replica sets and sharded clusters), clients must use MongoDB drivers updated for MongoDB 4.2.
- When using the drivers, each operation in the transaction must be associated with the session (i.e. pass in the session to each operation).
- Operations in a transaction use transaction-level read concern, transaction-level write concern, and transaction-level read preference.
The example uses the new callback API for working with transactions, which starts a transaction, executes the specified operations, and commits (or aborts on error). The new callback API incorporates retry logic for "TransientTransactionError" or "UnknownTransactionCommitResult" commit errors.
Important
- For transactions on MongoDB 4.2 deployments (replica sets and sharded clusters), clients must use MongoDB drivers updated for MongoDB 4.2.
- When using the drivers, each operation in the transaction must be associated with the session (i.e. pass in the session to each operation).
- Operations in a transaction use transaction-level read concern, transaction-level write concern, and transaction-level read preference.
The example uses the new callback API for working with transactions, which starts a transaction, executes the specified operations, and commits (or aborts on error). The new callback API incorporates retry logic for "TransientTransactionError" or "UnknownTransactionCommitResult" commit errors.
Important
- For transactions on MongoDB 4.2 deployments (replica sets and sharded clusters), clients must use MongoDB drivers updated for MongoDB 4.2.
- When using the drivers, each operation in the transaction must be associated with the session (i.e. pass in the session to each operation).
- Operations in a transaction use transaction-level read concern, transaction-level write concern, and transaction-level read preference.
The example uses the new callback API for working with transactions, which starts a transaction, executes the specified operations, and commits (or aborts on error). The new callback API incorporates retry logic for "TransientTransactionError" or "UnknownTransactionCommitResult" commit errors.
Important
- For transactions on MongoDB 4.2 deployments (replica sets and sharded clusters), clients must use MongoDB drivers updated for MongoDB 4.2.
- When using the drivers, each operation in the transaction must be associated with the session (i.e. pass in the session to each operation).
- Operations in a transaction use transaction-level read concern, transaction-level write concern, and transaction-level read preference.
The example uses the new callback API for working with transactions, which starts a transaction, executes the specified operations, and commits (or aborts on error). The new callback API incorporates retry logic for "TransientTransactionError" or "UnknownTransactionCommitResult" commit errors.
Important
- For transactions on MongoDB 4.2 deployments (replica sets and sharded clusters), clients must use MongoDB drivers updated for MongoDB 4.2.
- When using the drivers, each operation in the transaction must be associated with the session (i.e. pass in the session to each operation).
- Operations in a transaction use transaction-level read concern, transaction-level write concern, and transaction-level read preference.
The example uses the new callback API for working with transactions, which starts a transaction, executes the specified operations, and commits (or aborts on error). The new callback API incorporates retry logic for "TransientTransactionError" or "UnknownTransactionCommitResult" commit errors.
Important
- For transactions on MongoDB 4.2 deployments (replica sets and sharded clusters), clients must use MongoDB drivers updated for MongoDB 4.2.
- When using the drivers, each operation in the transaction must be associated with the session (i.e. pass in the session to each operation).
- Operations in a transaction use transaction-level read concern, transaction-level write concern, and transaction-level read preference.
The example uses the new callback API for working with transactions, which starts a transaction, executes the specified operations, and commits (or aborts on error). The new callback API incorporates retry logic for "TransientTransactionError" or "UnknownTransactionCommitResult" commit errors.
Important
- For transactions on MongoDB 4.2 deployments (replica sets and sharded clusters), clients must use MongoDB drivers updated for MongoDB 4.2.
- When using the drivers, each operation in the transaction must be associated with the session (i.e. pass in the session to each operation).
- Operations in a transaction use transaction-level read concern, transaction-level write concern, and transaction-level read preference.
The example uses the new callback API for working with transactions, which starts a transaction, executes the specified operations, and commits (or aborts on error). The new callback API incorporates retry logic for "TransientTransactionError" or "UnknownTransactionCommitResult" commit errors.
Important
- For transactions on MongoDB 4.2 deployments (replica sets and sharded clusters), clients must use MongoDB drivers updated for MongoDB 4.2.
- When using the drivers, each operation in the transaction must be associated with the session (i.e. pass in the session to each operation).
- Operations in a transaction use transaction-level read concern, transaction-level write concern, and transaction-level read preference.
The example uses the new callback API for working with transactions, which starts a transaction, executes the specified operations, and commits (or aborts on error). The new callback API incorporates retry logic for "TransientTransactionError" or "UnknownTransactionCommitResult" commit errors.
Core API¶
The core transaction API does not incorporate retry logic for errors labeled:
"TransientTransactionError". If an operation in a transaction returns an error labeled "TransientTransactionError", the transaction as a whole can be retried.
To handle "TransientTransactionError", applications should explicitly incorporate retry logic for the error.
"UnknownTransactionCommitResult". If the commit returns an error labeled "UnknownTransactionCommitResult", the commit can be retried.
To handle "UnknownTransactionCommitResult", applications should explicitly incorporate retry logic for the error.
The following example incorporates logic to retry the transaction for transient errors and retry the commit for unknown commit error:
- Python
- Java (Sync)
- Node.js
- PHP
- C
- Other
Important
To associate read and write operations with a transaction, you must pass the session to each operation in the transaction.
Important
To associate read and write operations with a transaction, you must pass the session to each operation in the transaction.
Important
To associate read and write operations with a transaction, you must pass the session to each operation in the transaction.
Important
To associate read and write operations with a transaction, you must pass the session to each operation in the transaction.
Important
To associate read and write operations with a transaction, you must pass the session to each operation in the transaction.
Important
To associate read and write operations with a transaction, you must pass the session to each operation in the transaction.
Important
To associate read and write operations with a transaction, you must pass the session to each operation in the transaction.
Driver Versions¶
For transactions on MongoDB 4.2 deployments (replica sets and sharded clusters), clients must use MongoDB drivers updated for MongoDB 4.2:
Transaction Error Handling¶
Regardless of the database system, whether MongoDB or relational databases, applications should take measures to handle errors during transaction commits and incorporate retry logic for transactions.
"TransientTransactionError"
¶
The individual write operations inside the transaction are not
retryable, regardless of the value of retryWrites
. If an
operation encounters an error associated with the label
"TransientTransactionError"
, such as when the primary steps down,
the transaction as a whole can be retried.
- The callback API incorporates retry logic for
"TransientTransactionError"
. - The core transaction API does not incorporate retry logic
for
"TransientTransactionError"
. To handle"TransientTransactionError"
, applications should explicitly incorporate retry logic for the error.
"UnknownTransactionCommitResult"
¶
The commit operations are retryable write operations. If the commit operation encounters an error,
MongoDB drivers retry the commit regardless of the value of
retryWrites
.
If the commit operation encounters an error labeled
"UnknownTransactionCommitResult"
, the commit can be retried.
- The callback API incorporates retry logic for
"UnknownTransactionCommitResult"
. - The core transaction API does not incorporate retry logic for
"UnknownTransactionCommitResult"
. To handle"UnknownTransactionCommitResult"
, applications should explicitly incorporate retry logic for the error.
Driver Version Errors¶
On sharded clusters with multiple mongos
instances,
performing transactions with drivers updated for MongoDB 4.0 (instead
of MongoDB 4.2) will fail and can result in errors, including:
Note
Your driver may return a different error. Refer to your driver’s documentation for details.
Error Code | Error Message |
---|---|
251 | cannot continue txnId -1 for session ... with txnId 1 |
50940 | cannot commit with no participants |
For transactions on MongoDB 4.2 deployments (replica sets and sharded clusters), use the MongoDB drivers updated for MongoDB 4.2
Additional Information¶
mongo
Shell Example¶
The following mongo
shell methods are available for
transactions:
Note
The mongo
shell example omits retry logic
and robust error handling for simplicity’s sake. For a
more practical example of incorporating transactions in
applications, see Transaction Error Handling instead.