Schema
Tables
A table is declared once, in TypeScript, in the backend/schema/ directory.
That declaration is the only thing the backend knows about your data. From it,
Rebase generates the table and its row-level security policies in Postgres,
serves the table over REST, realtime and MCP, and types the SDK.
// backend/schema/posts.tsimport { defineTable, col, rel } from "@rebasepro/server/schema";import { users } from "./users";
export const posts = defineTable("posts", { columns: { id: col.uuid().primaryKey().defaultRandom(), title: col.text().notNull().validate({ min: 3, max: 200 }), status: col.enum(["draft", "published", "archived"]).notNull().default("draft"), publishDate: col.timestamp({ withTimezone: true }), createdAt: col.timestamp({ withTimezone: true }).notNull().onCreateNow(), }, relations: { author: rel.belongsTo(() => users, { notNull: true }), }, rls: [ { operation: "select", access: "public", condition: { status: "published" } }, { operations: ["select", "insert", "update"], roles: ["editor"] }, { operation: "delete", roles: ["admin"] }, ],});Three things are worth reading off this example before anything else:
- Columns are nullable unless you say otherwise, as in SQL.
.notNull()makes a columnNOT NULLand required on create. See Columns. - The foreign key is declared by the relation.
authorderives anauthor_idcolumn, its constraint and its index. See Relations. rlsis required. A table without a row-level security posture is a type error, and it is refused when the schema is compiled. See Row-level security.
The backend/schema directory
Section titled “The backend/schema directory”backend/├── schema/│ ├── index.ts # exports every table and view, and optionally defaultRls│ ├── users.ts # defineAuthTable("users", …)│ ├── posts.ts # defineTable("posts", …)│ └── tags.ts # defineTable("tags", …)├── functions/└── crons/One file per table is a convention, not a rule. What counts is
backend/schema/index.ts: the backend reads the tables and views it exports,
and nothing else.
// backend/schema/index.tsimport type { DefaultRls } from "@rebasepro/server/schema";
export { users } from "./users";export { posts } from "./posts";export { tags } from "./tags";
// What every table declared with `rls: "inherit"` takes.export const defaultRls: DefaultRls = [ { operation: "select", access: "authenticated" },];defaultRls is optional. It is only read by tables that say
rls: "inherit"; a project that never writes "inherit" does not need it.
The directory is backend/schema unless rebase.json names another one with
the tables key. The schema key keeps its old meaning: the generated Drizzle
module.
{ "apps": { "backend": { "type": "backend", "runtime": "managed", "tables": "backend/schema" } }}A project without backend/schema/index.ts declares no tables. The backend
then reads the tables from the live database at boot, and serves only those
with row-level security enabled. See Backend only.
The schema files are plain TypeScript with no server dependencies:
@rebasepro/server/schema loads nothing of the server. A frontend can
import type { posts } from "../../backend/schema/posts" to type its own code
against a table, without pulling backend code into the browser bundle.
What a table becomes
Section titled “What a table becomes”| From the declaration | Rebase generates |
|---|---|
columns, relations, indexes |
the CREATE TABLE, foreign keys, junction tables and indexes, written to schema.sql by rebase db push and rebase db generate |
rls, tenant, the auth table |
ENABLE ROW LEVEL SECURITY and one CREATE POLICY per rule and operation, in policies.sql |
search, vector columns |
the generated tsvector column and the GIN and ANN indexes |
| the slug | the REST routes under /api/data/<slug>, realtime subscriptions, the MCP tools and the OpenAPI document |
| the columns’ types and modifiers | the SDK’s Row, Insert and Update types, and the inferred types you can use in your own code |
Every surface reads the same compiled form of the table, called its
descriptor: columns with their Postgres types, nullability, validation and
storage rules, relations resolved to slugs, and the row-level security
posture. Hook code never leaves the server; the descriptor only says which
hooks exist. The backend serves the descriptors at GET /api/schema/tables,
which is what the CMS, the Studio and the MCP apps render from.
The pipeline from declaration to database is described in Schema as code.
defineTable options
Section titled “defineTable options”defineTable(name, config) takes the table’s name and these keys:
| Key | What it does |
|---|---|
columns |
Required. col.* builders by key, in physical order. At least one must be .primaryKey(). See Columns. |
rls |
Required. "admin-only", "inherit", or a non-empty list of rules. See Row-level security. |
relations |
rel.* builders by relation name. See Relations. |
slug |
The name in the API, the SDK and in scopes. The table’s name when omitted. |
table |
The SQL table name, when it differs from the name. |
schema |
The Postgres schema. public when omitted. |
database |
A non-default Postgres database, declared in backend/resources.ts. See Multiple sources. |
description |
What the table holds. Shown in OpenAPI and in the MCP tool descriptions. |
defaultPolicies |
false generates only your rules, without the admin baseline policies. Refused with rls: "admin-only". true keeps the baseline when the table’s database switches it off for every table (database({ rls: { defaultPolicies: false } })). Left out, the database’s setting decides. |
rlsRequired |
false serves the table even when the database does not enforce its rls (row-level security off, declared policies missing), for a schema another tool owns and an app that enforces access itself. true requires it under a database that says database({ rls: { required: false } }). Left out, the database’s setting decides, and a table the database does not protect is not served by a boot that provisions nothing. See Another tool owns the schema. |
tenant |
Scope every row to a tenant. See Tenancy. |
softDelete |
true or { field }: a delete stamps a timestamp instead of removing the row. See Soft delete. |
history |
true records every write in the history table. See Entity history. |
search |
Ranked full-text search over the columns named. See Search. |
indexes |
Indexes, each with the query it serves. See Indexes. |
hooks |
Server-side lifecycle hooks. See Table hooks. |
strictWrites |
A write naming a column the table does not declare is a 400. false accepts it, for a column that exists in the database without being declared (filled by a trigger, say). The column still has to exist. |
metadata |
Any data you want served with the table’s descriptor. Rebase does not read it. |
Two more definitions share most of these keys:
defineAuthTable for the table users are stored
in, and defineView for SQL views.
The first argument of defineTable is the table’s name, and it is the default
for everything else:
| Name | Default | Override |
|---|---|---|
| SQL table | the name | table: "blog_posts" |
| API slug, SDK accessor, scope target | the name | slug: "articles" |
| Postgres schema | public |
schema: "content" |
| SQL column of a column | the snake_case of its key | the builder’s first argument: col.text("legacy_name") |
A column’s key is its name on the JSON row, in the SDK and in filters and
sorts. Its SQL name is the snake_case of the key: publishDate is the column
publish_date, and photoURL is photo_url. A builder’s first argument maps
a key to any other SQL name, as in Drizzle (col.text("legacy_name")), which
is how a table adopts an existing database’s names without changing what
clients see.
table and schema must be plain SQL identifiers. Two definitions may not
share a name, a slug or a SQL table. The slug matters beyond the URL: foreign
key and junction column names are derived from it, so changing the slug of a
table that is already deployed can rename columns. Set slug explicitly when it
should differ from the table’s name, and leave it alone afterwards.
Primary keys
Section titled “Primary keys”There is no implicit id column. Every table marks at least one column
.primaryKey():
import { defineTable, col } from "@rebasepro/server/schema";
export const invoices = defineTable("invoices", { columns: { id: col.uuid().primaryKey().defaultRandom(), number: col.integer().notNull().unique(), }, rls: "admin-only",});
// Several key columns form a composite key, in declaration order.export const dailyStats = defineTable("daily_stats", { columns: { siteId: col.uuid().primaryKey(), day: col.date().primaryKey(), views: col.integer().notNull().default(0), }, rls: "admin-only",});A key column is NOT NULL by definition. A uuid key usually takes
.defaultRandom(); an integer key takes .generatedByDefaultAsIdentity(). A key without a
default is supplied by the caller on create. A key column cannot be
.private(), and cannot be a timestamptz or time.
When a definition is refused
Section titled “When a definition is refused”A schema that would leave a table unprotected or unservable never reaches the database. It is refused at three points:
- In the editor.
rlsandcolumnsare required by the types, andrls: []is not a valid posture. AtenantorsoftDeletefield, or an index column written as a plain key, that names no column is a type error. - When the module loads.
defineTablethrows on a table with no columns, a column that is not acol.*builder, a relation that is not arel.*result, a relation with the same key as a column, or no usablerls. This also catches JavaScript code and casts that the types cannot see. - When the schema is compiled.
rebase db generate,rebase db push,rebase doctorand server boot compile every table together and stop with aSchemaDefinitionErrorthat lists every problem, each with the table, the column or relation, and what to write instead:
The schema cannot be used (2 problems): - posts: the table has no primary key. Mark a column `.primaryKey()` — e.g. `id: col.uuid().primaryKey().defaultRandom()`; several make a composite key in declaration order. - comments: `rls: "inherit"` takes the project's `defaultRls`, and none was given. Export `defaultRls` from backend/schema/index.ts (`"admin-only"` or a list of rules), or write this table's own `rls`.The compile step checks what needs every table at once: relation targets and
their key types, junction tables two relations both claim, slugs and SQL names
that collide (including names that collide once Postgres truncates them to 63
bytes), rules that name a column the table does not have, and "inherit"
without a defaultRls. A table exported from a file next to index.ts but not
from index.ts itself is refused too: the index is the list of tables.
Next steps
Section titled “Next steps”- Columns: every
col.*builder and modifier - JSON documents: typed and validated
jsonbwithjson.* - Relations: the five
rel.*kinds - Row-level security: the
rlsposture and its rules - Table hooks: server-side lifecycle hooks
- Type inference:
InferRow,InferInsertandInferUpdate