Python: Simulation
Run access simulations as every user type, preview policy or SQL changes, and compare runs with the Python SDK.
Checks who can do what in your project without writing anything. Use a team member's token — simulations act on the project's configuration. Background: Simulate access before you ship.
run = await sovaria.simulate_run(resource="public.orders")
if run["cases_fail"]:
raise SystemExit(f"{run['cases_fail']} access checks failed")Methods
sovaria.sim_compare_runs
Sim compare runs.
await sovaria.sim_compare_runs(
target_run_id: str,
baseline_run_id: str,
) -> dict[str, Any]Parameters
target_run_idstrrequiredbaseline_run_idstrrequired
- Returns
dict[str, Any]
sovaria.sim_discover
Sim discover.
await sovaria.sim_discover() -> dict[str, Any]- Returns
dict[str, Any]
sovaria.sim_get_run
Sim get run.
await sovaria.sim_get_run(run_id: str) -> dict[str, Any]Parameters
run_idstrrequired
- Returns
dict[str, Any]
sovaria.sim_list_runs
Sim list runs.
await sovaria.sim_list_runs(
*, limit: int = 20,
offset: int = 0,
) -> dict[str, Any]Parameters
limitintoptionaldefault20offsetintoptionaldefault0
- Returns
dict[str, Any]
sovaria.simulate_change
Try a change before making it; nothing is written.
policy (SPL, optionally replaces a live policy id) or disable_policy_ids: who gains and who loses access.
await sovaria.simulate_change(
*, policy: str | None = None,
policy_name: str = 'draft',
replaces: str | None = None,
disable_policy_ids: list[str] | None = None,
sql: str | None = None,
) -> dict[str, Any]sql: the script runs with every check and is rolled back; the answer lists objects added/dropped/changed, rows changed and tables that would be rewritten under a full lock. violations lists what should block the change.
Parameters
policystr | NoneoptionaldefaultNonepolicy_namestroptionaldefault'draft'replacesstr | NoneoptionaldefaultNonedisable_policy_idslist[str] | NoneoptionaldefaultNonesqlstr | NoneoptionaldefaultNone
- Returns
dict[str, Any]
sovaria.simulate_plan
Preview simulation traversal without execution side effects.
await sovaria.simulate_plan(
simulation_name: str,
operations: list[dict[str, Any]],
*, context: dict[str, Any] | None = None,
) -> dict[str, Any]Parameters
simulation_namestrrequiredoperationslist[dict[str, Any]]requiredcontextdict[str, Any] | NoneoptionaldefaultNone
- Returns
dict[str, Any]
sovaria.simulate_run
Who can do what in the live project, as visitors, the app's users and the team. Every persona's requests go through the real gateway; SQL writes run with every check and are rolled back, other writes stop after their access checks, so nothing is written.
await sovaria.simulate_run(
simulation_name: str | None = None,
operations: list[dict[str, Any]] | None = None,
*, resource: str | None = None,
action: str | None = None,
role: str | None = None,
include_execution_tree: bool = False,
context: dict[str, Any] | None = None,
) -> dict[str, Any]resource/action/role narrow the run (role: __guest__, __app_user__, app:<role> or a team role). simulation_name/operations are accepted for older callers and ignored: the run covers the whole project.
Parameters
simulation_namestr | NoneoptionaldefaultNoneoperationslist[dict[str, Any]] | NoneoptionaldefaultNoneresourcestr | NoneoptionaldefaultNone- Only this table/collection/bucket/channel/function.
actionstr | NoneoptionaldefaultNone- Only this action, e.g.
sql:delete. rolestr | NoneoptionaldefaultNone__guest__,__app_user__,app:<role>or a team role.include_execution_treebooloptionaldefaultFalsecontextdict[str, Any] | NoneoptionaldefaultNone
- Returns
dict[str, Any]