In Django, why can two flash-sale checkouts that lock several product rows with select_for_update() deadlock, and how do you prevent and handle it?

## How the deadlock forms A **deadlock** is two transactions each holding a lock the other needs. With `select_for_update()` it typically comes from locking rows one at a time in an order that depends on the input: ```python with transaction.atomic(): for item in basket.items: # basket order product = Product.objects.select_for_update().get(pk=item.product_id) product.stock -= item.qty product.save(update_fields=["stock"]) ``` | Step | Checkout 1 (basket: A, B) | Checkout 2 (basket: B, A) | |---|---|---| | 1 | locks A | locks B | | 2 | waits for B | waits for A | | 3 | — deadlock — | — deadlock — | The database detects the cycle and aborts one of the transactions with an error; the other proceeds. Django wraps the driver error in a `django.db.DatabaseError` subclass — `OperationalError` with PostgreSQL's driver. ## Prevention: a consistent lock order 1. **Lock all rows in one query.** `select_for_update().filter(pk__in=ids)` takes every lock in a single statement instead of a loop. 2. **Order it deterministically.** Add `.order_by("pk")`. Rows are locked as the query reads them, so a fixed sort order means every checkout asks for A before B. 3. **Lock first, compute second.** Take the locks at the top of the block, then validate and update; locks acquired mid-way through other work are where inconsistent orders creep in. 4. **Keep the block short** — fewer, shorter lock holds mean fewer chances to collide. 5. **Lock only what you change.** Use `of=("self",)` when `select_related()` would otherwise also lock shared rows in join order. ```python with transaction.atomic(): products = { p.pk: p for p in Product.objects.select_for_update() .filter(pk__in=[i.product_id for i in basket.items]) .order_by("pk") } for item in basket.items: products[item.product_id].stock -= item.qty Product.objects.bulk_update(products.values(), ["stock"]) ``` ## Handling: retry the whole transaction Ordering removes the common cause, but other code paths — an admin action, a signal, a row updated by a plain `update()` — can still lock the same rows in another order. When the error arrives: - The transaction is **aborted**. Catching the error inside the `atomic` block and continuing fails — the same rule as for `IntegrityError`. - Put the `try` **around** `transaction.atomic()` and re-run the whole function, a small bounded number of times, ideally with a short randomised pause. - Retry only the deadlock or lock-timeout class of errors, not `IntegrityError` or programming errors. - Keep side effects out of the retried block, or register them with `transaction.on_commit()` so a rolled-back attempt emits nothing. ## Things that make it worse in Django projects - **Signals** that lock or update other rows during `save()`, silently extending the lock order. - **`ATOMIC_REQUESTS`**, which turns the whole view into one long transaction. - **Implicit joins**: `select_related()` with the default lock scope also locks joined rows, adding tables to the lock order you have to reason about. - **Loops over user-ordered input**, as in the basket example. ## Diagnosing - Look for the database's deadlock message in logs next to Django's `OperationalError` traceback; it names both statements. - Find every code path that locks the same tables and write down its lock order; the mismatched one is the culprit. - A spike of deadlocks at a sale's start usually points at per-item locking loops rather than at the database. ## Why not just use `nowait`? `nowait=True` does stop a checkout from ever *waiting*, so no wait-for cycle can form — but every contended checkout now fails instead of queueing, which during a sale means a flood of "try again" errors. It is a valid choice for a fail-fast UX, not a substitute for a consistent lock order.