What does Django's ATOMIC_REQUESTS database setting wrap in a transaction, what stays outside it, and when do you opt a view out?

## What the setting is `ATOMIC_REQUESTS` lives inside each database entry in `DATABASES`, next to `ENGINE` and `NAME`: ```python DATABASES = { "default": { "ENGINE": "django.db.backends.postgresql", "NAME": "wallets", "ATOMIC_REQUESTS": True, } } ``` Its default is `False`. It is per alias: a project with `default` and `ledger` can enable it on one and not the other, and with both enabled the view is wrapped once per alias — two separate transactions, not one shared commit. ## What it wraps When the handler has resolved a URL to a view, it wraps the view callable in `transaction.atomic(using=alias)` for each alias with the setting on. From there the ordinary `atomic` rules apply: - the view **returns** a response → commit; - the view **raises** → rollback, and the exception continues to the exception middleware and the error handlers; - an `atomic` block inside the view becomes a **savepoint**, because the request transaction is already open; - a `durable=True` block inside the view raises `RuntimeError`, since it is nested. ## What it leaves outside | Part of the request | Inside the transaction? | |---|---| | Middleware, including `process_view` hooks | No | | The view function or class-based view `dispatch()` | Yes | | Rendering a `TemplateResponse` after the view returns | No | | Generating a `StreamingHttpResponse` body | No | | Signal receivers triggered by the view's saves | Yes | The docs warn against writing to the database while generating a streaming response, since the transaction is gone and errors cannot be reported cleanly. ## The traps 1. **A handled error commits.** A view that catches `ValidationError` or a service exception and returns a 400 page has not raised, so every write it made before the error is committed. Either raise, or roll back deliberately. 2. **Swallowed database errors** inside the view break the request transaction exactly like any other `atomic` block; the fix is an inner block around the risky write. 3. **Long transactions.** The transaction and its locks are held for the whole view — including any HTTP call to a payment provider. The docs warn that the overhead grows with traffic. 4. **Async views.** If a coroutine view would be wrapped, Django raises `RuntimeError("You cannot use ATOMIC_REQUESTS with async views.")`; async code must manage its own blocks. ## Opting out ```python from django.db import transaction @transaction.non_atomic_requests def wallet_export(request): ... @transaction.non_atomic_requests(using="ledger") def ledger_report(request): ... ``` `non_atomic_requests` marks the view function so the handler skips wrapping it. It only works on the view itself — decorating a helper the view calls has no effect. ## When teams choose it - **For**: small CRUD apps where "the request is the unit of work" is true and nobody has to remember `atomic`. - **Against**: services with external calls, long reports or streaming, and code that wants its boundaries visible next to the business logic — there, explicit `atomic` blocks in service functions are clearer. ## Rolling back without raising A view that must answer with a normal page yet discard its writes can call `transaction.set_rollback(True)` before returning: the wrapping block then rolls back on exit instead of committing. It is a precise tool for the handled-error trap above, but raising a proper exception and mapping it to a response in one place is usually clearer than scattering rollback flags across views. ## Checking a project quickly - Search `DATABASES` for `ATOMIC_REQUESTS` on each alias. - Search views for `non_atomic_requests` to find the deliberate exceptions. - For every view that calls an external service, ask whether that call should really sit inside the request transaction.