From 87e5f8606e48dfb59d8bd6c30aaa68f8cd2d1d86 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Tue, 6 May 2025 12:00:44 -0500 Subject: [PATCH 1/7] first draft --- source/crud/transactions.txt | 75 +++++++++++++++++++++++++++++++++--- 1 file changed, 70 insertions(+), 5 deletions(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index 9e8102a6..53191156 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -27,21 +27,32 @@ 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. +MongoDB guarantees that the data involved in your transaction operations remains +consistent, even if the operations encounter unexpected errors. + +Sessions +-------- + 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 +enable 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. +:website:`ACID transaction `. When using the {+driver-short+}, you can create a new session from a ``MongoClient`` instance as an ``IClientSession`` type. We recommend that you reuse your client for multiple sessions and transactions instead of instantiating a new client each time. +The following example shows how to create a session by calling the ``StartSession()`` +method: + +.. code-block:: + + var client = new MongoClient("mongodb://localhost:27017"); + var session = client.StartSession(); + .. warning:: Use an ``IClientSession`` only with the ``MongoClient`` (or associated @@ -49,6 +60,60 @@ instantiating a new client each time. ``IClientSession`` with a different ``MongoClient`` results in operation errors. +ClientSessionOptions +~~~~~~~~~~~~~~~~~~~~ + +You can customize the behavior of your session by passing an instance of the +``ClientSessionOptions`` class to the ``StartSession()`` method. The following table +describes the properties that you can set on a ``ClientSessionOptions`` object: + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Property + - Description + + * - ``CausalConsistency`` + - Specifies whether the session is causally consistent. In a causally consistent session, + the driver executes operations in the order they were issued. To learn more, see + :ref:``. + | + | **Data Type**: {+bool-data-type+} + | **Default**: ``true`` + + * - ``DefaultTransactionOptions`` + - The default transaction options for the session. This includes the maximum commit + time, read concern, read preference, and write concern. + | + | **Data Type**: `TransactionOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.TransactionOptions.html>`__ + | **Default**: ``null`` + + * - ``Snapshot`` + - Specifies whether the driver performs snapshot reads. To learn more about snapshot + reads, see :manual:`Read Concern "snapshot" ` + in the {+mdb-server+} manual. + | + | **Data Type**: {+bool-data-type+} + | **Default**: ``false`` + +The following code example shows how to create a session with custom options: + +.. code-block:: + + var client = new MongoClient("mongodb://localhost:27017"); + var sessionOptions = new ClientSessionOptions + { + CausalConsistency = true, + DefaultTransactionOptions = new TransactionOptions( + readConcern: ReadConcern.Available, + writeConcern: WriteConcern.Acknowledged) + }; + + var session = client.StartSession(sessionOptions); + +.. _csharp-causal-consistency: + Causal Consistency ~~~~~~~~~~~~~~~~~~ From dff2526eeb97523393708f84f7e45836093a8896 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Tue, 6 May 2025 12:06:39 -0500 Subject: [PATCH 2/7] fixes --- source/crud/transactions.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index 53191156..6ac862bb 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -1,15 +1,15 @@ .. _csharp-transactions: -============ -Transactions -============ +================================ +Batch Operations in Transactions +================================ .. facet:: :name: genre :values: reference .. meta:: - :keywords: code example, multi-document + :keywords: code example, multi-document, atomic, acid .. contents:: On this page :local: From f4ce348f972ffc83b300373803eaef297bc0a283 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Tue, 6 May 2025 13:11:08 -0500 Subject: [PATCH 3/7] nr feedback --- source/crud/transactions.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index 6ac862bb..dcaa3537 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -49,6 +49,7 @@ The following example shows how to create a session by calling the ``StartSessio method: .. code-block:: + :language: csharp var client = new MongoClient("mongodb://localhost:27017"); var session = client.StartSession(); @@ -83,7 +84,7 @@ describes the properties that you can set on a ``ClientSessionOptions`` object: | **Default**: ``true`` * - ``DefaultTransactionOptions`` - - The default transaction options for the session. This includes the maximum commit + - Specifies the default transaction options for the session. This includes the maximum commit time, read concern, read preference, and write concern. | | **Data Type**: `TransactionOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.TransactionOptions.html>`__ @@ -100,6 +101,7 @@ describes the properties that you can set on a ``ClientSessionOptions`` object: The following code example shows how to create a session with custom options: .. code-block:: + :language: csharp var client = new MongoClient("mongodb://localhost:27017"); var sessionOptions = new ClientSessionOptions From c01c8300a70344a0e2ae152fc3187f7ae4b6941d Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Tue, 6 May 2025 13:17:16 -0500 Subject: [PATCH 4/7] fixes --- source/crud/transactions.txt | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index dcaa3537..a825d72d 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -69,31 +69,31 @@ You can customize the behavior of your session by passing an instance of the describes the properties that you can set on a ``ClientSessionOptions`` object: .. list-table:: - :widths: 20 80 + :widths: 40 60 :header-rows: 1 * - Property - Description * - ``CausalConsistency`` - - Specifies whether the session is causally consistent. In a causally consistent session, - the driver executes operations in the order they were issued. To learn more, see - :ref:``. + - | Specifies whether the session is causally consistent. In a causally consistent session, + the driver executes operations in the order they were issued. To learn more, see + :ref:``. | | **Data Type**: {+bool-data-type+} | **Default**: ``true`` * - ``DefaultTransactionOptions`` - - Specifies the default transaction options for the session. This includes the maximum commit - time, read concern, read preference, and write concern. + - | Specifies the default transaction options for the session. This includes the maximum commit + time, read concern, read preference, and write concern. | | **Data Type**: `TransactionOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.TransactionOptions.html>`__ | **Default**: ``null`` * - ``Snapshot`` - - Specifies whether the driver performs snapshot reads. To learn more about snapshot - reads, see :manual:`Read Concern "snapshot" ` - in the {+mdb-server+} manual. + - | Specifies whether the driver performs snapshot reads. To learn more about snapshot + reads, see :manual:`Read Concern "snapshot" ` + in the {+mdb-server+} manual. | | **Data Type**: {+bool-data-type+} | **Default**: ``false`` From 5ae79e4d87bca1867f5d54f10966170b1092669b Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Tue, 6 May 2025 13:20:51 -0500 Subject: [PATCH 5/7] fixes --- source/crud/transactions.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index a825d72d..fc448bf5 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -48,8 +48,8 @@ instantiating a new client each time. The following example shows how to create a session by calling the ``StartSession()`` method: -.. code-block:: - :language: csharp +.. code-block:: csharp + :copyable: true var client = new MongoClient("mongodb://localhost:27017"); var session = client.StartSession(); @@ -100,8 +100,8 @@ describes the properties that you can set on a ``ClientSessionOptions`` object: The following code example shows how to create a session with custom options: -.. code-block:: - :language: csharp +.. code-block:: csharp + :copyable: true var client = new MongoClient("mongodb://localhost:27017"); var sessionOptions = new ClientSessionOptions From 4dbeac53d1e2df3d02d784152ad0ed8ae6835a65 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Tue, 6 May 2025 13:28:31 -0500 Subject: [PATCH 6/7] column width --- source/crud/transactions.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index fc448bf5..1a6ad435 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -69,7 +69,7 @@ You can customize the behavior of your session by passing an instance of the describes the properties that you can set on a ``ClientSessionOptions`` object: .. list-table:: - :widths: 40 60 + :widths: 35 65 :header-rows: 1 * - Property From b41afb77dbd6319923b9c4c07850f29bd6de2e38 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Tue, 6 May 2025 13:43:56 -0500 Subject: [PATCH 7/7] column width --- source/crud/transactions.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index 1a6ad435..f9049a47 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -161,7 +161,7 @@ tabs to learn about the methods to manage your transaction: :tabid: synchronous-methods .. list-table:: - :widths: 40 60 + :widths: 30 70 :header-rows: 1 * - Method