Row-level security
Row-level security (RLS) is how a vastframe app decides which rows each signed-in person can read and change. Because the platform passes the person's identity into Postgres, policies can use their id, email, department, groups and app roles, with no auth code in the app.
How it works
- A browser calls the Data API (
/_tc/db/...) or server code usestc.db.asUser(req). - Postgres runs the query as the
tc_userrole with the person's claims attached. - Policies on each table, written
to tc_user, decide which rows are visible and which changes are allowed, using helpers liketc.user_id().
Service-role access (DATABASE_URL, tc.db.sql) and the Studio bypass RLS.
Policy templates
Database › Policies lists every policy with a plain-English description, and adds new ones from templates. New tables get a template when they're created.
| Template | What it allows |
|---|---|
| Everyone with app access can read | Anyone who can open the app can read every row. Nobody can write unless another policy allows it |
| Rows belong to the creator | People see and change only the rows they created. Adds a created_by column filled with the signed-in person |
| Editors can write | People with an app role (default editor) can add, change and delete rows |
| A role can read and change every row | People with an app role (for example approver or admin) can read and change all rows, whoever created them |
| An Entra group can read | Members of a group (for example Finance - FP&A) can read every row |
Templates can be combined: "rows belong to the creator" plus "a role can read and change every row" (role approver) gives a classic request-and-approve app.
What the templates generate
-- Rows belong to the creator
alter table public.expenses add column if not exists created_by text default tc.user_id();
create policy "Creators read their own rows" on public.expenses for select to tc_user
using (created_by = tc.user_id());
create policy "Creators add rows as themselves" on public.expenses for insert to tc_user
with check (created_by = tc.user_id());
create policy "Creators change their own rows" on public.expenses for update to tc_user
using (created_by = tc.user_id()) with check (created_by = tc.user_id());
create policy "Creators delete their own rows" on public.expenses for delete to tc_user
using (created_by = tc.user_id());
-- A role can read and change every row (role: approver)
create policy "Role approver can read and change every row" on public.expenses for all to tc_user
using (tc.has_role('approver')) with check (tc.has_role('approver'));
Plain-English descriptions
Every policy, including ones you write by hand, is shown in words in Database › Policies, for example Signed-in users can add rows when the row's created_by is the signed-in user. Use it to check what a policy really does.
Identity helpers
| Helper | Example |
|---|---|
tc.user_id() | using (created_by = tc.user_id()) |
tc.user_email() | using (assignee_email = tc.user_email()) |
tc.user_name() | created_by_name text default tc.user_name() |
tc.department() | using (department = tc.department()) |
tc.in_group(name) | using (tc.in_group('Finance - FP&A')) |
tc.has_role(name) | using (tc.has_role('approver')) |
tc.claims() | (tc.claims() ->> 'job_title') |
App roles are assigned on the project's Access page (or MCP set_access with roles). Group names and departments come from your directory.
Writing policies by hand
alter table budget_lines enable row level security;
create policy "same department reads" on budget_lines for select to tc_user
using (department = tc.department());
create policy "finance admins write" on budget_lines for all to tc_user
using (tc.in_group('Finance Admins')) with check (tc.in_group('Finance Admins'));
Rules of thumb:
- Always write policies
to tc_user. - Use
with checkon insert and update so people can't write rows they couldn't read. - Default
created_bytotc.user_id()so the browser never has to send it; a forged value is refused by the check.
Troubleshooting
| Symptom | Likely cause |
|---|---|
| The app sees no rows, the Studio sees them all | RLS is on and no policy allows select for this person. Add one |
| Insert fails with a policy violation | The with check doesn't hold, often because the browser sent a created_by that isn't the signed-in person. Drop it from the insert and use the default |
| A role-based policy doesn't match | The person doesn't have the app role in this project. Check Access › App roles; roles arrive in the token within seconds of saving |
| A group-based policy doesn't match | Group names are matched exactly, including spaces and case |