API Reference¶

Auto-generated from source code docstrings.

Top-Level Exports¶

The most common symbols are available directly from django_rls_tenants:

from django_rls_tenants import (
    RLSConstraint,
    RLSManager,
    RLSProtectedModel,
    TenantQuerySet,
    TenantUser,
    admin_context,
    tenant_context,
    with_rls_context,
)

RLS Layer¶

Generic PostgreSQL Row-Level Security primitives. This layer has zero imports from tenants/.

GUC Helpers¶

django_rls_tenants.rls.guc.set_guc ¶

set_guc(
    name: str,
    value: str,
    *,
    is_local: bool = False,
    using: str = "default",
) -> None

Set a PostgreSQL session variable (GUC).

Parameters:

Name	Type	Description	Default
`name`	`str`	Variable name (e.g., `"rls.current_tenant"`).	required
`value`	`str`	Variable value as string.	required
`is_local`	`bool`	If `True`, use `SET LOCAL` (transaction-scoped). If `False`, use `set_config` (session-scoped, persists until changed).	`False`
`using`	`str`	Database alias. Default: `"default"`.	`'default'`

Raises:

Type	Description
`ValueError`	If `name` contains invalid characters.
`RuntimeError`	If `is_local=True` outside `transaction.atomic()`.

Source code in django_rls_tenants/rls/guc.py

def set_guc(
    name: str,
    value: str,
    *,
    is_local: bool = False,
    using: str = "default",
) -> None:
    """Set a PostgreSQL session variable (GUC).

    Args:
        name: Variable name (e.g., ``"rls.current_tenant"``).
        value: Variable value as string.
        is_local: If ``True``, use ``SET LOCAL`` (transaction-scoped).
            If ``False``, use ``set_config`` (session-scoped, persists until changed).
        using: Database alias. Default: ``"default"``.

    Raises:
        ValueError: If ``name`` contains invalid characters.
        RuntimeError: If ``is_local=True`` outside ``transaction.atomic()``.
    """
    _validate_guc_name(name)
    conn = connections[using]
    if is_local and not conn.in_atomic_block:
        raise RuntimeError(
            f"Cannot use SET LOCAL for '{name}' outside a transaction. "
            f"Wrap your code in transaction.atomic() or use is_local=False."
        )
    with conn.cursor() as cursor:
        if is_local:
            # SET LOCAL is transaction-scoped; auto-clears at commit/rollback.
            # The variable name is developer-controlled, not user input.
            cursor.execute(f"SET LOCAL {name} TO %s", [value])
        else:
            cursor.execute("SELECT set_config(%s, %s, false)", [name, value])

django_rls_tenants.rls.guc.get_guc ¶

get_guc(name: str, *, using: str = 'default') -> str | None

Get a PostgreSQL session variable value.

Returns:

Type	Description
`str \| None`	The variable value, or `None` if unset or empty.

Raises:

Type	Description
`ValueError`	If `name` contains invalid characters.

Source code in django_rls_tenants/rls/guc.py

def get_guc(name: str, *, using: str = "default") -> str | None:
    """Get a PostgreSQL session variable value.

    Returns:
        The variable value, or ``None`` if unset or empty.

    Raises:
        ValueError: If ``name`` contains invalid characters.
    """
    _validate_guc_name(name)
    conn = connections[using]
    with conn.cursor() as cursor:
        cursor.execute("SELECT current_setting(%s, true)", [name])
        result = cursor.fetchone()
        value = result[0] if result else None
        return value if value != "" else None

django_rls_tenants.rls.guc.clear_guc ¶

clear_guc(
    name: str,
    *,
    is_local: bool = False,
    using: str = "default",
) -> None

Clear a GUC variable by setting it to an empty string.

Parameters:

Name	Type	Description	Default
`name`	`str`	Variable name to clear.	required
`is_local`	`bool`	If `True`, use `SET LOCAL` (transaction-scoped).	`False`
`using`	`str`	Database alias. Default: `"default"`.	`'default'`

Source code in django_rls_tenants/rls/guc.py

def clear_guc(name: str, *, is_local: bool = False, using: str = "default") -> None:
    """Clear a GUC variable by setting it to an empty string.

    Args:
        name: Variable name to clear.
        is_local: If ``True``, use ``SET LOCAL`` (transaction-scoped).
        using: Database alias. Default: ``"default"``.
    """
    set_guc(name, "", is_local=is_local, using=using)

Constraints¶

django_rls_tenants.rls.constraints.RLSConstraint ¶

RLSConstraint(
    *,
    field: str,
    name: str,
    guc_tenant_var: str = "rls.current_tenant",
    guc_admin_var: str = "rls.is_admin",
    tenant_pk_type: str = "int",
    extra_bypass_flags: list[str] | None = None,
)

Bases: BaseConstraint

Django constraint that generates PostgreSQL RLS policies during migrations.

When Django applies a migration containing this constraint, it:

Enables RLS on the table (ALTER TABLE ... ENABLE ROW LEVEL SECURITY).
Forces RLS for the table owner (ALTER TABLE ... FORCE ROW LEVEL SECURITY).
Creates an isolation policy with configurable USING and WITH CHECK.

Parameters:

Name	Type	Description	Default
`field`	`str`	FK field name for tenant identification (e.g., `"tenant"`). The policy checks `{field}_id` against the GUC variable.	required
`name`	`str`	Constraint name. Supports `%(app_label)s` and `%(class)s`.	required
`guc_tenant_var`	`str`	GUC variable holding the current tenant ID. Default: `"rls.current_tenant"`.	`'rls.current_tenant'`
`guc_admin_var`	`str`	GUC variable for admin bypass. Default: `"rls.is_admin"`.	`'rls.is_admin'`
`tenant_pk_type`	`str`	SQL cast type for tenant PK. Default: `"int"`. Options: `"int"`, `"uuid"`, `"bigint"`.	`'int'`
`extra_bypass_flags`	`list[str] \| None`	Additional GUC variables that bypass the `USING` clause (but NOT `WITH CHECK`). Useful for auth edge cases.	`None`