Install & Compatibility
Where this runs
tested against v0.11 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 66.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.4s · import 0.000s · 67MB
65MB installed
● package 65MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MasterSlaveRouter
✓ from multidb import MasterSlaveRouter
✗ from multidb import MultiDBRouter
PinningMasterSlaveRouter
✓ from multidb import PinningMasterSlaveRouter
ReplicaRouter
✓ from multidb import ReplicaRouter
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
]
Debug
Known issues
breakingIn 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.fixUpdate settings: rename SLAVE_DATABASES to REPLICA_DATABASES and ensure all replica aliases are listed.
affects: >=0.9
deprecatedPython 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.fixUse Python 3.7+ and Django 1.11+.
affects: >=0.9
gotchaIf 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.fixAlways define REPLICA_DATABASES as a list of alias strings, even if only one replica is configured.
affects: <0.9 (and later if missing)
gotchaPinningRouter 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.fixAdd 'multidb.pinning.MultiDBMiddleware' to MIDDLEWARE.
affects: >=2.0
Upgrade
Version history
0.11latest on PyPI · released Jul 4, 2025
Audit
Dependencies
DjangorequiredRequired; works with Django 1.11+ (tested up to 3.2).