windmill/docs/datatable-viewer-roles.md

# Data table connections and the viewer's roles

A data table under roles (Enterprise Edition) resolves a connection that names a role to that
role alone. A connection that names none is resolved from the data table's default role:

| Default role | A connection naming no role holds |
|---|---|
| `admin` (until changed) | `admin`, as before viewer roles existed |
| another role | that role when the job's own identity may use it, plus **every role the job's viewer is a tenant of** |
| none (`NO_DEFAULT_DATATABLE_ROLE`) | the viewer's roles only |

A connection left with no role at all is refused. Postgres row-level security can then answer
per viewer from a backend runnable that runs as the app's publisher, with nothing written in the
runnable.

Policies test membership, which is true for a role's own login too, so one policy serves a named
connection and an unnamed one:

```sql
CREATE POLICY emea ON orders FOR SELECT
  USING (region = 'emea' AND pg_has_role(current_user, 'sales_emea', 'member'));
```

A policy names its role as text, so renaming the role breaks it.

## Code

| Where | What |
|---|---|
| `windmill-common/src/workspaces.rs` | `DatatableAccess`, `get_datatable_resource_from_db` |
| `windmill-common/src/datatable_roles_ee.rs` | `resolve_datatable_role_connection`, `viewer_role_ids`, `ensure_role_set_login`, `retire_role_set_logins_of`, `sweep_unused_role_set_logins` |
| `windmill-api-jobs/src/execution.rs` | `run_end_user_email`, where a run's viewer is recorded |
| `frontend/.../workspaceSettings/DataTablePermissionsButton.svelte` | the roles drawer, which warns while the default is `admin` |

## What holds it together

- **A default of `admin` is not a floor.** `admin` owns the tables and bypasses row-level
  security, so nothing could be added to it, and it is the default until someone changes it.
  Such a data table resolves exactly as it did before viewer roles existed. Nothing ever sets a
  default back to `admin`: removing or deleting the default role leaves none.
- **The default role is tenant-checked against the job's own identity**, the publisher for a
  publisher-mode app, and held only when that passes. The viewer's roles are added either way.
- **No role at all is a refusal, never an empty answer.** There is no login that would read
  nothing: what a role sees is up to each table's grants and policies. A job without a recorded
  viewer (anonymous app viewer, schedule, trigger, a tool job started by an AI agent step), or
  whose viewer is not a member of the governing workspace, therefore needs a default it may use
  or a named role.
- **A set login owns what it creates.** Postgres gives a new object to `current_user`, and
  default privileges go by the creating role, so a table created over a connection that holds
  several roles belongs to that set's login: no other role or viewer reaches it, and it passes to
  `custom_instance_user` when the login is swept. Unnamed connections are for rows. To create an
  object, name a role or run `SET ROLE <role>` first, which a set login may do for any role it
  holds. Migrations are not affected: one that declares no role runs as `admin`.
- **The viewer is `job_perms.end_user_email`, and nothing else.** The server records it when the
  run starts: the session behind an app request, the caller of a direct run or preview, and for a
  job started with another job's token, that job's viewer. No argument reaches it.
- **A cached result belongs to one viewer.** `cached_result_path` hashes the run's recorded viewer
  into the key, since a cache hit returns before any connection is resolved. Runs with no viewer
  recorded keep sharing one entry.
- **Only a tenant list naming the viewer counts.** A workspace admin may *use* every role,
  `admin` included. The viewer's roles are those whose tenants name them (user, group, folder,
  `*`), and never `admin`.
- **One role is that role's login. Several are a login per distinct set.** `wm_set_<hash>` is a
  member of exactly those roles, with `INHERIT`; the hash is over their catalog ids, so a rename
  moves nothing and a change in someone's groups resolves them to another login instead of
  editing one. Its privileges are its memberships, so `SET ROLE` only narrows and `RESET ROLE`
  comes back to it. The prefix is reserved in `validate_role_name`.
- **Resolving stays cheap where no viewer could add anything.** The viewer is only looked up when
  some role other than the default and `admin` has tenants on that data table.
- **A `datatable_role_set` row with a password names a login that can authenticate with it.** The
  row is written after the login exists and removed, in its own commit, before the login is
  dropped or made `NOLOGIN`. A login without a row is taken back with a new password on next use,
  and so is one whose row has an empty password: that is what a sweep leaves when it could
  neither drop a login nor let it back in, so the next sweep still finds it.
- **Set logins are bounded by use, not by the number of role combinations.** One exists only for
  a set some viewer actually connected with, so there are at most as many as (viewer, data table)
  pairs. `last_used_at` is recorded at most once a day, and `sweep_unused_role_set_logins`, run
  from the monitor loop, drops those unused for 30 days; a dropped one is made again on demand.
  The sweep goes by this instance's rows, never by the cluster's `wm_set_*` roles: a cluster can
  serve several Windmill instances.
- **Disabling or dropping a role retires every set login holding it.** `NOLOGIN` on a role does
  not reach a login that is a member of it.
- **A worker or server that predates this connects as the default role alone**, so a mixed fleet
  shows a viewer fewer rows, never more. It refuses a data table with no default role, whose
  marker it reads as a role the data table lacks.

## Trust

A job that names no role runs its author's code with the viewer's reach into the data table, the
same trust as an app in viewer execution mode or a script someone else wrote and you run. Whoever
can deploy a publisher-mode app, or a script that others run, can therefore read through the
non-`admin` roles of the people who use it. Naming a role in the code is how an author pins the
connection to one role instead.