work in progress

Author: norareidy

source/includes/interact-data/transactions.py

@@ -0,0 +1,22 @@
+from django.db import transaction
+from sample_mflix.models import Movie
+
+# start-transaction-decorator
+@transaction.atomic
+def run_movie_transaction():
+    Movie.objects.create(
+        title="Poor Things",
+        runtime=141,
+        genres=["Comedy", "Romance"]
+    )
+# end-transaction-decorator
+
+# start-transaction-manager
+def run_movie_transaction():
+    with transaction.atomic():
+        Movie.objects.create(
+            title="Poor Things",
+            runtime=141,
+            genres=["Comedy", "Romance"]
+        )
+# end-transaction-manager

source/interact-data/transactions.txt

@@ -20,9 +20,97 @@ Transactions and Sessions
 Overview
 --------
 
-In this guide, you can learn how to use the {+django-odm+} to perform
-**transactions**. Transactions allow you to perform a series of operations
+In this guide, you can learn how to use {+django-odm+} to perform
+**transactions**. Transactions allow you to run a series of operations
 that change data only if the entire transaction is committed.
-If any operation in the transaction does not succeed, the library stops the
+If any operation in the transaction does not succeed, {+django-odm+} stops the
 transaction and discards all data changes before they ever become
-visible. This feature is called **atomicity**.
+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. 
+
+You can use {+framework+}'s transaction API to perform database transactions.
+To run operations within a transaction, define them inside an atomic block of
+code. {+framework+} manages session logic internally, so you do not need to
+manually start a session before running a transaction.
+
+.. important:: Transaction Limitations
+
+   {+django-odm+}'s support for the {+framework+} transaction API
+   has several limitations. To view a list of limitations, see
+   :ref:`Database and Collection Support <django-feature-compat-db-coll>`
+   in the Django and MongoDB Feature Compatibility guide.
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide use the ``Movie`` model, which represents
+the ``sample_mflix.movies`` collection from the :atlas:`Atlas sample datasets </sample-data>`.
+The ``Movie`` model class has the following definition:
+
+.. literalinclude:: /includes/interact-data/crud.py
+   :start-after: start-models
+   :end-before: end-models
+   :language: python
+   :copyable:
+
+.. include:: /includes/use-sample-data.rst
+
+   .. replacement:: model-classes
+
+      ``Movie`` model includes
+
+   .. replacement:: model-imports
+
+      .. code-block:: python
+
+         from <your application name>.models import Movie
+         from django.utils import timezone
+         from datetime import datetime
+
+Start a Transaction
+-------------------
+
+To start a database transaction, define an atomic block of code
+by adding the ``@transaction.atomic`` decorator above your function.
+This decorator guarantees the atomicity of any database operations
+within the function. If the function successfully completes, the 
+changes are committed MongoDB.
+
+The following example calls the ``create()`` method within a transaction,
+inserting a document into the ``sample_mflix.movies`` collection:
+
+.. literalinclude:: /includes/interact-data/transactions.py
+   :start-after: start-transaction-decorator
+   :end-before: end-transaction-decorator
+   :language: python
+   :copyable:
+
+Alternatively, you can use the ``transaction.atomic()`` context manager
+to create an atomic block. This example runs the same operation as the
+previous example but uses a context manager to start a transaction:
+
+.. literalinclude:: /includes/interact-data/transactions.py
+   :start-after: start-transaction-manager
+   :end-before: end-transaction-manager
+   :language: python
+   :copyable:
+
+Handle Transaction Errors
+-------------------------
+
+To handle exceptions that occur during a transaction, add error handling
+logic around your atomic code block. If you include error handing logic inside
+the atomic block, {+framework+} might ignore these errors, resulting in unexpected
+behavior.
+
+Additional Information
+----------------------
+
+To learn more about the {+framework+} transaction API, see `Database Transactions
+<{+django-docs+}/topics/db/transactions>`__ in the {+framework+} documentation.

source/limitations-upcoming.txt

@@ -183,6 +183,8 @@ Query Support
        the :ref:`raw_aggregate() method <django-raw-queries-search>`.
      - ✓
 
+.. _django-feature-compat-db-coll:
+
 Database and Collection Support
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -248,7 +250,15 @@ Database and Collection Support
      - ✓
 
    * - Transactions
-     - *Unsupported*.
+     - *Partially Supported*. You can use {+framework+}'s transactions API with the
+       following limitations:
+
+       - ``QuerySet.union()`` is not supported within a transaction.
+       - If a transaction generates an error, the transaction is no longer usable.
+       - Nested atomic blocks are not supported. The outermost atomic block starts
+         a transaction, and any subsequent atomic blocks have no effect.
+       - Migration operations do not run inside a transaction, which differs from {+framework+}'s
+         default migration behavior.
      - ✓
 
 Django Features