docs

Author: timgraham

django_mongodb_backend/features.py

@@ -97,7 +97,8 @@ class DatabaseFeatures(BaseDatabaseFeatures):
         "expressions.tests.ExpressionOperatorTests.test_lefthand_transformed_field_bitwise_or",
     }
     _django_test_expected_failures_transactions = {
-        # When get_or_create() fails with IntegrityError, the transaction is no longer usable.
+        # When update_or_create() fails with IntegrityError, the transaction
+        # is no longer usable.
         "get_or_create.tests.UpdateOrCreateTests.test_manual_primary_key_test",
         "get_or_create.tests.UpdateOrCreateTestsWithManualPKs.test_create_with_duplicate_primary_key",
     }

docs/source/conf.py

@@ -45,6 +45,7 @@
     "pymongo": ("https://pymongo.readthedocs.io/en/stable/", None),
     "python": ("https://docs.python.org/3/", None),
     "atlas": ("https://www.mongodb.com/docs/atlas/", None),
+    "manual": ("https://www.mongodb.com/docs/manual/", None),
 }
 
 root_doc = "contents"

docs/source/ref/database.rst

@@ -41,3 +41,45 @@ effect. Rather, if you need to close the connection pool, use
 .. versionadded:: 5.2.0b0
 
     Support for connection pooling and ``connection.close_pool()`` were added.
+
+.. _transactions:
+
+Transactions
+============
+
+.. versionadded:: 5.2.0b2
+
+Support for :doc:`Django's transactions APIs <django:topics/db/transactions>`
+is enabled if the MongoDB configuration supports them: MongoDB must be
+configured as a :doc:`replica set <manual:replication>` or :doc:`sharded
+cluster <manual:sharding>`, and the store engine must be :doc:`WiredTiger
+<manual:core/wiredtiger>`.
+
+If transactions aren't supported, query execution uses Django and MongoDB's
+default behavior of autocommit mode. Each query is immediately committed to the
+database. Django's transaction management APIs, such as
+:func:`~django.db.transaction.atomic`, function as no-ops.
+
+.. _transactions-limitations:
+
+Limitations
+-----------
+
+MongoDB's transaction limitations that are applicable to Django are:
+
+- :meth:`QuerySet.union() <django.db.models.query.QuerySet.union>` is not
+  supported inside a transaction.
+- If a transaction raises an exception, the transaction is no longer usable.
+  For example, if the update stage of :meth:`QuerySet.update_or_create()
+  <django.db.models.query.QuerySet.update_or_create>` fails with
+  :class:`~django.db.IntegrityError` due to a unique constraint violation, the
+  create stage won't be able to proceed.
+  :class:`pymongo.errors.OperationFailure` is raised, wrapped by
+  :class:`django.db.DatabaseError`.
+- Savepoints (i.e. nested :func:`~django.db.transaction.atomic` blocks) aren't
+  supported. The outermost :func:`~django.db.transaction.atomic` will start
+  a transaction while any subsequent :func:`~django.db.transaction.atomic`
+  blocks will have no effect.
+- Migration operations aren't :ref:`wrapped in a transaction
+  <topics/migrations:transactions>` because of MongoDB restrictions such as
+  adding indexes to existing collections while in a transaction.

docs/source/releases/5.2.x.rst

@@ -11,6 +11,7 @@ New features
 ------------
 
 - Added subquery support for :class:`~.fields.EmbeddedModelArrayField`.
+- Added support for :ref:`database transactions <transactions>`.
 
 5.2.0 beta 1
 ============

docs/source/topics/known-issues.rst

@@ -80,11 +80,7 @@ Database functions
 Transaction management
 ======================
 
-Query execution uses Django and MongoDB's default behavior of autocommit mode.
-Each query is immediately committed to the database.
-
-Django's :doc:`transaction management APIs <django:topics/db/transactions>`
-are not supported.
+See :ref:`transactions` for details.
 
 Database introspection
 ======================