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

Contributing

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

License

MIT