{"id":23582,"library":"django-multidb-router","title":"django-multidb-router","description":"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.","status":"maintenance","version":"0.11","language":"python","source_language":"en","source_url":"https://github.com/jbalogh/django-multidb-router","tags":["django","database-routing","multi-database","replication","round-robin"],"install":[{"cmd":"pip install django-multidb-router","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Required; works with Django 1.11+ (tested up to 3.2).","package":"Django","optional":false}],"imports":[{"note":"MultiDBRouter is located in multidb directly, not multidb.pinning.","wrong":"from multidb.pinning import MultiDBRouter","symbol":"MultiDBRouter","correct":"from multidb import MultiDBRouter"},{"note":"PinningRouter is in the submodule multidb.pinning.","wrong":"from multidb import PinningRouter","symbol":"PinningRouter","correct":"from multidb.pinning import PinningRouter"},{"note":"","wrong":"","symbol":"use_master","correct":"from multidb.pinning import use_master"},{"note":"","wrong":"","symbol":"use_replica","correct":"from multidb.pinning import use_replica"}],"quickstart":{"code":"# settings.py\nDATABASES = {\n    'default': {\n        'ENGINE': 'django.db.backends.postgresql',\n        'NAME': 'mydb',\n        'USER': 'user',\n        'PASSWORD': 'pass',\n        'HOST': 'primary.example.com',\n    },\n    'replica1': {\n        'ENGINE': 'django.db.backends.postgresql',\n        'NAME': 'mydb',\n        'USER': 'user',\n        'PASSWORD': 'pass',\n        'HOST': 'replica1.example.com',\n    },\n    'replica2': {\n        'ENGINE': 'django.db.backends.postgresql',\n        'NAME': 'mydb',\n        'USER': 'user',\n        'PASSWORD': 'pass',\n        'HOST': 'replica2.example.com',\n    },\n}\nREPLICA_DATABASES = ['replica1', 'replica2']  # required list\n\nDATABASE_ROUTERS = ['multidb.MultiDBRouter']\n\n# Optional: pinning for session consistency\nMIDDLEWARE = [\n    'multidb.pinning.MultiDBMiddleware',\n    # ... other middleware\n]","lang":"python","description":"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."},"warnings":[{"fix":"Update settings: rename SLAVE_DATABASES to REPLICA_DATABASES and ensure all replica aliases are listed.","message":"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.","severity":"breaking","affected_versions":">=0.9"},{"fix":"Use Python 3.7+ and Django 1.11+.","message":"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.","severity":"deprecated","affected_versions":">=0.9"},{"fix":"Always define REPLICA_DATABASES as a list of alias strings, even if only one replica is configured.","message":"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.","severity":"gotcha","affected_versions":"<0.9 (and later if missing)"},{"fix":"Add 'multidb.pinning.MultiDBMiddleware' to MIDDLEWARE.","message":"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.","severity":"gotcha","affected_versions":">=2.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Change entry to 'multidb.MultiDBRouter' for round-robin, or 'multidb.pinning.PinningRouter' for pinning behavior.","cause":"Misconfigured DATABASE_ROUTERS: using 'multidb.pinning.MultiDBRouter' instead of 'multidb.MultiDBRouter'.","error":"django.core.exceptions.ImproperlyConfigured: 'multidb.pinning' is not a valid router module (or does not provide a Router class)"},{"fix":"Ensure each alias in REPLICA_DATABASES exists as a key in DATABASES.","cause":"The database alias listed in REPLICA_DATABASES is not defined in the DATABASES dict.","error":"KeyError: 'replica1' (or other replica alias)"},{"fix":"Define REPLICA_DATABASES with at least one valid replica database alias.","cause":"The router is used but REPLICA_DATABASES is empty or not defined, causing reads to try to connect to a non-existent replica.","error":"AttributeError: 'NoneType' object has no attribute 'close' (or similar connection errors)"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}