In Django, what does transaction.atomic(durable=True) guarantee, and why does it raise RuntimeError when it is nested inside another block?

## The problem durable solves `transaction.atomic` composes by nesting: called inside another block it creates a **savepoint**, and only the outermost block commits. That is convenient, but it means a function cannot know, from its own code, whether its successful exit actually committed anything. A caller — or `ATOMIC_REQUESTS`, which wraps the whole view — may still roll everything back later. For most code that is fine. It is not fine when the next line assumes the data is durable: capturing a payment on a wallet and then telling an external provider "done", issuing a receipt, or recording a ledger entry that a second process will read immediately. ## What `durable=True` does `atomic(durable=True)` adds one check on entry: - if no `atomic` block is active on that database alias, it behaves like an ordinary outermost block — open, then commit or roll back on exit; - if **any** other block is already active — the only exception being the per-test block that `django.test.TestCase` opens — it raises `RuntimeError` with the message "A durable atomic block cannot be nested within another atomic block." The guarantee is therefore: *if this block exits without an exception, its changes are committed*. The error turns a silent semantic change (becoming a savepoint) into a loud failure at the call site. ```python from django.db import transaction @transaction.atomic(durable=True) def capture_payment(wallet_id, amount): ... # debit the wallet and write the ledger row @transaction.atomic def checkout(order): capture_payment(order.wallet_id, order.total) # RuntimeError: nested ``` ## Interaction with other features | Situation | Result | |---|---| | Called with no active block | Normal outermost transaction | | Called inside another `atomic` block | `RuntimeError` | | Called from a view under `ATOMIC_REQUESTS` | `RuntimeError`, because the view is already wrapped | | Called directly inside a `django.test.TestCase` test | Allowed: the per-test block is exempt | | Nested in another block inside a `TestCase` test | `RuntimeError`, same as production | The `TestCase` exemption matters because every `TestCase` test already runs inside an `atomic` block; without it, no test could call a durable function. Since Django 4.1 the nested case raises inside `TestCase` too, so tests catch the same mistake production would. ## The opposite lever: `set_rollback()` `transaction.set_rollback(True)` marks the innermost enclosing savepoint-backed block (or the whole transaction) for rollback **without raising an exception**. Typical uses: 1. a "dry run" option on a management command that performs every write, reports the result, then discards it; 2. a view that must return a normal response yet undo its writes. `set_rollback(False)` clears the flag and is only safe after you have rolled back to a known-good savepoint yourself. Both `get_rollback()` and `set_rollback()` raise `TransactionManagementError` outside an atomic block. ## When to reach for durable - Use it on a small number of functions whose callers must never wrap them. - Do not sprinkle it everywhere: it removes composability, and a project running `ATOMIC_REQUESTS` cannot call durable functions from its views at all. - Pair it with commit hooks when the follow-up side effect should run only after the commit. ## How to answer in an interview A good answer states the contract in one sentence — "if it exits without error, it is committed" — then explains why a normal block cannot promise that (nesting turns it into a savepoint), names the exception (`RuntimeError`) and the test-time exemption, and closes with a trade-off: durability is bought by giving up composability, so it belongs on a handful of boundary functions, not on every service.