From 6d7676585b0cc87797584ff5f247c30ef770d467 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Fri, 13 Jun 2025 10:54:26 -0400 Subject: [PATCH 01/11] DOCSP-35201 add section linking to solutions for transaction retry logic in node Core API --- source/crud/transactions.txt | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index 4a82050d4..02041bd0a 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -311,12 +311,17 @@ error-handling logic into your application for the following errors: before the driver commits the transaction. To learn more about this error, see the :manual:`TransientTransactionError description ` on - the Driver API page in the Server manual. + the Drivers API page in the Server manual. - ``UnknownTransactionCommitResult``: Raised if the commit operation encounters an error. To learn more about this error, see the :manual:`UnknownTransactionCommitResult description ` on - the Driver API page in the Server manual. + the Drivers API page in the Server manual. + +To learn how to implement retry logic to prevent these errors while using the +Core API, see the :manual:`Core API section +` on the Drivers API page in the +Server manual. The Convenient Transaction API incorporates retry logic for these error types, so the driver retries the transaction until there is a successful commit. \ No newline at end of file From f638d05b0718b0f62bb82290094bafe0b194fc99 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Fri, 13 Jun 2025 11:32:33 -0400 Subject: [PATCH 02/11] DOCSP-35201 adding more details for retry logic --- source/crud/transactions.txt | 37 ++++++++++++++++++------------------ 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index 02041bd0a..25a3c7180 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -304,24 +304,25 @@ the ``startTransaction()`` method: Transaction Errors ------------------ -If you are using the Core API to perform a transaction, you must incorporate -error-handling logic into your application for the following errors: - -- ``TransientTransactionError``: Raised if a write operation errors - before the driver commits the transaction. To learn more about this error, see the - :manual:`TransientTransactionError description - ` on - the Drivers API page in the Server manual. -- ``UnknownTransactionCommitResult``: Raised if the commit operation - encounters an error. To learn more about this error, see the - :manual:`UnknownTransactionCommitResult description - ` on - the Drivers API page in the Server manual. - -To learn how to implement retry logic to prevent these errors while using the -Core API, see the :manual:`Core API section +Since MongoDB transactions are :website:`ACID compliant +`, the driver may produce errors during operation to +ensure your data maintains consistent. If the following errors occur, the +transaction must be retried: + +- ``TransientTransactionError``: Raised if a write operation encounters an error + before the driver commits the transaction. +- ``UnknownTransactionCommitResult``: Raised if the commit operation encounters + an error. + +If you are using the Core API to perform a transaction, you must implement the +error-handling logic into your application. To do so, you must create separate +functions within your application that explicitly retry transaction and commit +operations when these errors are detected. To see an +example of this retry logic, see the :manual:`Core API section ` on the Drivers API page in the Server manual. -The Convenient Transaction API incorporates retry logic for these error -types, so the driver retries the transaction until there is a successful commit. \ No newline at end of file +The Convenient Transaction API incorporates retry logic for these error types, +so the driver automatically retries the transaction until there is a successful +commit. You do not have to explicitly declare functions for the API to retry +transaction operations with these errors. \ No newline at end of file From 578bfd157bcd0495de88267177149b81e81b8334 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Fri, 13 Jun 2025 11:57:51 -0400 Subject: [PATCH 03/11] DOCSP-35201 edit for clarity, add list of functions --- source/crud/transactions.txt | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index 25a3c7180..ad7d79f45 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -315,14 +315,20 @@ transaction must be retried: an error. If you are using the Core API to perform a transaction, you must implement the -error-handling logic into your application. To do so, you must create separate -functions within your application that explicitly retry transaction and commit -operations when these errors are detected. To see an -example of this retry logic, see the :manual:`Core API section +error-handling logic into your application. To do so, you must create the following functions: + +- A function that retries the entire transaction when the driver encounters a + ``TransientTransactionError`` +- A function that retries the commit operation when the driver encounters an + ``UnknownTransactionCommitResult`` + +These functions should continue to retry the operation until there is a +successful commit or a different error. For an example of this retry +logic, see the :manual:`Core API section ` on the Drivers API page in the Server manual. The Convenient Transaction API incorporates retry logic for these error types, so the driver automatically retries the transaction until there is a successful commit. You do not have to explicitly declare functions for the API to retry -transaction operations with these errors. \ No newline at end of file +transaction operations when the driver produces these errors. \ No newline at end of file From b668668748a0b994f54c63d9643ed8d54db27cb5 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Fri, 13 Jun 2025 12:34:53 -0400 Subject: [PATCH 04/11] DOCSP-35201 restructuring for clarity and brevity --- source/crud/transactions.txt | 34 +++++++++++++++++++++------------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index ad7d79f45..00863ce95 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -310,25 +310,33 @@ ensure your data maintains consistent. If the following errors occur, the transaction must be retried: - ``TransientTransactionError``: Raised if a write operation encounters an error - before the driver commits the transaction. + before the driver commits the transaction. To learn more about this error + type, see the :manual:`TransientTransactionError description +` on the Drivers API page in the +Server manual. - ``UnknownTransactionCommitResult``: Raised if the commit operation encounters - an error. + an error. To learn more about this error type, see the + :manual:`UnknownTransactionCommitResult description +` on the Drivers API page in the +Server manual. + +The Convenient Transaction API incorporates retry logic for these error types, +so the driver automatically retries the transaction until there is a successful +commit. + +Core API Error Error Handling +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you are using the Core API to perform a transaction, you must implement the -error-handling logic into your application. To do so, you must create the following functions: +error-handling logic into your application. To do so, you must create the +following functions that run until there is a successful commit or a different +error: - A function that retries the entire transaction when the driver encounters a - ``TransientTransactionError`` + ``TransientTransactionError`` - A function that retries the commit operation when the driver encounters an ``UnknownTransactionCommitResult`` -These functions should continue to retry the operation until there is a -successful commit or a different error. For an example of this retry -logic, see the :manual:`Core API section +For an example of this retry logic, see the :manual:`Core API section ` on the Drivers API page in the -Server manual. - -The Convenient Transaction API incorporates retry logic for these error types, -so the driver automatically retries the transaction until there is a successful -commit. You do not have to explicitly declare functions for the API to retry -transaction operations when the driver produces these errors. \ No newline at end of file +Server manual. \ No newline at end of file From b47779377938a4b620bbbe1fc148b85903021b10 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Fri, 13 Jun 2025 12:41:54 -0400 Subject: [PATCH 05/11] DOCSP-35201 fixing links --- source/crud/transactions.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index 00863ce95..e8fa3b90b 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -311,14 +311,14 @@ transaction must be retried: - ``TransientTransactionError``: Raised if a write operation encounters an error before the driver commits the transaction. To learn more about this error - type, see the :manual:`TransientTransactionError description -` on the Drivers API page in the -Server manual. + type, see the :manual:`TransientTransactionError + description ` on + the Drivers API page in the Server manual. - ``UnknownTransactionCommitResult``: Raised if the commit operation encounters an error. To learn more about this error type, see the - :manual:`UnknownTransactionCommitResult description -` on the Drivers API page in the -Server manual. + :manual:`UnknownTransactionCommitResult + description ` + on the Drivers API page in the Server manual. The Convenient Transaction API incorporates retry logic for these error types, so the driver automatically retries the transaction until there is a successful From d6e04967cdf87d432dd6f271c4e18f8e5e8b4ac1 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Fri, 13 Jun 2025 12:44:50 -0400 Subject: [PATCH 06/11] DOCSP-35201 remove double error in title --- source/crud/transactions.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index e8fa3b90b..62c2853b1 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -324,8 +324,8 @@ The Convenient Transaction API incorporates retry logic for these error types, so the driver automatically retries the transaction until there is a successful commit. -Core API Error Error Handling -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Core API Error Handling +~~~~~~~~~~~~~~~~~~~~~~~ If you are using the Core API to perform a transaction, you must implement the error-handling logic into your application. To do so, you must create the From 7ba44ffd80704c457d50c30a3fc7c044f4ce0ae0 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Fri, 13 Jun 2025 12:53:51 -0400 Subject: [PATCH 07/11] DOCSP-35201 fix sentences --- source/crud/transactions.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index 62c2853b1..20c4bef07 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -329,14 +329,14 @@ Core API Error Handling If you are using the Core API to perform a transaction, you must implement the error-handling logic into your application. To do so, you must create the -following functions that run until there is a successful commit or a different -error: +following functions: - A function that retries the entire transaction when the driver encounters a ``TransientTransactionError`` - A function that retries the commit operation when the driver encounters an ``UnknownTransactionCommitResult`` -For an example of this retry logic, see the :manual:`Core API section +These functions must run until there is a successful commit or a different +error. For an example of this retry logic, see the :manual:`Core API section ` on the Drivers API page in the Server manual. \ No newline at end of file From 99290d22be3c847144cadb2037ee5d23e5f2cbd1 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Mon, 16 Jun 2025 11:01:14 -0400 Subject: [PATCH 08/11] DOCSP-35201 style guide changes/wording --- source/crud/transactions.txt | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index 20c4bef07..b6a7b6f05 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -304,9 +304,9 @@ the ``startTransaction()`` method: Transaction Errors ------------------ -Since MongoDB transactions are :website:`ACID compliant -`, the driver may produce errors during operation to -ensure your data maintains consistent. If the following errors occur, the +Because MongoDB transactions are :website:`ACID compliant +`, the driver might produce errors during operation +to ensure your data maintains consistent. If the following errors occur, the transaction must be retried: - ``TransientTransactionError``: Raised if a write operation encounters an error @@ -320,6 +320,11 @@ transaction must be retried: description ` on the Drivers API page in the Server manual. +The following sections describe how to handle these errors for different APIs. + +Convenient Transaction Error Handling +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The Convenient Transaction API incorporates retry logic for these error types, so the driver automatically retries the transaction until there is a successful commit. @@ -327,9 +332,8 @@ commit. Core API Error Handling ~~~~~~~~~~~~~~~~~~~~~~~ -If you are using the Core API to perform a transaction, you must implement the -error-handling logic into your application. To do so, you must create the -following functions: +If you are using the Core API to perform a transaction, you must add the following +error-handling functions to your application: - A function that retries the entire transaction when the driver encounters a ``TransientTransactionError`` From 99e41ce7a640b606bb60d1e29b5e395d44cc6563 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Mon, 16 Jun 2025 11:14:57 -0400 Subject: [PATCH 09/11] DOCSP-35201 add API to title --- source/crud/transactions.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index b6a7b6f05..6e3fe906f 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -322,8 +322,8 @@ transaction must be retried: The following sections describe how to handle these errors for different APIs. -Convenient Transaction Error Handling -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Convenient Transaction API Error Handling +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Convenient Transaction API incorporates retry logic for these error types, so the driver automatically retries the transaction until there is a successful From 9581c7a5ff50ec0de9802776db26c182ebf5c7d1 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Tue, 17 Jun 2025 11:09:14 -0400 Subject: [PATCH 10/11] Update source/crud/transactions.txt Co-authored-by: Mike Woofter <108414937+mongoKart@users.noreply.github.com> --- source/crud/transactions.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index 6e3fe906f..ec1c0044f 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -306,8 +306,8 @@ Transaction Errors Because MongoDB transactions are :website:`ACID compliant `, the driver might produce errors during operation -to ensure your data maintains consistent. If the following errors occur, the -transaction must be retried: +to ensure your data maintains consistent. If the following errors occur, your +application must retry the transaction: - ``TransientTransactionError``: Raised if a write operation encounters an error before the driver commits the transaction. To learn more about this error From 22fbe2dc2639cdd8d70a340d0ef0c1756b04c0c8 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Tue, 17 Jun 2025 11:09:59 -0400 Subject: [PATCH 11/11] DOCSP-35201 grammar changes --- source/crud/transactions.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index ec1c0044f..5a18b9c0e 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -320,13 +320,13 @@ application must retry the transaction: description ` on the Drivers API page in the Server manual. -The following sections describe how to handle these errors for different APIs. +The following sections describe how to handle these errors when using different APIs. Convenient Transaction API Error Handling ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The Convenient Transaction API incorporates retry logic for these error types, -so the driver automatically retries the transaction until there is a successful +The Convenient Transaction API incorporates retry logic for these error types. +The driver automatically retries the transaction until there is a successful commit. Core API Error Handling