From c91d9b1a9f1627311d72c6a9007850a7cdeaa274 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Thu, 18 Jan 2024 15:39:10 -0500 Subject: [PATCH] DOCSP-34822: commitTxn is idempotent (#337) * DOCSP-34822: commitTxn is idempotent * vale fixes * Server clarification * JS PR fix * language (cherry picked from commit 40d675e20180d4371b431097fe8bc95b1a3b74c2) --- .../crud/write-operations/insert.txt | 2 +- source/fundamentals/transactions.txt | 72 +++++++++++-------- 2 files changed, 45 insertions(+), 29 deletions(-) diff --git a/source/fundamentals/crud/write-operations/insert.txt b/source/fundamentals/crud/write-operations/insert.txt index b10ffa19..b8e9221e 100644 --- a/source/fundamentals/crud/write-operations/insert.txt +++ b/source/fundamentals/crud/write-operations/insert.txt @@ -195,7 +195,7 @@ to set with ``InsertManyOptions`` are: * - ``Ordered`` - | If ``true``, the driver sends documents to the server in the order provided. - If an error occurs, the driver and server abort all remaining insert operations. + If an error occurs, the driver and server end all remaining insert operations. To learn more, see :ref:`golang-ordered-behavior`. | Default: ``false`` diff --git a/source/fundamentals/transactions.txt b/source/fundamentals/transactions.txt index 79e60c03..14d8af48 100644 --- a/source/fundamentals/transactions.txt +++ b/source/fundamentals/transactions.txt @@ -20,23 +20,24 @@ Transactions Overview -------- -In this guide, you can learn how to use **transactions** with the -{+driver-long+}. :manual:`Transactions ` allow you -to run a series of operations that do not change any data until the -transaction is committed. If any operation in the transaction fails, the -driver cancels the transaction and discards all data changes before they -ever become visible. +In this guide, you can learn how to use the {+driver-long+} to perform +**transactions**. :manual:`Transactions ` allow +you to run a series of operations that do not change any data until the +transaction is committed. If any operation in the transaction returns an +error, the driver cancels the transaction and discards all data changes +before they ever become visible. In MongoDB, transactions run within logical **sessions**. A -:manual:`session ` is a -grouping of related read or write operations that you intend to run -sequentially. Sessions enable :manual:`causal consistency ` -for a group of operations or allow you to execute operations in an :website:`ACID -transaction `. MongoDB guarantees that the data -involved in your transaction operations remains consistent, even if the operations -encounter unexpected errors. - -With the {+driver-short+}, you can create a new session from a +:manual:`session ` is a grouping of related +read or write operations that you intend to run sequentially. Sessions +enable :manual:`causal consistency +` for a +group of operations or allow you to execute operations in an +:website:`ACID transaction `. MongoDB +guarantees that the data involved in your transaction operations remains +consistent, even if the operations encounter unexpected errors. + +When using the {+driver-short+}, you can create a new session from a ``Client`` instance as a ``Session`` type. We recommend that you reuse your client for multiple sessions and transactions instead of instantiating a new client each time. @@ -45,7 +46,7 @@ instantiating a new client each time. Use a ``Session`` only with the ``Client`` (or associated ``Database`` or ``Collection``) that created it. Using a - ``Session`` with a different ``Client`` will result in operation + ``Session`` with a different ``Client`` results in operation errors. .. warning:: @@ -56,8 +57,8 @@ instantiating a new client each time. Methods ------- -After you start a session using the ``StartSession()`` method, you can modify -the session state using the method set provided by the ``Session`` interface. The +After you start a session by using the ``StartSession()`` method, you can modify +the session state by using the method set provided by the ``Session`` interface. The following table describes these methods: .. list-table:: @@ -70,26 +71,41 @@ following table describes these methods: * - ``StartTransaction()`` - | Starts a new transaction, configured with the given options, on this session. Returns an error if there is already - a transaction in progress for the session. For more - information, see the :manual:`manual entry `. + a transaction in progress for the session. To learn more about + this method, see the :manual:`startTransaction() page + ` in the Server manual. | | **Parameter**: ``TransactionOptions`` | **Return Type**: ``error`` * - ``AbortTransaction()`` - - | Aborts the active transaction for this session. Returns an + - | Ends the active transaction for this session. Returns an error if there is no active transaction for the session or the - transaction has been committed or aborted. For more - information, see the :manual:`manual entry `. + transaction has been committed or ended. To learn more about + this method, see the :manual:`abortTransaction() page + ` in the Server manual. | | **Parameter**: ``Context`` | **Return Type**: ``error`` * - ``CommitTransaction()`` - | Commits the active transaction for this session. Returns an - error if there is no active transaction for the session or the - transaction has been aborted. For more - information, see the :manual:`manual entry `. + error if there is no active transaction for the session or if the + transaction was ended. To learn more about + this method, see the :manual:`commitTransaction() page + ` in the Server manual. + + .. note:: Retrying a Transaction + + The ``CommitTransaction()`` method is an idempotent function, which + means that you can attempt to commit a transaction multiple times + without changing data after the first successful commit. + + A transaction can succeed but return an error with the + ``UnknownTransactionCommitResult`` label. If you rerun the + ``CommitTransaction()`` method after receiving this error, + your data is not changed by the repeat attempts. + | | **Parameter**: ``Context`` | **Return Type**: ``error`` @@ -102,7 +118,7 @@ following table describes these methods: | **Return Type**: ``interface{}``, ``error`` * - ``EndSession()`` - - | Aborts any existing transactions and closes the session. + - | Ends any existing transactions and closes the session. | | **Parameter**: ``Context`` | **Return Type**: none @@ -133,7 +149,7 @@ following steps: :end-before: end-session If you require more control over your transactions, you can find an example -showing how to manually create, commit, and abort transactions in the +showing how to manually create, commit, and end transactions in the `full code example `__. Additional Information