In Django, what do a database router's db_for_read, db_for_write, allow_relation and allow_migrate methods decide, and what does returning None mean?

## What a router is A **database router** is a plain Python class; it does not subclass anything. Django instantiates each entry of the `DATABASE_ROUTERS` setting (a list of dotted paths, empty by default) and wraps them in the base router, `django.db.router`. Whenever the ORM needs a decision, it asks the base router, which asks your routers **in list order**. A router may implement any subset of four methods. A missing method is treated exactly like an answer of `None`: that router is skipped for that decision. ## The four methods | Method | Called when | Returns | If every router passes | |---|---|---|---| | `db_for_read(model, **hints)` | a QuerySet read runs without `using()` | an alias or `None` | hint instance's `_state.db`, else `'default'` | | `db_for_write(model, **hints)` | a save, delete, create, `update()`, `get_or_create()` or `select_for_update()` runs without `using()` | an alias or `None` | hint instance's `_state.db`, else `'default'` | | `allow_relation(obj1, obj2, **hints)` | a related object is assigned or added | `True`, `False` or `None` | allowed only if both objects share `_state.db` | | `allow_migrate(db, app_label, model_name=None, **hints)` | `migrate` considers an operation on alias `db` | `True`, `False` or `None` | allowed | For `db_for_read` and `db_for_write`, the **first truthy alias wins**. For `allow_relation` and `allow_migrate`, the **first non-`None` answer wins**, so an explicit `False` stops the chain. ## Hints The `hints` dictionary carries extra context. For reads and writes the only hint Django currently supplies is **`instance`**: the object being saved, or the object whose related manager is running the query. Its `instance._state.db` records the database it was loaded from. A router that wants Django's default behaviour of fetching related objects from the same database should check that attribute before returning a fixed alias. For `allow_migrate`, when `model_name` is set the hints usually include `'model'`, which may be a **historical model** from the migration state: only its `_meta` is reliable, not your custom methods or managers. ## What allow_relation protects Django does not support foreign keys or many-to-many relations spanning two databases, because the database cannot enforce the key. `allow_relation` is the guard at assignment time: `book.author = author` calls it, and if the answer is `False` the descriptor raises `ValueError` with *the current database router prevents this relation*. A primary/replica pool is the usual reason to override the default, since an object read from `'replica'` and one from `'default'` hold the same data: ```python def allow_relation(self, obj1, obj2, **hints): pool = {'default', 'replica'} if obj1._state.db in pool and obj2._state.db in pool: return True return None ``` ## How one read is resolved Take `Listing.objects.filter(active=True)` evaluated in a view, with two routers installed and no `using()`: 1. The QuerySet is not marked for writing, so Django calls `router.db_for_read(Listing, **hints)`. 2. The base router asks the first router. It has no `db_for_read` method, so it is skipped. 3. The second router returns `None` because `Listing` is not one of its models. 4. No router answered and there is no `instance` hint, so the base router returns `'default'`. If the same QuerySet had come from a related manager, such as `seller.listings.all()`, the seller would be the `instance` hint and step 4 would return the seller's `_state.db` instead. The resolution happens when the query runs, not when the QuerySet is built. Because routers are plain classes, they are easy to unit-test without a database: instantiate the router and call `db_for_read(Listing)` or `allow_migrate('replica', 'shop', model_name='listing')` directly, asserting on the returned alias or verdict. ## Why order matters - Put **narrow** routers first (one app to its own database) and **catch-all** routers last. A catch-all whose `allow_migrate` returns `True` for everything, listed first, makes every model migrate onto every alias. - Return `None`, not `'default'`, for models a router does not own, or the routers after it never get a say. - `DATABASE_ROUTERS` is read once, so routers should be stateless or read request-scoped state themselves. ## Common mistakes 1. Returning `False` from `allow_migrate` or `allow_relation` to mean 'not my model': there it is a verdict that ends the chain, and only `None` passes to the next router. 2. Ignoring the `instance` hint, so related lookups on an object loaded from one database go to another. 3. Forgetting that a manual `using()` bypasses the router entirely, then debugging the router for a query it never saw.