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. Open a discussion →

Requirements

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

Contributing

Contributions are welcome! See the contributing guide to get started. This project is governed by the Contributor Covenant Code of Conduct.

License

MIT