From 8e8c72e9fe10e17e256629ac8d777403153cf7ea Mon Sep 17 00:00:00 2001 From: Dmitry Rybakov Date: Mon, 20 Nov 2023 14:25:54 +0100 Subject: [PATCH 1/4] RUBY-3341 Document error handling in transactions --- docs/reference/transactions.txt | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/reference/transactions.txt b/docs/reference/transactions.txt index a4e8571320..95e5ca4352 100644 --- a/docs/reference/transactions.txt +++ b/docs/reference/transactions.txt @@ -76,6 +76,27 @@ which are read concern, write concern and read preference: collection.insert_one({hello: 'world'}, session: session) end +Handling Errors Within the ``with_transaction`` Block +----------------------------------------------------- + +If a command inside the ``with_transaction`` block fails, it may cause +the transaction on the server to be aborted. This situation is normally handled +transparently by the driver. However, if the application catches such an error +and does not re-raise it, the driver will not be able to determine whether +the transaction was aborted or not. The driver will then retry the block +indefinitely. + +To avoid this situation, the application should re-raise errors that do not +have ``TransientTransactionError`` in their error labels. For example: + +.. code-block:: ruby + + session.with_transaction do + collection.insert_one({hello: 'world'}, session: session) + rescue Mongo::Error::OperationFailure => e + # Do something in response to the error + raise unless e.label?('TransientTransactionError') + end Low Level API ============= @@ -145,6 +166,14 @@ session if one is in progress: # ok c2.database.drop +Handling Errors +--------------- + +If a command inside the transaction fails with, the transaction may be aborted +on the server. Errors that abort transactions do not have +``TransientTransactionError`` in their error labels. An attempt to commit such +transaction will be rejected with ``NoSuchTransaction`` error. + Retrying Commits ================ From 2af0e37e67763b9871ebbdfb284062b5efce8478 Mon Sep 17 00:00:00 2001 From: Dmitry Rybakov Date: Mon, 20 Nov 2023 15:38:50 +0100 Subject: [PATCH 2/4] Update docs/reference/transactions.txt Co-authored-by: Alex Bevilacqua --- docs/reference/transactions.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/transactions.txt b/docs/reference/transactions.txt index 95e5ca4352..8f02b237d0 100644 --- a/docs/reference/transactions.txt +++ b/docs/reference/transactions.txt @@ -171,7 +171,7 @@ Handling Errors If a command inside the transaction fails with, the transaction may be aborted on the server. Errors that abort transactions do not have -``TransientTransactionError`` in their error labels. An attempt to commit such +``TransientTransactionError`` in their error labels. An attempt to commit such a transaction will be rejected with ``NoSuchTransaction`` error. From 374ba637808cfd2e01b297be533b8b12a59c390c Mon Sep 17 00:00:00 2001 From: Dmitry Rybakov Date: Mon, 20 Nov 2023 15:40:04 +0100 Subject: [PATCH 3/4] Fix code review remarks --- docs/reference/transactions.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/transactions.txt b/docs/reference/transactions.txt index 8f02b237d0..5967014476 100644 --- a/docs/reference/transactions.txt +++ b/docs/reference/transactions.txt @@ -169,7 +169,7 @@ session if one is in progress: Handling Errors --------------- -If a command inside the transaction fails with, the transaction may be aborted +If a command inside the transaction fails, the transaction may be aborted on the server. Errors that abort transactions do not have ``TransientTransactionError`` in their error labels. An attempt to commit such a transaction will be rejected with ``NoSuchTransaction`` error. From 50f21b26ccb0c3325416ca74da4a60277a3cccf5 Mon Sep 17 00:00:00 2001 From: Dmitry Rybakov Date: Tue, 5 Dec 2023 16:58:00 +0100 Subject: [PATCH 4/4] Add clarification about errors --- docs/reference/transactions.txt | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/reference/transactions.txt b/docs/reference/transactions.txt index 5967014476..722038ca8f 100644 --- a/docs/reference/transactions.txt +++ b/docs/reference/transactions.txt @@ -86,8 +86,9 @@ and does not re-raise it, the driver will not be able to determine whether the transaction was aborted or not. The driver will then retry the block indefinitely. -To avoid this situation, the application should re-raise errors that do not -have ``TransientTransactionError`` in their error labels. For example: +To avoid this situation, the application must not silently handle errors within +``with_transaction`` block. If the application needs to handle errors within +the block, it must re-raise the errors. .. code-block:: ruby @@ -95,9 +96,12 @@ have ``TransientTransactionError`` in their error labels. For example: collection.insert_one({hello: 'world'}, session: session) rescue Mongo::Error::OperationFailure => e # Do something in response to the error - raise unless e.label?('TransientTransactionError') + raise e end +If the applications needs to handle errors in a custom way, it should use +the low level API instead. + Low Level API =============