Database
Each project has its own Postgres database, created with the project. You don't create servers, users or connection strings: the platform provisions them and hands your code the right access.
Open it in the console
Open the project, then Database. The Studio has four tabs:
| Tab | For |
|---|---|
| Tables | Spreadsheet-style table editor: create tables, edit rows, add columns, import and export CSV. More |
| SQL editor | Run SQL with a statement timeout and read-only mode; save snippets. More |
| Policies | Row-level security policies in plain English, and templates to add them. More |
| Schema | Tables and relationships as a diagram. More |
The owner, people with the developer app role, Org Admins and Delegated Admins in scope can change things. Auditors can browse tables, policies and the schema, and run read-only SQL.
How your code connects
In the browser
Use the SDK's Data API client. It uses Supabase / postgrest-js syntax, runs as the signed-in person, and row-level security applies:
import { tc } from '@tenantcloud/sdk'
const { data, error } = await tc.db.from('purchase_requests')
.select('*')
.eq('status', 'pending')
.order('created_at', { ascending: false })
await tc.db.from('purchase_requests').insert({ title: 'Monitor', amount: 240 })
No URL or key: requests go to /_tc/db/* on the page's own origin. See Data API.
In server code
import { tc } from '@tenantcloud/sdk'
// As the project's service role (bypasses RLS). Tagged template = parameterised.
const rows = await tc.db.sql`select status, count(*)::int as n from purchase_requests group by status`
// As the signed-in person (RLS applies)
const { data } = await tc.db.asUser(req).from('purchase_requests').select('*')
const mine = await tc.db.asUser(req).sql`select * from purchase_requests`
from tenantcloud import tc
rows = tc.db.sql("select * from purchase_requests where status = %s", ["open"]) # a DataFrame if pandas is installed
res = tc.db.as_user(request).from_("purchase_requests").select("*").execute()
DATABASE_URL is also set, so any Postgres client or ORM works. It connects as the service role, which bypasses row-level security: use it for trusted server logic and jobs, and use asUser when acting for a person.
In jobs
Cron and worker services get DATABASE_URL and use tc.db.sql as the service role.
Roles in a project database
| Role | Used by | Row-level security |
|---|---|---|
p_<project>_owner | Migrations, the Studio, MCP data tools; owns the tables | Bypassed (owner) |
p_<project>_service | DATABASE_URL, tc.db.sql | Bypassed (BYPASSRLS) |
p_<project>_authenticator | The Data API, to switch into tc_user | n/a |
tc_user | Signed-in people, through the Data API or asUser | Applies |
tc_user can't log in directly; it's reachable only through a project's Data API. Policies are written to tc_user.
In a vastframe cloud organization, names carry the tenant slug too (p_<tenant>__<project>), so databases of different organizations never share a name. See Multi-tenancy and isolation.
Identity in SQL
Helpers in the tc schema read the signed-in person from the request:
| Function | Returns |
|---|---|
tc.user_id() | The person's id (oid) |
tc.user_email() | |
tc.user_name() | Display name |
tc.department() | Department from the directory |
tc.in_group('Finance - FP&A') | Whether the person is in the group |
tc.has_role('approver') | Whether the person has the app role |
tc.claims() | All claims as JSON |
Use them in policies and as column defaults (created_by text default tc.user_id()). See Row-level security.
Good practice
- Turn on row-level security for every table people reach from the browser, and add the policies you need. Don't disable RLS to make something work.
- Keep files out of the database: store them in Storage and keep the path in a column.
- Version schema changes as migrations.
On the local stack project databases live on a shared Postgres server with derived passwords. On Azure they move to Azure Database for PostgreSQL Flexible Server with Entra authentication and managed identities, and point-in-time restore. That driver is coming soon; backups and "restore to a new database" aren't available in the console yet.