DOCSP-30555: transactions guide (#87)

(cherry picked from commit 0542362)

Author: rustagir

source/fundamentals.txt

@@ -18,6 +18,7 @@ Fundamentals
    /fundamentals/schema-validation
    /fundamentals/aggregation
    /fundamentals/indexes
+   /fundamentals/transactions
    /fundamentals/time-series
    /fundamentals/tracing-logging
    /fundamentals/run-command
@@ -29,7 +30,6 @@ Fundamentals
 
 ..
    Connect to MongoDB Atlas from AWS Lambda <https://www.mongodb.com/docs/atlas/manage-connections-aws-lambda/>
-   /fundamentals/transactions
    /fundamentals/gridfs
    /fundamentals/encrypt-fields
 

source/fundamentals/crud/compound-operations.txt

@@ -48,10 +48,10 @@ This guide includes the following sections:
   provides links to resources and API documentation for types
   and methods mentioned in this guide
 
-.. TODO .. tip::
+.. tip::
 
-..    If you must perform atomic read and writes on more than one
-..    document, use :ref:`transactions <rust-transactions>`.
+   To learn how to perform atomic read and write operations on more than one
+   document at a time, see the :ref:`rust-transactions` guide.
 
 .. _rust-compound-sample-data:
 

source/fundamentals/transactions.txt

@@ -0,0 +1,187 @@
+.. _rust-transactions:
+
+============
+Transactions
+============
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, ACID compliance, multi-document
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to use the {+driver-short+} to perform
+**transactions**. Transactions allow you to perform a series of operations
+that change data only if the entire transaction is committed.
+If any operation in the transaction does not succeed, the driver stops the
+transaction and discards all data changes before they ever become
+visible. This feature is called **atomicity**.
+
+In MongoDB, transactions run within logical sessions. A
+session is a grouping of related read or write operations that you
+want to run sequentially. Sessions enable causal consistency for a group
+of operations and allow you to run operations in an **ACID-compliant**
+transaction, which is a transaction that meets an expectation of
+atomicity, consistency, isolation, and durability. 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 ``ClientSession`` type. You can improve your
+app's performance by reusing your client for multiple sessions and
+transactions instead of instantiating a new client each time.
+
+.. warning::
+
+   Use a ``ClientSession`` only in operations running on the
+   ``Client`` that created it. Using a ``ClientSession`` with a
+   different ``Client`` results in operation errors.
+
+Methods
+-------
+
+Create a ``ClientSession`` by using the ``start_session()`` method on your
+``Client`` instance. You can then modify the session state using the
+methods provided by the ``ClientSession`` type. The following table
+describes these methods:
+
+.. list-table::
+   :widths: 25 75
+   :stub-columns: 1
+   :header-rows: 1
+
+   * - Method
+     - Description
+
+   * - ``start_transaction()``
+     - | Starts a new transaction, configured according to an optional
+         ``TransactionOptions`` parameter, on this session. The session
+         must be passed into each operation within the transaction, or
+         the operation will run outside of the transaction.
+       |
+       | Errors returned from operations run within the transaction
+         might include a ``TRANSIENT_TRANSACTION_ERROR`` label, which
+         indicates that the entire transaction can be ended, then retried
+         with the expectation that it will succeed.
+       |
+       | **Parameter**: ``TransactionOptions``
+
+   * - ``commit_transaction()``
+     - | Commits the active transaction for this session. This method returns an
+         error if there is no active transaction for the session or the
+         transaction was previously ended.
+       |
+       | This method might return an error that includes an
+         ``UNKNOWN_TRANSACTION_COMMIT_RESULT`` label, which 
+         indicates that it is unknown if the committed transaction
+         satisfies the set write concern. If you encounter this error,
+         it is safe to retry the commit until the write concern is
+         satisfied or the method returns an error without the label.
+
+   * - ``abort_transaction()``
+     - | Ends the active transaction for this session. This method returns an
+         error if there is no active transaction for the session or if the
+         transaction was committed or ended.
+
+   * - ``with_transaction()``
+     - | Starts a transaction on this session and runs the given
+         callback, then commits or ends the transaction. When you use
+         this method to perform a transaction, the driver automatically
+         handles any errors, so you can choose to omit error handling code.
+       |
+       | Because the callback returns a future and can be run multiple
+         times, the Rust language closure borrowing rules for captured
+         values can be restrictive. So, the ``with_transaction()``
+         method accepts a context parameter that is passed to the callback.
+       |
+       | **Parameters**: context ``C``, callback ``FnMut(&'a mut
+         ClientSession, &'a mut C)``, ``TransactionOptions``
+
+.. important:: Methods That Can Run in Transactions
+
+   To run MongoDB tasks within transactions, you must use the
+   ``_with_session()`` suffixed methods. These methods accept a
+   ``ClientSession`` instance as a parameter.
+
+   For example, to delete a document, you can generally use the
+   ``delete_one()`` method. However, to delete a document within
+   a transaction, you must use the ``delete_one_with_session()``
+   method and pass the session as a parameter.
+
+Example
+-------
+
+The following code defines the ``insert_media()`` callback function that
+inserts data into the ``books`` and ``films`` collections:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/transaction.rs
+   :language: rust
+   :dedent:
+   :start-after: begin-callback
+   :end-before: end-callback
+
+The following code completes the following actions to perform the
+transaction:
+
+1. Creates a session from the client by using the ``start_session()`` method.
+#. Uses the ``with_transaction()`` method to start a transaction and run
+   the ``insert_media()`` callback function within the transaction.
+
+.. io-code-block::
+
+   .. input:: /includes/fundamentals/code-snippets/transaction.rs
+      :language: rust
+      :dedent:
+      :start-after: begin-session
+      :end-before: end-session
+
+   .. output:: 
+      :language: console
+      :visible: false
+
+      Successfully committed transaction!
+
+If you require more control over your transactions, see the `ClientSession API
+documentation <{+api+}/struct.ClientSession.html#transactions>`__
+to find an example that shows how to manually create and commit a transaction.
+
+Additional Information
+----------------------
+
+To learn more about the concepts mentioned in this guide, see the
+following pages in the Server manual:
+
+- :manual:`Transactions </core/transactions/>`
+- :manual:`Server Sessions </reference/server-sessions/>`
+- :manual:`Read Isolation, Consistency, and Recency </core/read-isolation-consistency-recency/#causal-consistency>`
+
+To learn more about ACID compliance, see the :website:`What are ACID
+Properties in Database Management Systems? </basics/acid-transactions>`
+article on the MongoDB website.
+
+To learn more about insert operations, see the
+:ref:`rust-insert-guide` guide.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about the methods and types mentioned in this
+guide, see the following API documentation:
+
+- `ClientSession <{+api+}/struct.ClientSession.html#>`__
+- `start_session() <{+api+}/struct.Client.html#method.start_session>`__
+- `start_transaction() <{+api+}/struct.ClientSession.html#method.start_transaction>`__
+- `commit_transaction() <{+api+}/struct.ClientSession.html#method.commit_transaction>`__
+- `abort_transaction() <{+api+}/struct.ClientSession.html#method.abort_transaction>`__
+- `with_transaction() <{+api+}/struct.ClientSession.html#method.with_transaction>`__
+- `TransactionOptions <{+api+}/options/struct.TransactionOptions.html>`__

source/includes/fundamentals-sections.rst

@@ -11,6 +11,7 @@ Fundamentals section:
 - :ref:`Implement Schema Validation <rust-schema-validation>`
 - :ref:`Perform Aggregations <rust-aggregation>`
 - :ref:`Create and Manage Indexes <rust-indexes>`
+- :ref:`Perform a Multi-Document Transaction <rust-transactions>`
 - :ref:`Create a Time Series Collection <rust-time-series>`
 - :ref:`Record Driver Events <rust-tracing-logging>`
 - :ref:`Run A Database Command <rust-run-command>`

source/includes/fundamentals/code-snippets/transaction.rs

@@ -0,0 +1,52 @@
+use std::env;
+use bson::{ Document, doc };
+use futures::FutureExt;
+use mongodb::{ Client, ClientSession };
+use mongodb::error::Error;
+
+// begin-callback
+async fn insert_media(session: &mut ClientSession) -> Result<(), Error> {
+    let books_coll = session
+        .client()
+        .database("db")
+        .collection::<Document>("books");
+
+    let films_coll = session
+        .client()
+        .database("db")
+        .collection::<Document>("films");
+
+    books_coll.insert_one_with_session(
+        doc! { 
+            "name": "Sula", 
+            "author": "Toni Morrison"
+        },
+        None,
+        session
+    ).await?;
+
+    films_coll.insert_one_with_session(
+        doc! { "name": "Nostalgia", "year": 1983 },
+        None,
+        session
+    ).await?;
+
+    Ok(())
+}
+// end-callback
+
+#[tokio::main]
+async fn main() -> mongodb::error::Result<()> {
+    let uri = "<connection string>";
+    let client = Client::with_uri_str(uri).await?;
+
+    // begin-session
+    let mut session = client.start_session(None).await?;
+    session
+        .with_transaction((), |session, _| insert_media(session).boxed(), None)
+        .await?;
+    println!("Successfully committed transaction!");
+    // end-session
+
+    Ok(())
+}