Esquema
Tabelas
Uma tabela é declarada uma única vez, em TypeScript, no diretório backend/schema/.
Essa declaração é a única coisa que o backend sabe sobre os seus dados. A partir
dela, o Rebase gera a tabela e suas políticas de row-level security no Postgres,
disponibiliza a tabela via REST, realtime e MCP, e tipa o 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"] }, ],});Três coisas valem a pena notar neste exemplo antes de qualquer outra coisa:
- As colunas são anuláveis (nullable), a menos que você defina o contrário, como no SQL.
.notNull()torna a colunaNOT NULLe obrigatória na criação. Consulte Columns. - A chave estrangeira é declarada pela relação.
authorderiva uma colunaauthor_id, sua restrição e seu índice. Consulte Relations. rlsé obrigatório. Uma tabela sem uma postura de row-level security resulta em um erro de tipo e é recusada quando o schema é compilado. Consulte Row-level security.
O diretório backend/schema
Seção intitulada “O diretório backend/schema”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/Um arquivo por tabela é uma convenção, não uma regra. O que importa é
backend/schema/index.ts: o backend lê as tabelas e views que ele exporta,
e nada mais.
// 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 é opcional. Ele só é lido por tabelas que usam
rls: "inherit"; um projeto que nunca usa "inherit" não precisa dele.
O diretório é backend/schema, a menos que o rebase.json especifique outro com
a chave tables. A chave schema mantém seu significado anterior: o módulo Drizzle
gerado.
{ "apps": { "backend": { "type": "backend", "runtime": "managed", "tables": "backend/schema" } }}Um projeto sem backend/schema/index.ts não declara nenhuma tabela. O backend
então lê as tabelas do banco de dados ativo durante a inicialização e disponibiliza apenas
aquelas com row-level security habilitado. Consulte Backend only.
Os arquivos de schema são TypeScript puro, sem dependências de servidor:
@rebasepro/server/schema não carrega nada do servidor. Um frontend pode fazer
import type { posts } from "../../backend/schema/posts" para tipar seu próprio código
com base em uma tabela, sem incluir código de backend no bundle do navegador.
O que uma tabela se torna
Seção intitulada “O que uma tabela se torna”| A partir da declaração | O Rebase gera |
|---|---|
columns, relations, indexes |
o CREATE TABLE, chaves estrangeiras, tabelas de junção e índices, gravados em schema.sql por rebase db push e rebase db generate |
rls, tenant, a tabela de autenticação |
ENABLE ROW LEVEL SECURITY e um CREATE POLICY por regra e operação, em policies.sql |
search, colunas vetoriais |
a coluna tsvector gerada e os índices GIN e ANN |
| o slug | as rotas REST em /api/data/<slug>, subscrições em tempo real (realtime), as ferramentas MCP e o documento OpenAPI |
| os tipos e modificadores das colunas | os tipos Row, Insert e Update do SDK, e os tipos inferidos que você pode usar em seu próprio código |
Cada interface lê a mesma forma compilada da tabela, chamada de
descritor: colunas com seus tipos Postgres, nulabilidade, regras de validação
e armazenamento, relações resolvidas para slugs e a postura de row-level security.
O código de hooks nunca sai do servidor; o descritor apenas indica quais
hooks existem. O backend serve os descritores em GET /api/schema/tables,
que é o que o CMS, o Studio e os apps MCP utilizam para renderização.
O pipeline da declaração ao banco de dados está descrito em Schema as code.
Opções do defineTable
Seção intitulada “Opções do defineTable”defineTable(name, config) recebe o nome da tabela e as seguintes chaves:
| Chave | O que faz |
|---|---|
columns |
Obrigatório. Construtores col.* por chave, na ordem física. Pelo menos um deve ser .primaryKey(). Consulte Columns. |
rls |
Obrigatório. "admin-only", "inherit" ou uma lista não vazia de regras. Consulte Row-level security. |
relations |
Construtores rel.* por nome da relação. Consulte Relations. |
slug |
O nome na API, no SDK e nos escopos. Usa o nome da tabela quando omitido. |
table |
O nome da tabela SQL, quando for diferente do nome. |
schema |
O schema do Postgres. public quando omitido. |
database |
Um banco de dados Postgres não padrão, declarado em backend/resources.ts. Consulte Multiple sources. |
description |
O que a tabela armazena. Exibido no OpenAPI e nas descrições de ferramentas MCP. |
defaultPolicies |
false gera apenas as suas regras, sem as políticas de baseline de admin. Recusado com rls: "admin-only". true mantém a baseline quando o banco de dados da tabela a desativa para todas as tabelas (database({ rls: { defaultPolicies: false } })). Quando omitido, a configuração do banco de dados prevalece. |
rlsRequired |
false disponibiliza a tabela mesmo quando o banco de dados não impõe o seu rls (row-level security desativado, políticas declaradas ausentes), para casos em que outra ferramenta gerencia o schema e o próprio app aplica o controle de acesso. true o exige sob um banco de dados configurado com database({ rls: { required: false } }). Quando omitido, a configuração do banco de dados decide, e uma tabela não protegida pelo banco de dados não é disponibilizada em uma inicialização que não provisiona nada. Consulte Another tool owns the schema. |
tenant |
Restringe o escopo de cada linha a um tenant. Consulte Tenancy. |
softDelete |
true ou { field }: uma exclusão grava um timestamp em vez de remover a linha. Consulte Soft delete. |
history |
true registra cada escrita na tabela de histórico. Consulte Entity history. |
search |
Busca textual (full-text search) ranqueada nas colunas especificadas. Consulte Search. |
indexes |
Índices, cada um com a consulta que atende. Consulte Indexes. |
hooks |
Hooks de ciclo de vida no servidor. Consulte Table hooks. |
strictWrites |
Uma escrita que especifique uma coluna não declarada na tabela retorna 400. false aceita isso, para colunas que existem no banco de dados sem estarem declaradas (preenchidas por uma trigger, por exemplo). A coluna ainda deve existir. |
metadata |
Quaisquer dados que você queira disponibilizar junto ao descritor da tabela. O Rebase não faz a leitura desses dados. |
Mais duas definições compartilham a maior parte dessas chaves:
defineAuthTable para a tabela onde os usuários são armazenados
e defineView para views SQL.
O primeiro argumento de defineTable é o nome da tabela, e ele serve de padrão
para todo o restante:
| Nome | Padrão | Substituição |
|---|---|---|
| Tabela SQL | o nome | table: "blog_posts" |
| Slug da API, acessor do SDK, alvo de escopo | o nome | slug: "articles" |
| Schema do Postgres | public |
schema: "content" |
| Coluna SQL de uma coluna | o snake_case da sua chave | o primeiro argumento do construtor: col.text("legacy_name") |
A chave de uma coluna é o seu nome na linha JSON, no SDK e em filtros e
ordenações. Seu nome SQL é o snake_case da chave: publishDate é a coluna
publish_date, e photoURL é photo_url. O primeiro argumento de um construtor mapeia
uma chave para qualquer outro nome SQL, assim como no Drizzle (col.text("legacy_name")),
permitindo que uma tabela adote os nomes de um banco de dados existente sem alterar o que
os clientes veem.
table e schema devem ser identificadores SQL simples. Duas definições não podem
compartilhar um mesmo nome, slug ou tabela SQL. O slug é importante além da URL:
nomes de chaves estrangeiras e de colunas de junção são derivados dele, portanto alterar o
slug de uma tabela já implantada pode renomear colunas. Defina slug explicitamente
quando ele precisar ser diferente do nome da tabela e não o altere depois.
Chaves primárias
Seção intitulada “Chaves primárias”Não existe uma coluna id implícita. Toda tabela deve marcar pelo menos uma coluna
com .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",});Uma coluna de chave é NOT NULL por definição. Uma chave uuid normalmente usa
.defaultRandom(); uma chave inteira usa .generatedByDefaultAsIdentity(). Uma chave sem
valor padrão deve ser fornecida pelo cliente na criação. Uma coluna de chave não pode ser
.private() e não pode ser timestamptz ou time.
Quando uma definição é recusada
Seção intitulada “Quando uma definição é recusada”Um schema que deixaria uma tabela desprotegida ou indisponível nunca chega ao banco de dados. Ele é recusado em três momentos:
- No editor.
rlsecolumnssão exigidos pelos tipos, erls: []não é uma postura válida. Um campotenantousoftDelete, ou uma coluna de índice escrita como uma chave simples que não aponte para nenhuma coluna, resulta em erro de tipo. - Quando o módulo é carregado.
defineTablelança um erro para tabelas sem colunas, uma coluna que não seja um construtorcol.*, uma relação que não seja o resultado derel.*, uma relação com a mesma chave de uma coluna ou nenhumrlsutilizável. Isso também detecta códigos JavaScript e casts que os tipos não conseguem verificar. - Quando o schema é compilado.
rebase db generate,rebase db push,rebase doctore a inicialização do servidor compilam todas as tabelas juntas e são interrompidos com umSchemaDefinitionErrorque lista cada problema, identificando a tabela, a coluna ou relação, e o que deve ser escrito no lugar:
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`.A etapa de compilação verifica o que requer a análise de todas as tabelas simultaneamente:
alvos de relações e seus tipos de chave, tabelas de junção reivindicadas por duas relações ao mesmo
tempo, slugs e nomes SQL que colidem (incluindo nomes que colidem quando o Postgres os trunca para 63
bytes), regras que referenciam colunas inexistentes na tabela e "inherit"
sem um defaultRls. Uma tabela exportada de um arquivo ao lado de index.ts, mas não
do próprio index.ts, também é recusada: o arquivo index é a lista oficial de tabelas.
Próximos passos
Seção intitulada “Próximos passos”- Columns: todos os construtores e modificadores
col.* - JSON documents:
jsonbtipado e validado comjson.* - Relations: os cinco tipos de
rel.* - Row-level security: a postura de
rlse suas regras - Table hooks: hooks de ciclo de vida no servidor
- Type inference:
InferRow,InferInserteInferUpdate