django-rls-tenants

Database-enforced multitenancy for Django using PostgreSQL Row-Level Security. Every query -- ORM, raw SQL, dbshell -- is filtered by the database itself. Missing tenant context returns zero rows, never leaks data.

Why this library?

Existing Django multitenancy libraries enforce isolation at the application level — one missed filter and data leaks across tenants. django-rls-tenants pushes enforcement to PostgreSQL itself using Row-Level Security. Every query — ORM, raw SQL, dbshell — is filtered by the database. Missing tenant context returns zero rows, never leaked data.

Learn more about the RLS approach →

Features

• Database-enforced isolation -- RLS policies protect tenant tables across ORM queries, raw SQL, dbshell, and data migrations when using a database role subject to RLS (not a superuser or BYPASSRLS role; system check W005 warns about those, and E001 is an error for them when DEBUG is off). It guards against omitted tenant scoping, not arbitrary SQL on the app connection -- see the security model.
• Fail-closed by default -- missing tenant context returns zero rows; optional STRICT_MODE raises NoTenantContextError on unscoped TenantQuerySet evaluation (STRICT_MODE_EXCLUDE exempts listed models, such as the user model an auth backend reads).
• Automatic query scoping -- RLSProtectedModel adds the tenant FK, the RLS policy, and a tenant-scoped manager.
• Index-friendly by design -- the manager's WHERE tenant_id = X is what reaches the planner; the policy alone is a post-scan filter. Composite (tenant, ...) indexes, partial indexes, joins and the v1.3.0 InitPlan form, with measured EXPLAIN plans. Performance guide →
• Tenant-aware Django admin -- RLSTenantModelAdmin scopes changelists, forms, and related dropdowns to the current tenant, with a tenant switcher for cross-tenant admins. Admin guide →
• Cross-tenant foreign key validation -- full_clean(), forms, the admin and DRF serializers reject a foreign key to another tenant's row, which RLS cannot catch; validate_cross_tenant_fks() covers service code. Guide →
• Native Celery integration -- @rls_task carries the active tenant context from enqueue to worker, including across chains, groups, and chords (pip install "django-rls-tenants[celery]"). Celery guide →
• Django REST Framework integration -- RLSTenantAPIViewMixin opens the RLS context after DRF authenticates the user (token and JWT clients included, which the middleware cannot see), RLSTenantPermission refuses a view that runs outside it, and RLSTenantModelSerializer fills the tenant FK from it (pip install "django-rls-tenants[drf]"). DRF guide →
• Async context managers -- async with async_tenant_context(...) for async views, consumers and tasks; tenant state is set in the coroutine, so the async ORM is scoped. Async context managers → · Async deployment guide →
• Per-tenant management commands -- run_as_tenant runs any management command inside one tenant's context and run_for_all_tenants runs it once per tenant (filters, --parallel, --json, a failure summary and exit status), so reports, re-indexing and backfills need no context code of their own. Management commands guide →
• Audit logging -- structured records on the django_rls_tenants.audit logger each time a tenant or admin context is entered, exited or refused (who, which tenant, which code path), ready for a JSON formatter and routed with Django's LOGGING. Audit logging guide →
• Users in several tenants -- a user model that adds rls_tenant_ids (MultiTenantUser) selects the tenant a request runs in with an X-Tenant header or switch_tenant(); the middleware, the DRF mixin and the admin check every selection against the user's tenants and refuse any other with a 403. Guide →
• Raw SQL helpers -- safe_tenant_sql() builds a tenant-filter predicate; current_tenant_value_sql() returns the current tenant ID expression for inserts and projections. Both reuse the expressions used by RLS policies. Raw SQL guide →
• M2M isolation -- auto-detected subquery-based RLS policies on M2M through tables; check_rls --generate writes the migration that creates them.
• Third-party tables -- AddRLSPolicy adds the same policy to a table of an app you do not own, and RLS_TENANTS["EXTERNAL_MODELS"] makes check_rls, the cross-tenant foreign key check and the select_related() / prefetch_related() tenant filters treat the model as protected. Guide →
• Sharing rows across tenants -- extra_predicates (SharedWith, TenantField, RawPredicate) let a tenant read rows another tenant shares with it, in a separate FOR SELECT policy that never lets it update or delete them; including_shared() queries them. Guide →
• Single schema, single database -- no schema-per-tenant overhead, no connection routing.

Quick Start

pip install django-rls-tenants

# settings.py
INSTALLED_APPS = [..."django_rls_tenants"]

RLS_TENANTS = {
    "TENANT_MODEL": "myapp.Tenant",  # required
}

MIDDLEWARE = [..."django_rls_tenants.RLSTenantMiddleware"]

# models.py
from django_rls_tenants import RLSProtectedModel

class Order(RLSProtectedModel):
    title = models.CharField(max_length=255)
    # tenant FK + RLS policy added automatically

python manage.py migrate
python manage.py check_rls   # verify policies are in place

Full tutorial and documentation → Something not working? Start with the Troubleshooting page (symptom / cause / fix).

Want to see it in action first? Check out the example project -- cd example && docker compose up, then open http://localhost:8000.

Comparison with Alternatives

See the full comparison →

Used in Production

Are you using django-rls-tenants in production? We'd love to hear about it. Used in production? Tell us →

Requirements

See the supported-versions policy for how these lists change.

Contributing

Contributions are welcome! See the contributing guide to get started. Questions and bug reports have their own places: see SUPPORT.md. This project is governed by the Contributor Covenant Code of Conduct.

License

MIT