Fixed #32220 -- Added durable argument to transaction.atomic().

2 files changed, 22 insertions, 1 deletions

diff --git a/docs/releases/3.2.txt b/docs/releases/3.2.txt
index 222ef6c870..1209b357e2 100644
--- a/docs/releases/3.2.txt
+++ b/docs/releases/3.2.txt
@@ -356,6 +356,11 @@ Models
   allow using transforms. See :ref:`using-transforms-in-expressions` for
   details.
 
+* The new ``durable`` argument for :func:`~django.db.transaction.atomic`
+  guarantees that changes made in the atomic block will be committed if the
+  block exits without errors. A nested atomic block marked as durable will
+  raise a ``RuntimeError``.
+
 Pagination
 ~~~~~~~~~~
 
diff --git a/docs/topics/db/transactions.txt b/docs/topics/db/transactions.txt
index 996dd7534d..bdfb99cdfd 100644
--- a/docs/topics/db/transactions.txt
+++ b/docs/topics/db/transactions.txt
@@ -93,7 +93,7 @@ Controlling transactions explicitly
 
 Django provides a single API to control database transactions.
 
-.. function:: atomic(using=None, savepoint=True)
+.. function:: atomic(using=None, savepoint=True, durable=False)
 
     Atomicity is the defining property of database transactions. ``atomic``
     allows us to create a block of code within which the atomicity on the
@@ -105,6 +105,12 @@ Django provides a single API to control database transactions.
     completes successfully, its effects can still be rolled back if an
     exception is raised in the outer block at a later point.
 
+    It is sometimes useful to ensure an ``atomic`` block is always the
+    outermost ``atomic`` block, ensuring that any database changes are
+    committed when the block is exited without errors. This is known as
+    durability and can be achieved by setting ``durable=True``. If the
+    ``atomic`` block is nested within another it raises a ``RuntimeError``.
+
     ``atomic`` is usable both as a :py:term:`decorator`::
 
         from django.db import transaction
@@ -232,6 +238,16 @@ Django provides a single API to control database transactions.
     is especially important if you're using :func:`atomic` in long-running
     processes, outside of Django's request / response cycle.
 
+.. warning::
+
+    :class:`django.test.TestCase` disables the durability check to allow
+    testing durable atomic blocks in a transaction for performance reasons. Use
+    :class:`django.test.TransactionTestCase` for testing durability.
+
+.. versionchanged:: 3.2
+
+    The ``durable`` argument was added.
+
 Autocommit
 ==========