Scalable row-level multi-tenancy for Django with PostgreSQL Row Level Security.
These guides are task-focused. For the exhaustive API and option tables, see the README, which is the reference layer. For per-setting detail, see the settings reference.
I want to...
| I want to... | Go to |
|---|---|
| Build a multi-tenant app from scratch | Build your first multi-tenant app |
| Define the tenant model itself | Set up a tenant model |
| Scope a model that reaches the tenant through a relation | Scope a model through a relation |
| Scope a service or task that already holds the tenant | Scope a function that holds the tenant |
| Add boundary to an app that already has data | Add boundary to an existing app |
| Decide how requests map to tenants | Choose and order resolvers |
| Rename "tenant" to merchant, organisation, club | Customise the terminology |
| Write tests that don't leak across tenants | Write tenant-safe tests |
| Enforce isolation at the database level | Add RLS policies with migrations |
| Keep tenant context inside Celery tasks | Run Celery tasks with tenant context |
| Serve tenants from region-specific databases | Deploy across multiple regions |
| Safely operate across all tenants | Run cross-tenant admin operations |
| Create or delete tenants | Provision and deprovision tenants |
| Understand why isolation has two layers | Isolation layers and the threat model |
| Understand how a request becomes a tenant | How tenant resolution works |
Look up a BOUNDARY_ setting |
Settings reference |
| Fix an error or unexpected behaviour | Troubleshooting |
How these docs are organised
The documentation follows the Diátaxis model:
- Tutorial: a single, opinionated path from nothing to a working multi-tenant app. Start here if you are new.
- How-to guides: recipes for specific tasks. Each one states a goal, lists prerequisites, gives runnable steps, and shows how to verify the result.
- Explanation: the "why": the threat model, the two isolation layers, and the request-to-tenant lifecycle. Read these to build a mental model.
- Settings reference and the README: the exhaustive lookup tables.
- Troubleshooting: symptom, cause, fix.
New to django-boundary?
- Read Isolation layers and the threat model to understand what the package protects against.
- Follow the tutorial end to end.
- Keep the settings reference and troubleshooting page open as you integrate.