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). 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.
• 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 →
• 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 →
• 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 →
• 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.
• 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