A Django marketplace adds a router sending every read to a 'replica' alias for analytics; checkout now raises DoesNotExist reading back an order created inside transaction.atomic() - why, and how do you fix it?

## What the router actually does A Django **database router** is consulted per query, not per request or per transaction. With this router installed: ```python class ReplicaRouter: def db_for_read(self, model, **hints): return 'replica' def db_for_write(self, model, **hints): return 'default' ``` checkout code such as this fails: ```python with transaction.atomic(): order = Order.objects.create(buyer=buyer, total=total) order = Order.objects.select_related('buyer').get(pk=order.pk) # DoesNotExist ``` 1. `Order.objects.create()` is a write, so `db_for_write` sends the `INSERT` to `'default'`. 2. `transaction.atomic()` with no `using` argument opened its transaction on the `'default'` connection only. Atomic blocks are per alias; nothing is opened on `'replica'`. 3. `Order.objects.get()` is a read, so `db_for_read` sends the `SELECT` to `'replica'`, a separate connection to a separate server. 4. The `INSERT` is not committed yet, so no other connection can see it, and the replica has not received it anyway. The `get()` raises `Order.DoesNotExist`. The router has no idea a transaction is open; Django's documentation says as much about the sample primary/replica router, which ignores both **replication lag** and transactions. After the block commits the same code can still fail for a moment, because the replica applies the change after the primary does. That second failure is lag; the first one would happen with zero lag. ## Confirming the diagnosis Before changing the router, prove where each statement went: 1. Turn on the `django.db.backends` logger at `DEBUG` (it logs only when `DEBUG` is true or a debug cursor is forced). Each SQL line ends with `alias=...`, so the `INSERT` shows `alias=default` and the failing `SELECT` shows `alias=replica`. 2. In a shell, check `Order.objects.all().db`: it returns the alias the router picks for a read without sending any SQL. 3. Repeat the failing code with `Order.objects.using('default').get(...)`. If it now succeeds inside the block, the cause is routing, not the write. ## Fix 1: route only what should go to the replica The real requirement was 'analytics reads on the replica', not 'every read on the replica'. Make the router answer only for the models that tolerate stale data and return `None` for everything else, so checkout, accounts and the admin keep reading from `'default'`. ## Fix 2: keep reads on the primary inside a transaction Each alias's connection wrapper exposes `in_atomic_block`, and `django.db.connections` gives each thread its own wrappers, so a router can check whether the current code is inside `atomic()` on the primary and send reads there. Be aware of the cost: - With `ATOMIC_REQUESTS` enabled on `'default'`, every view runs inside a transaction, so this rule sends every read in a view to the primary and the replica only serves management commands and background jobs. - `select_for_update()`, `get_or_create()` and `update_or_create()` already route through `db_for_write`, so they are not the problem. ## Fix 3: honour the instance hint and use() the primary on purpose - When code follows a relation from an object loaded on `'default'`, Django passes that object as `hints['instance']`. Returning `instance._state.db` keeps related reads on the same database, which is what Django does with no router at all. - For a single read that must be fresh, such as the order confirmation page right after checkout, bind it explicitly: `Order.objects.using('default').get(pk=pk)`. A manual alias always outranks the router. ## Comparing the fixes | Fix | Cures uncommitted read in atomic() | Cures lag after commit | Replica load kept | |---|---|---|---| | Scope `db_for_read` to analytics models | yes, for checkout models | yes, for checkout models | analytics only, as intended | | `in_atomic_block` check | yes | no | reads outside transactions | | `instance` hint | related reads only | related reads only | most reads | | `using('default')` at the call site | yes | yes | everything else | Keeping a user on the primary for a while after their own write, across requests, is a pinning policy; the routing layer is where a Django project would read a request-scoped flag for it, but the policy itself is a design choice beyond this router. ## Checklist for replica routers - Return an alias only for models you have decided may be stale. - Never route writes or locking reads to a replica. - Return `False` from `allow_migrate` for the replica alias. - Allow relations between objects from `'default'` and `'replica'` in `allow_relation`, since they hold the same data. - Test with a real replica or a delay, because a replica configured as a test mirror of `'default'` hides lag entirely.