Skip to main content

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:

TabFor
TablesSpreadsheet-style table editor: create tables, edit rows, add columns, import and export CSV. More
SQL editorRun SQL with a statement timeout and read-only mode; save snippets. More
PoliciesRow-level security policies in plain English, and templates to add them. More
SchemaTables 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​

RoleUsed byRow-level security
p_<project>_ownerMigrations, the Studio, MCP data tools; owns the tablesBypassed (owner)
p_<project>_serviceDATABASE_URL, tc.db.sqlBypassed (BYPASSRLS)
p_<project>_authenticatorThe Data API, to switch into tc_usern/a
tc_userSigned-in people, through the Data API or asUserApplies

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:

FunctionReturns
tc.user_id()The person's id (oid)
tc.user_email()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.
Availability

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.

Was this page helpful?