Esquema
Tablas
Una tabla se declara una sola vez, en TypeScript, en el directorio backend/schema/.
Esa declaración es lo único que el backend sabe sobre tus datos. A partir de ella,
Rebase genera la tabla y sus políticas de seguridad a nivel de fila en Postgres,
sirve la tabla a través de REST, realtime y MCP, y genera los tipos para el 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"] }, ],});Hay tres cosas que vale la pena notar de este ejemplo antes que cualquier otra:
- Las columnas aceptan valores nulos a menos que indiques lo contrario, como en SQL.
.notNull()hace que una columna seaNOT NULLy obligatoria al crearla. Consulta Columnas. - La clave foránea se declara mediante la relación.
authorderiva una columnaauthor_id, su restricción y su índice. Consulta Relaciones. rlses obligatorio. Una tabla sin una postura de seguridad a nivel de fila es un error de tipo, y se rechaza cuando se compila el esquema. Consulta Seguridad a nivel de fila.
El directorio backend/schema
Sección titulada «El directorio 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/Un archivo por tabla es una convención, no una regla. Lo que cuenta es
backend/schema/index.ts: el backend lee las tablas y vistas que exporta,
y nada más.
// 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 es opcional. Solo lo leen las tablas que indican
rls: "inherit"; un proyecto que nunca escribe "inherit" no lo necesita.
El directorio es backend/schema a menos que rebase.json especifique otro mediante
la clave tables. La clave schema mantiene su significado anterior: el módulo
Drizzle generado.
{ "apps": { "backend": { "type": "backend", "runtime": "managed", "tables": "backend/schema" } }}Un proyecto sin backend/schema/index.ts no declara ninguna tabla. El backend
entonces lee las tablas de la base de datos activa al arrancar, y solo sirve aquellas
que tengan habilitada la seguridad a nivel de fila. Consulta Solo backend.
Los archivos de esquema son TypeScript puro sin dependencias del servidor:
@rebasepro/server/schema no carga nada del servidor. Un frontend puede hacer
import type { posts } from "../../backend/schema/posts" para tipar su propio código
contra una tabla, sin incluir código del backend en el bundle del navegador.
En qué se convierte una tabla
Sección titulada «En qué se convierte una tabla»| A partir de la declaración | Rebase genera |
|---|---|
columns, relations, indexes |
el CREATE TABLE, claves foráneas, tablas de unión e índices, escritos en schema.sql mediante rebase db push y rebase db generate |
rls, tenant, la tabla de autenticación |
ENABLE ROW LEVEL SECURITY y un CREATE POLICY por regla y operación, en policies.sql |
search, columnas vectoriales |
la columna tsvector generada y los índices GIN y ANN |
| el slug | las rutas REST bajo /api/data/<slug>, suscripciones realtime, las herramientas MCP y el documento OpenAPI |
| los tipos y modificadores de las columnas | los tipos Row, Insert y Update del SDK, y los tipos inferidos que puedes usar en tu propio código |
Cada interfaz lee la misma forma compilada de la tabla, llamada su
descriptor: columnas con sus tipos de Postgres, nulabilidad, reglas de validación y
almacenamiento, relaciones resueltas a slugs y la postura de seguridad
a nivel de fila. El código de los hooks nunca sale del servidor; el descriptor solo indica qué
hooks existen. El backend sirve los descriptores en GET /api/schema/tables,
que es a partir de lo cual renderizan el CMS, el Studio y las aplicaciones MCP.
El flujo desde la declaración hasta la base de datos se describe en Esquema como código.
Opciones de defineTable
Sección titulada «Opciones de defineTable»defineTable(name, config) toma el nombre de la tabla y estas claves:
| Clave | Qué hace |
|---|---|
columns |
Obligatorio. Constructores col.* por clave, en orden físico. Al menos uno debe ser .primaryKey(). Consulta Columnas. |
rls |
Obligatorio. "admin-only", "inherit", o una lista no vacía de reglas. Consulta Seguridad a nivel de fila. |
relations |
Constructores rel.* por nombre de relación. Consulta Relaciones. |
slug |
El nombre en la API, el SDK y en los scopes. Es el nombre de la tabla si se omite. |
table |
El nombre de la tabla SQL, cuando difiere del nombre. |
schema |
El esquema de Postgres. public si se omite. |
database |
Una base de datos Postgres no predeterminada, declarada en backend/resources.ts. Consulta Múltiples orígenes. |
description |
Lo que contiene la tabla. Se muestra en OpenAPI y en las descripciones de herramientas MCP. |
defaultPolicies |
false genera solo tus reglas, sin las políticas base de administrador. Rechazado con rls: "admin-only". true mantiene la base cuando la base de datos de la tabla la desactiva para todas las tablas (database({ rls: { defaultPolicies: false } })). Si se omite, la configuración de la base de datos decide. |
rlsRequired |
false sirve la tabla incluso cuando la base de datos no aplica su rls (seguridad a nivel de fila desactivada, políticas declaradas faltantes), para un esquema propiedad de otra herramienta y una aplicación que aplica el acceso por sí misma. true lo requiere bajo una base de datos que especifica database({ rls: { required: false } }). Si se omite, la configuración de la base de datos decide, y una tabla que la base de datos no protege no se sirve en un arranque que no aprovisiona nada. Consulta Otra herramienta es propietaria del esquema. |
tenant |
Delimita cada fila a un tenant. Consulta Tenencia. |
softDelete |
true o { field }: un borrado estampa una marca de tiempo en lugar de eliminar la fila. Consulta Borrado suave. |
history |
true registra cada escritura en la tabla de historial. Consulta Historial de entidades. |
search |
Búsqueda de texto completo clasificada sobre las columnas indicadas. Consulta Búsqueda. |
indexes |
Índices, cada uno con la consulta a la que sirve. Consulta Índices. |
hooks |
Hooks de ciclo de vida del lado del servidor. Consulta Hooks de tabla. |
strictWrites |
Una escritura que nombra una columna que la tabla no declara devuelve un 400. false la acepta, para una columna que existe en la base de datos sin estar declarada (llenada por un disparador, por ejemplo). La columna aún debe existir. |
metadata |
Cualquier dato que desees que se sirva con el descriptor de la tabla. Rebase no lo lee. |
Otras dos definiciones comparten la mayoría de estas claves:
defineAuthTable para la tabla donde se almacenan
los usuarios, y defineView para vistas SQL.
Nombres
Sección titulada «Nombres»El primer argumento de defineTable es el nombre de la tabla, y es el valor predeterminado
para todo lo demás:
| Nombre | Predeterminado | Anulación |
|---|---|---|
| Tabla SQL | el nombre | table: "blog_posts" |
| Slug de API, descriptor de acceso SDK, objetivo de scope | el nombre | slug: "articles" |
| Esquema de Postgres | public |
schema: "content" |
| Columna SQL de una columna | el snake_case de su clave | el primer argumento del constructor: col.text("legacy_name") |
La clave de una columna es su nombre en la fila JSON, en el SDK y en los filtros y
ordenaciones. Su nombre en SQL es el snake_case de la clave: publishDate es la columna
publish_date, y photoURL es photo_url. El primer argumento de un constructor mapea
una clave a cualquier otro nombre SQL, como en Drizzle (col.text("legacy_name")), que
es cómo una tabla adopta los nombres de una base de datos existente sin cambiar lo que
ven los clientes.
table y schema deben ser identificadores SQL válidos. Dos definiciones no pueden
compartir un nombre, un slug o una tabla SQL. El slug importa más allá de la URL: los nombres
de las claves foráneas y de las columnas de unión se derivan de él, por lo que cambiar el slug
de una tabla que ya está desplegada puede renombrar columnas. Establece slug explícitamente cuando
deba diferir del nombre de la tabla y no lo modifiques después.
Claves primarias
Sección titulada «Claves primarias»No hay una columna id implícita. Cada tabla marca al menos una columna
como .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",});Una columna clave es NOT NULL por definición. Una clave uuid generalmente toma
.defaultRandom(); una clave de entero toma .generatedByDefaultAsIdentity(). Una clave sin un
valor predeterminado la proporciona quien realiza la llamada al momento de la creación. Una columna clave no puede ser
.private(), y no puede ser un timestamptz o time.
Cuándo se rechaza una definición
Sección titulada «Cuándo se rechaza una definición»Un esquema que dejaría una tabla desprotegida o inservible nunca llega a la base de datos. Se rechaza en tres puntos:
- En el editor.
rlsycolumnsson requeridos por los tipos, yrls: []no es una postura válida. Un campo detenantosoftDelete, o una columna de índice escrita como una clave simple, que no nombre ninguna columna es un error de tipo. - Al cargar el módulo.
defineTablearroja un error en una tabla sin columnas, una columna que no sea un constructorcol.*, una relación que no sea el resultado derel.*, una relación con la misma clave que una columna o unrlsno utilizable. Esto también detecta código JavaScript y conversiones de tipo que los tipos no pueden ver. - Al compilar el esquema.
rebase db generate,rebase db push,rebase doctory el arranque del servidor compilan todas las tablas juntas y se detienen con unSchemaDefinitionErrorque enumera cada problema, cada uno con la tabla, la columna o relación, y qué escribir en su 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`.El paso de compilación verifica lo que necesita evaluar todas las tablas a la vez: los destinos de las relaciones y
sus tipos de clave, tablas de unión que ambas relaciones reclaman, slugs y nombres SQL
que colisionan (incluidos los nombres que colisionan una vez que Postgres los trunca a 63
bytes), reglas que nombran una columna que la tabla no tiene, e "inherit"
sin un defaultRls. Una tabla exportada desde un archivo junto a index.ts pero no
desde el propio index.ts también se rechaza: el índice es la lista de tablas.
Próximos pasos
Sección titulada «Próximos pasos»- Columnas: cada constructor y modificador
col.* - Documentos JSON:
jsonbtipado y validado conjson.* - Relaciones: los cinco tipos de
rel.* - Seguridad a nivel de fila: la postura de
rlsy sus reglas - Hooks de tabla: hooks de ciclo de vida del lado del servidor
- Inferencia de tipos:
InferRow,InferInserteInferUpdate