Zum Inhalt springen

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.ts
import { 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 zu NOT NULL und bei der Erstellung erforderlich. Siehe Spalten.
  • Der Fremdschlüssel wird durch die Relation deklariert. author leitet eine author_id-Spalte, deren Constraint und deren Index ab. Siehe Relationen.
  • rls ist erforderlich. Eine Tabelle ohne Row-Level-Security-Einstellung ist ein Typfehler und wird beim Kompilieren des Schemas abgelehnt. Siehe Row-Level-Security.
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.ts
import 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.

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(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.

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.

Ein Schema, das eine Tabelle ungeschützt oder nicht bereitstellbar hinterlassen würde, erreicht niemals die Datenbank. Es wird an drei Stellen abgelehnt:

  1. Im Editor. rls und columns sind typmäßig erforderlich, und rls: [] ist keine gültige Einstellung. Ein tenant- oder softDelete-Feld oder eine als einfacher Schlüssel geschriebene Index-Spalte, die keine Spalte benennt, ist ein Typfehler.
  2. Beim Laden des Moduls. defineTable wirft einen Fehler bei einer Tabelle ohne Spalten, einer Spalte, die kein col.*-Builder ist, einer Relation, die kein rel.*-Ergebnis ist, einer Relation mit demselben Schlüssel wie eine Spalte oder wenn kein verwendbares rls vorhanden ist. Dies fängt auch JavaScript-Code und Typumwandlungen (Casts) ab, die die Typen nicht erkennen können.
  3. Beim Kompilieren des Schemas. rebase db generate, rebase db push, rebase doctor und der Serverstart kompilieren alle Tabellen gemeinsam und brechen mit einem SchemaDefinitionError ab, 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.