django-db-tenants¶
Database-per-client multi-tenancy for Django, with tenant databases registered at runtime.
This site is the developer's guide. It is for:
- contributors who change, test and release the library;
- developers who integrate the library into a Django project and need to know how it works inside.
What the library does¶
- One shared database holds the client registry. Every client (the tenant) gets its own database, with its own
authusers, sessions and application tables. - Tenant databases are added to
django.db.connectionswhile the process runs, so adding, suspending or re-pointing a client never needs a restart. - How each client's database is reached, created and dropped is pluggable: a database strategy per client, configured by encrypted parameters. The built-in one derives tenant connections from the shared database's settings.
Where to start¶
| You want to | Read |
|---|---|
| Get from a fresh clone to passing tests and a running demo | Quick start |
| Set up a full workstation (PostgreSQL, MySQL, IDE, docs) | Local environment setup |
| Understand the design behind the multi-tenancy | Design overview |
| Understand how a request reaches the right database | Architecture |
| Look up a model, a command, a setting or a function | Model reference, CLI reference, API reference |
| Send a change | Contribution guidelines |
The project's README has the short integration recipe (settings, URLs, first tenant). Terms used across these pages are defined in the glossary.
Build these docs¶
The published version, built from the develop branch, is at https://gigiusb.github.io/django-db-tenants/. To build it locally:
uv run zensical serve # live preview on http://127.0.0.1:8000/
uv run tox -e docs # strict build, as the docs check runs it
Next steps¶
Start with the Quick start.