Commit Hooks

## The problem: side effects you cannot undo Inside a `transaction.atomic()` block, Django's `save()` and `create()` send their SQL to the database straight away, but the changes are only **committed** when the outermost block exits normally. Anything later in the block — creating order lines, charging a wallet, a validation error — can still raise, and then the whole transaction is rolled back. Database work rolls back. An email does not. If `place_order()` sends the receipt right after `Order.objects.create()` and the next line fails, the customer holds a receipt for an order that never existed. The same applies to enqueueing a background task, invalidating a cache entry or calling a webhook. ## What `on_commit` does `django.db.transaction.on_commit(func, using=None, robust=False)` registers a callable against the current transaction on one database alias: | Situation when you call it | What happens to `func` | |---|---| | Inside an `atomic` block (or an `ATOMIC_REQUESTS` view) | Stored; called after the outermost block commits | | The transaction is rolled back | Discarded, never called | | Outside any block, autocommit on (Django's default) | Called immediately | | Autocommit turned off and no `atomic` block | `TransactionManagementError` | Callbacks run in the order they were registered. They are called **after** the commit and after autocommit is restored on the connection, so a query inside a callback runs in ordinary autocommit mode rather than reopening the finished transaction. ## Writing the callback The callable is invoked with **no arguments**. Bind what it needs with `functools.partial`: ```python from functools import partial from django.core.mail import send_mail from django.db import transaction def send_receipt(order_id): order = Order.objects.get(pk=order_id) send_mail("Your receipt", render_receipt(order), None, [order.email]) def place_order(cart, email): with transaction.atomic(): order = Order.objects.create(email=email, total=cart.total) add_lines(order, cart) transaction.on_commit(partial(send_receipt, order.pk)) return order ``` Passing the primary key rather than the instance keeps the callback honest: it reads the committed row. A `lambda` works too, but in a loop it captures the loop *variable*, not its value, so every callback sees the last item — `partial` binds the value at registration time. ## What it does not promise - **Not part of the transaction.** The callback runs after the commit; if the mail server is down, the order is still committed. Django's docs point to two-phase commit if a failure must undo the transaction, and a persisted outbox is the usual alternative. - **Not background work.** The callback runs synchronously in the same thread, at the moment the outer block exits. A slow SMTP call delays the code after the block — in a view, the response. - **Not durable.** If the process dies between the commit and the callback, the callback is lost. - **Per alias.** A callback registered for `using="default"` is tied to that connection's transaction only. ## Interview checklist - Say *when* it runs (after the outermost commit) and *when it doesn't* (rollback). - Mention immediate execution outside a block — a common surprise in scripts and tests. - Use `partial` and pass identifiers, not instances. - Name the limits: synchronous, after-commit, can be lost. ## Where it fits among the alternatives | Place to send the receipt | Emailed for a rolled-back order? | Email can be lost after commit? | |---|---|---| | Right after `save()` inside the block | Yes | No | | After the `with` block, in plain code | Yes, if a caller's outer block later rolls back | Yes | | `transaction.on_commit(...)` inside the block | No | Yes | Placing the call after the `with` block looks equivalent, but it breaks as soon as a caller wraps `place_order()` in its own `atomic` block or the view runs under `ATOMIC_REQUESTS`: "after the inner block" is then still inside the transaction. `on_commit` always waits for the *outermost* commit, which is why it is the idiom rather than code placement.