diff options
Diffstat (limited to 'docs/topics')
| -rw-r--r-- | docs/topics/db/transactions.txt | 18 |
1 files changed, 17 insertions, 1 deletions
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 ========== |