Schema
Tabellen
Eine Tabelle wird einmalig in TypeScript im Verzeichnis backend/schema/ deklariert.
Diese Deklaration ist das Einzige, was das Backend über Ihre Daten weiß. Daraus
generiert Rebase die Tabelle und ihre Row-Level-Security-Policies in Postgres,
stellt die Tabelle über REST, Realtime und MCP bereit und typisiert das 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"] }, ],});Drei Dinge sind an diesem Beispiel vor allem bemerkenswert:
- Spalten sind nullable, sofern nicht anders angegeben, wie in SQL.
.notNull()macht eine Spalte zuNOT NULLund bei der Erstellung erforderlich. Siehe Spalten. - Der Fremdschlüssel wird durch die Relation deklariert.
authorleitet eineauthor_id-Spalte, deren Constraint und deren Index ab. Siehe Relationen. rlsist erforderlich. Eine Tabelle ohne Row-Level-Security-Einstellung ist ein Typfehler und wird beim Kompilieren des Schemas abgelehnt. Siehe Row-Level-Security.
Das Verzeichnis backend/schema
Abschnitt betitelt „Das Verzeichnis 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/Eine Datei pro Tabelle ist eine Konvention, keine Regel. Entscheidend ist
backend/schema/index.ts: Das Backend liest die Tabellen und Views, die darin
exportiert werden, und sonst nichts.
// 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 ist optional. Es wird nur von Tabellen gelesen, die
rls: "inherit" angeben; ein Projekt, das niemals "inherit" verwendet,
benötigt es nicht.
Das Verzeichnis ist backend/schema, es sei denn, rebase.json gibt über den
Schlüssel tables ein anderes an. Der Schlüssel schema behält seine bisherige
Bedeutung: das generierte Drizzle-Modul.
{ "apps": { "backend": { "type": "backend", "runtime": "managed", "tables": "backend/schema" } }}Ein Projekt ohne backend/schema/index.ts deklariert keine Tabellen. Das Backend
liest die Tabellen dann beim Start aus der Live-Datenbank aus und stellt nur diejenigen
bereit, für die Row-Level-Security aktiviert ist. Siehe Nur Backend.
Die Schema-Dateien sind reines TypeScript ohne Server-Abhängigkeiten:
@rebasepro/server/schema lädt nichts vom Server. Ein Frontend kann
import type { posts } from "../../backend/schema/posts" verwenden, um seinen
eigenen Code anhand einer Tabelle zu typisieren, ohne Backend-Code in das
Browser-Bundle zu ziehen.
Was aus einer Tabelle wird
Abschnitt betitelt „Was aus einer Tabelle wird“| Aus der Deklaration | Rebase generiert |
|---|---|
columns, relations, indexes |
das CREATE TABLE, Fremdschlüssel, Junction-Tabellen und Indizes, geschrieben in schema.sql durch rebase db push und rebase db generate |
rls, tenant, die Auth-Tabelle |
ENABLE ROW LEVEL SECURITY und ein CREATE POLICY pro Regel und Operation in policies.sql |
search, Vektorspalten |
die generierte tsvector-Spalte sowie die GIN- und ANN-Indizes |
| den Slug | die REST-Routen unter /api/data/<slug>, Realtime-Abonnements, die MCP-Tools und das OpenAPI-Dokument |
| die Typen und Modifikatoren der Spalten | die Typen Row, Insert und Update des SDKs sowie die abgeleiteten Typen, die Sie in Ihrem eigenen Code verwenden können |
Jede Oberfläche liest dieselbe kompilierte Form der Tabelle, ihren sogenannten
Deskriptor: Spalten mit ihren Postgres-Typen, Nullability, Validierungs- und
Speicherregeln, zu Slugs aufgelöste Relationen und die Row-Level-Security-Einstellung.
Hook-Code verlässt niemals den Server; der Deskriptor gibt lediglich an, welche
Hooks existieren. Das Backend stellt die Deskriptoren unter GET /api/schema/tables
bereit, woraus das CMS, das Studio und die MCP-Apps rendern.
Die Pipeline von der Deklaration bis zur Datenbank wird in Schema as Code beschrieben.
defineTable-Optionen
Abschnitt betitelt „defineTable-Optionen“defineTable(name, config) akzeptiert den Namen der Tabelle und folgende Schlüssel:
| Schlüssel | Funktion |
|---|---|
columns |
Erforderlich. col.*-Builder nach Schlüssel in physischer Reihenfolge. Mindestens einer muss .primaryKey() sein. Siehe Spalten. |
rls |
Erforderlich. "admin-only", "inherit" oder eine nicht-leere Liste von Regeln. Siehe Row-Level-Security. |
relations |
rel.*-Builder nach Relationsname. Siehe Relationen. |
slug |
Der Name in der API, im SDK und in Scopes. Entspricht dem Namen der Tabelle, wenn weggelassen. |
table |
Der SQL-Tabellenname, falls er vom Namen abweicht. |
schema |
Das Postgres-Schema. public, wenn weggelassen. |
database |
Eine Nicht-Standard-Postgres-Datenbank, deklariert in backend/resources.ts. Siehe Mehrere Quellen. |
description |
Was die Tabelle enthält. Wird in OpenAPI und in den MCP-Tool-Beschreibungen angezeigt. |
defaultPolicies |
false generiert nur Ihre Regeln ohne die Admin-Baseline-Policies. Bei rls: "admin-only" abgelehnt. true behält die Baseline bei, wenn die Datenbank der Tabelle sie für alle Tabellen deaktiviert (database({ rls: { defaultPolicies: false } })). Weggelassen entscheidet die Einstellung der Datenbank. |
rlsRequired |
false stellt die Tabelle auch dann bereit, wenn die Datenbank deren rls nicht erzwingt (Row-Level-Security deaktiviert, deklarierte Policies fehlen) – nützlich für ein Schema, das einem anderen Tool gehört und eine App, die den Zugriff selbst erzwingt. true erfordert dies bei einer Datenbank mit database({ rls: { required: false } }). Weggelassen entscheidet die Einstellung der Datenbank, und eine von der Datenbank nicht geschützte Tabelle wird bei einem Start, der nichts provisioniert, nicht bereitgestellt. Siehe Ein anderes Tool besitzt das Schema. |
tenant |
Ordnet jede Zeile einem Mandanten (Tenant) zu. Siehe Mandantenfähigkeit. |
softDelete |
true oder { field }: Ein Löschvorgang setzt einen Zeitstempel, anstatt die Zeile zu entfernen. Siehe Soft Delete. |
history |
true zeichnet jeden Schreibvorgang in der History-Tabelle auf. Siehe Entitätshistorie. |
search |
Bewertete Volltextsuche über die angegebenen Spalten. Siehe Suche. |
indexes |
Indizes, jeweils mit der Abfrage, die sie bedienen. Siehe Indizes. |
hooks |
Serverseitige Lifecycle-Hooks. Siehe Tabellen-Hooks. |
strictWrites |
Ein Schreibvorgang, der eine Spalte benennt, die die Tabelle nicht deklariert, führt zu einem 400-Fehler. false akzeptiert dies für eine Spalte, die in der Datenbank existiert, ohne deklariert zu sein (z. B. durch einen Trigger befüllt). Die Spalte muss dennoch existieren. |
metadata |
Beliebige Daten, die mit dem Deskriptor der Tabelle bereitgestellt werden sollen. Rebase liest diese nicht aus. |
Zwei weitere Definitionen teilen die meisten dieser Schlüssel:
defineAuthTable für die Tabelle, in der Benutzer
gespeichert werden, und defineView für SQL-Views.
Das erste Argument von defineTable ist der Name der Tabelle und dient als
Standard für alles andere:
| Name | Standardwert | Überschreibung |
|---|---|---|
| SQL-Tabelle | der Name | table: "blog_posts" |
| API-Slug, SDK-Accessor, Scope-Ziel | der Name | slug: "articles" |
| Postgres-Schema | public |
schema: "content" |
| SQL-Spalte einer Spalte | snake_case ihres Schlüssels | erstes Argument des Builders: col.text("legacy_name") |
Der Schlüssel einer Spalte ist ihr Name in der JSON-Zeile, im SDK sowie in Filtern
und Sortierungen. Ihr SQL-Name ist die snake_case-Variante des Schlüssels:
publishDate ist die Spalte publish_date, und photoURL ist photo_url. Das
erste Argument eines Builders weist einem Schlüssel einen beliebigen anderen SQL-Namen
zu, wie in Drizzle (col.text("legacy_name")), wodurch eine Tabelle die Namen einer
bestehenden Datenbank übernehmen kann, ohne das zu ändern, was Clients sehen.
table und schema müssen einfache SQL-Identifier sein. Zwei Definitionen dürfen
sich keinen Namen, Slug oder eine SQL-Tabelle teilen. Der Slug ist über die URL
hinaus wichtig: Fremdschlüssel- und Junction-Spaltennamen werden daraus abgeleitet,
sodass das Ändern des Slugs einer bereits bereitgestellten Tabelle Spalten umbenennen
kann. Setzen Sie slug explizit, wenn er vom Namen der Tabelle abweichen soll, und
ändern Sie ihn danach nicht mehr.
Primärschlüssel
Abschnitt betitelt „Primärschlüssel“Es gibt keine implizite id-Spalte. Jede Tabelle markiert mindestens eine Spalte
mit .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",});Eine Schlüsselspalte ist per Definition NOT NULL. Ein uuid-Schlüssel verwendet
üblicherweise .defaultRandom(); ein Integer-Schlüssel verwendet
.generatedByDefaultAsIdentity(). Ein Schlüssel ohne Standardwert wird vom
Aufrufer bei der Erstellung übergeben. Eine Schlüsselspalte kann nicht .private()
und weder ein timestamptz noch ein time sein.
Wann eine Definition abgelehnt wird
Abschnitt betitelt „Wann eine Definition abgelehnt wird“Ein Schema, das eine Tabelle ungeschützt oder nicht bereitstellbar hinterlassen würde, erreicht niemals die Datenbank. Es wird an drei Stellen abgelehnt:
- Im Editor.
rlsundcolumnssind typmäßig erforderlich, undrls: []ist keine gültige Einstellung. Eintenant- odersoftDelete-Feld oder eine als einfacher Schlüssel geschriebene Index-Spalte, die keine Spalte benennt, ist ein Typfehler. - Beim Laden des Moduls.
defineTablewirft einen Fehler bei einer Tabelle ohne Spalten, einer Spalte, die keincol.*-Builder ist, einer Relation, die keinrel.*-Ergebnis ist, einer Relation mit demselben Schlüssel wie eine Spalte oder wenn kein verwendbaresrlsvorhanden ist. Dies fängt auch JavaScript-Code und Typumwandlungen (Casts) ab, die die Typen nicht erkennen können. - Beim Kompilieren des Schemas.
rebase db generate,rebase db push,rebase doctorund der Serverstart kompilieren alle Tabellen gemeinsam und brechen mit einemSchemaDefinitionErrorab, der jedes Problem auflistet – jeweils mit Angabe der Tabelle, der Spalte oder Relation und was stattdessen angegeben werden sollte:
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`.Der Kompilierungsschritt prüft alles, wofür alle Tabellen gleichzeitig benötigt
werden: Relationsziele und deren Schlüsseltypen, Junction-Tabellen, die von zwei
Relationen beansprucht werden, Slugs und SQL-Namen, die kollidieren (einschließlich
Namen, die kollidieren, sobald Postgres sie auf 63 Bytes kürzt), Regeln, die eine
Spalte benennen, die die Tabelle nicht besitzt, und "inherit" ohne defaultRls.
Eine Tabelle, die aus einer Datei neben index.ts, aber nicht aus index.ts
selbst exportiert wird, wird ebenfalls abgelehnt: Der Index ist die Liste der Tabellen.
Nächste Schritte
Abschnitt betitelt „Nächste Schritte“- Spalten: Jeder
col.*-Builder und -Modifikator - JSON-Dokumente: Typisiertes und validiertes
jsonbmitjson.* - Relationen: Die fünf
rel.*-Arten - Row-Level-Security: Die
rls-Einstellung und ihre Regeln - Tabellen-Hooks: Serverseitige Lifecycle-Hooks
- Typinferenz:
InferRow,InferInsertundInferUpdate