Skip to main content

CLI

The fastapi-rls command reconciles a policy registry against a live database. It's the no-Alembic path — and audit is useful in CI regardless of how you apply policies. Install the cli extra:

pip install "fastapi-rls[cli]"

Pointing at your policies​

Every reconciling command takes:

  • --url (or the DATABASE_URL env var) — a SQLAlchemy database URL.
  • --policies — a dotted path that loads your registry.
fastapi-rls sync --url "$DATABASE_URL" --policies myapp.models

--policies myapp.models imports that module; its RLSMixin models register themselves into the default registry as a side effect of import. --policies myapp.models:my_registry uses that specific PolicyRegistry object instead.

Commands​

sync — reconcile​

Enables + forces RLS and creates every registered policy, in a transaction.

fastapi-rls sync  --url "$DATABASE_URL" --policies myapp.models
fastapi-rls sync  --url "$DATABASE_URL" --policies myapp.models --dry-run
fastapi-rls sync  --url "$DATABASE_URL" --policies myapp.models --drop-untracked
  • --dry-run prints the plan without applying it.
  • --drop-untracked also drops policies present in the database but absent from the registry (off by default — reconciliation is additive unless you ask).

plan — show the DDL​

Prints exactly what sync would apply, without touching the database state.

fastapi-rls plan --url "$DATABASE_URL" --policies myapp.models

audit — report drift​

Read-only. Reports differences between the registry and the database, and exits non-zero when drift exists — ideal for CI.

fastapi-rls audit --url "$DATABASE_URL" --policies myapp.models
[missing_policy] documents: tenant_isolation is declared but not in the database

enable / disable​

Toggle RLS on a single table without touching policies.

fastapi-rls enable  --url "$DATABASE_URL" documents   # ENABLE + FORCE
fastapi-rls disable --url "$DATABASE_URL" documents   # DISABLE

In CI​

Fail the build when the database (or a review app) drifts from your declared policies:

- name: Check RLS policies are in sync
  run: fastapi-rls audit --url "$DATABASE_URL" --policies myapp.models

See the full command help with fastapi-rls --help and fastapi-rls <command> --help.