django-multidb-router

0.11 verified Fri May 01 auth: no python maintenance

Round-robin master/replica database router for Django. Version 0.11 provides simple master-write, replica-read routing using a round-robin algorithm. It is in maintenance mode with minimal recent updates.

pip install django-multidb-router

Common errors

error django.core.exceptions.ImproperlyConfigured: 'multidb.pinning' is not a valid router module (or does not provide a Router class) ↓

cause Misconfigured DATABASE_ROUTERS: using 'multidb.pinning.MultiDBRouter' instead of 'multidb.MultiDBRouter'.

fix

Change entry to 'multidb.MultiDBRouter' for round-robin, or 'multidb.pinning.PinningRouter' for pinning behavior.

error KeyError: 'replica1' (or other replica alias) ↓

cause The database alias listed in REPLICA_DATABASES is not defined in the DATABASES dict.

fix

Ensure each alias in REPLICA_DATABASES exists as a key in DATABASES.

error AttributeError: 'NoneType' object has no attribute 'close' (or similar connection errors) ↓

cause The router is used but REPLICA_DATABASES is empty or not defined, causing reads to try to connect to a non-existent replica.

fix

Define REPLICA_DATABASES with at least one valid replica database alias.

Warnings

breaking In v0.9+, the default terminology switched from 'master/slave' to 'primary/replica'. The settings key REPLICA_DATABASES must be used instead of the old SLAVE_DATABASES. The router also expects all replicas to be listed in REPLICA_DATABASES; missing this causes a fallback to master for reads. ↓

fix Update settings: rename SLAVE_DATABASES to REPLICA_DATABASES and ensure all replica aliases are listed.

deprecated Python 3.4 support was dropped in v0.9. Django 1.8 and 1.10 support dropped simultaneously. Python 3.6 and below are no longer tested. ↓

fix Use Python 3.7+ and Django 1.11+.

gotcha If REPLICA_DATABASES is not defined, MultiDBRouter will silently use the 'default' database for all reads, effectively disabling replica routing. No warning is issued in many versions. ↓

fix Always define REPLICA_DATABASES as a list of alias strings, even if only one replica is configured.

gotcha PinningRouter requires the MultiDBMiddleware to be added to MIDDLEWARE (not MIDDLEWARE_CLASSES) for Django 2.0+. Without it, the pinning context manager may not work correctly across requests. ↓

fix Add 'multidb.pinning.MultiDBMiddleware' to MIDDLEWARE.

Imports

MultiDBRouter
wrong
```
from multidb.pinning import MultiDBRouter
```
correct
```
from multidb import MultiDBRouter
```
MultiDBRouter is located in multidb directly, not multidb.pinning.

PinningRouter

wrong

from multidb import PinningRouter

correct

from multidb.pinning import PinningRouter

PinningRouter is in the submodule multidb.pinning.

use_master
```
from multidb.pinning import use_master
```
use_replica
```
from multidb.pinning import use_replica
```

Quickstart

Configure DATABASES with a 'default' (master) and replica(s). Set REPLICA_DATABASES to a list of replica database aliases. Then add the router to DATABASE_ROUTERS.

# settings.py
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'mydb',
        'USER': 'user',
        'PASSWORD': 'pass',
        'HOST': 'primary.example.com',
    },
    'replica1': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'mydb',
        'USER': 'user',
        'PASSWORD': 'pass',
        'HOST': 'replica1.example.com',
    },
    'replica2': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'mydb',
        'USER': 'user',
        'PASSWORD': 'pass',
        'HOST': 'replica2.example.com',
    },
}
REPLICA_DATABASES = ['replica1', 'replica2']  # required list

DATABASE_ROUTERS = ['multidb.MultiDBRouter']

# Optional: pinning for session consistency
MIDDLEWARE = [
    'multidb.pinning.MultiDBMiddleware',
    # ... other middleware
]