API reference

Everything below is importable from the top-level fastapi_rls package (the integration classes are lazy-loaded, so importing the package never requires SQLAlchemy or FastAPI to be installed).

Facade

`RLS`

The central handle that ties configuration, the registry, engines, dependencies, and reconciliation together. Build one per process.

RLS(
    *,
    engine=None,              # sync Engine — dependencies, sync/audit, pool hygiene
    async_engine=None,        # AsyncEngine — async dependency
    sessionmaker=None,        # auto-created from engine if omitted
    async_sessionmaker=None,  # auto-created from async_engine if omitted
    config=None,              # RLSConfig; defaults to the active global config
    registry=None,            # PolicyRegistry; defaults to default_registry
    install_hygiene=True,     # install the pool-checkin scrub on a sync engine
)

Method	Returns	Purpose
`session_dependency(*, identity, sessionmaker=None, is_local=None)`	FastAPI dependency	Yields an RLS-scoped `Session`
`async_session_dependency(*, identity, sessionmaker=None, is_local=None)`	FastAPI dependency	Yields an RLS-scoped `AsyncSession`
`sync(*, engine=None, drop_untracked=False, force=True)`	`SyncPlan`	Apply the registry to the database
`plan(*, engine=None, drop_untracked=False, force=True)`	`SyncPlan`	Compute the plan without applying
`audit(*, engine=None)`	`list[AuditFinding]`	Report drift (read-only)

Policies

Class	Signature (key args)
`TenantPolicy`	`(name, , column=None, tenant_field=None, context_key="tenant_id", context_type="integer", *base)`
`UserPolicy`	`(name, , column=None, user_field=None, context_key="user_id", context_type="integer", *base)`
`CustomPolicy`	`(name, , using, check=None, *base)`
`BasePolicy`	`(name, *, table=None, operation="ALL", permissive=True, roles=None, key_prefix="rls")`

Common **base options come from BasePolicy: table, operation (ALL/SELECT/INSERT/UPDATE/DELETE), permissive, roles, key_prefix. context_type accepts integer/int/bigint/smallint/uuid/text/string.

Key methods: bind_table(table), require_table(), is_bound, get_using_expression(), get_check_expression(). See Policies.

Registry

`PolicyRegistry`

Holds bound policies grouped by table.

Method	Purpose
`register(policy)`	Add one policy (idempotent for the same object; raises on a name clash)
`register_many(policies)`	Add several
`register_table(table, policies)`	Bind and add
`tables()`	Tables with policies
`policies_for(table)`	Policies on a table
`all_policies()`	Every registered policy
`clear()`	Remove all

default_registry is the module-level instance the mixin and CLI use by default.

Context

Executor-based helpers. Sync and async forms share the same bookkeeping.

Sync	Async	Purpose
`set_rls_context(executor, key, value, *, system=False)`	`aset_rls_context`	Set one key
`apply_rls_context(executor, mapping, *, system=False, is_local=True)`	`aapply_rls_context`	Set a mapping
`clear_rls_context(executor)`	`aclear_rls_context`	Clear context
`rls_context(executor, **keys)`	`arls_context`	Scoped set/restore (context manager)
`system_rls_context(executor, **keys)`	—	Scoped, auditable elevation
`require_rls_context()`	—	Raise if no identity is present
`has_rls_identity_context()`	—	Whether identity is set
`get_active_rls_context()`	—	Read the in-process mirror (see caveat below)

warning

get_active_rls_context() is not reliable inside sync FastAPI route handlers — read identity from your own dependency. See request context.

Configuration

RLSConfig (frozen dataclass), configure(...), get_config(). See the configuration reference.

Exceptions

All inherit from RLSError.

Exception	Raised when
`RLSError`	Base class
`PolicyError`	Invalid policy construction (bad name/identifier, forbidden `CustomPolicy` SQL)
`ConfigurationError`	Invalid config or a missing engine/sessionmaker
`RLSContextImmutableError`	Overriding an already-set `user_id`/`tenant_id` without a system context
`RLSContextRequiredError`	`require_context=True` and no identity is present
`TenantAccessDeniedError`	A tenant access check fails

Adapters and integrations

fastapi_rls.adapters.sqlalchemy — RLSMixin, SessionExecutor, AsyncSessionExecutor, collect_policies, install_pool_hygiene.
fastapi_rls.middleware — RLSContextMiddleware, identity_from_state.
fastapi_rls.alembic_ops — import to register op.* directives.
fastapi_rls.ddl — pure statement builders (enable_rls, create_policy, …).
fastapi_rls.sync — plan_sync, apply_sync, audit, SyncPlan, AuditFinding.

Deferred to a later release

These are intentionally not in v0.1 and are documented so you know the boundary:

SQLAlchemy-expression policies (the analog of django-rls' Q-object ModelPolicy).
Hierarchical / recursive-CTE RLS.
Context processors for injecting extra dynamic context variables.
Native async pool-hygiene scrub (the async path relies on SET LOCAL, which is sufficient on its own).

Facade​

RLS​

Policies​

Registry​

PolicyRegistry​

Context​

Configuration​

Exceptions​

Adapters and integrations​

Deferred to a later release​