Schema-Generierung

Überblick

Rebase verwendet eine Schema-as-Code-Pipeline, bei der Ihre TypeScript-Collection-Definitionen die einzige Quelle der Wahrheit sind. Die CLI transformiert sie durch eine deterministische Pipeline:

Collections (TypeScript) → Drizzle Schema → SQL Migrations → PostgreSQL

Diese Seite behandelt jeden CLI-Befehl, der an dieser Pipeline beteiligt ist.

Die Pipeline

1. Collections → Drizzle-Schema

Ihre Collection-Definitionen in config/collections/ beschreiben Tabellen, Spalten, Typen, Relationen und Enums. Der Befehl schema generate liest diese und gibt eine Drizzle-ORM-Schemadatei aus.

2. Drizzle-Schema → Migrationen

Aus dem generierten Drizzle-Schema vergleicht db generate mit dem aktuellen Datenbankzustand und erzeugt zeitgestempelte SQL-Migrationsdateien.

3. Migrationen → PostgreSQL

Der Befehl db migrate wendet ausstehende Migrationen auf Ihre PostgreSQL-Datenbank an.

Befehle

rebase schema generate

Generieren Sie eine Drizzle-ORM-Schemadatei aus Ihren Collection-Definitionen:

rebase schema generate

Was er tut:

• Liest alle Collections aus config/collections/
• Generiert backend/src/schema.generated.ts mit Drizzle-Tabellendefinitionen, Enums und Relationen

Optionen:

Flag	Beschreibung
--collections, -c	Pfad zum Collections-Verzeichnis (Standard: config/collections/)
--output, -o	Ausgabepfad für die generierte Schemadatei
--watch, -w	Auf Änderungen achten und automatisch neu generieren

Der Watch-Modus ist während der Entwicklung nützlich — bearbeiten Sie eine Collection-Datei und das Schema wird sofort neu generiert:

rebase schema generate --watch

rebase schema introspect

Rekonstruieren Sie Collection-Definitionen aus einer bestehenden PostgreSQL-Datenbank:

rebase schema introspect

Was er tut:

• Verbindet sich mit Ihrer Datenbank (mit der Verbindungszeichenfolge aus Ihrer .env)
• Inspiziert alle Tabellen, Spalten, Typen und Fremdschlüssel
• Generiert Collection-Definitionsdateien

Optionen:

Flag	Beschreibung
--output, -o	Ausgabeverzeichnis für die generierten Collection-Dateien

Dies ist nützlich, wenn Sie Rebase auf einer bestehenden Datenbank einführen — zuerst introspizieren, dann die generierten Collections anpassen.

rebase db push

Übertragen Sie Schemaänderungen direkt in die Datenbank ohne Migrationsdateien:

rebase db push

Was er tut:

• Liest das generierte Drizzle-Schema
• Wendet Änderungen direkt auf die Datenbank an (CREATE, ALTER, DROP)
• Erstellt keine Migrationsdateien

Achtung

db push modifiziert die Datenbank direkt. Verwenden Sie es nur in der Entwicklung. Für die Produktion verwenden Sie db generate + db migrate, um überprüfbare Migrationsdateien zu erstellen.

rebase db generate

Generieren Sie SQL-Migrationsdateien aus Schemaänderungen:

rebase db generate

Was er tut:

• Vergleicht das Drizzle-Schema mit dem aktuellen Datenbankzustand
• Erzeugt zeitgestempelte SQL-Migrationsdateien im drizzle/-Verzeichnis
• Dateien können überprüft, bearbeitet und in die Versionskontrolle committet werden

Die generierten Migrationen sind einfache SQL-Dateien — Sie können sie vor dem Anwenden inspizieren und ändern.

rebase db migrate

Führen Sie alle ausstehenden Migrationen aus:

rebase db migrate

Was er tut:

• Liest das drizzle/-Verzeichnis nach nicht angewendeten Migrationen
• Wendet sie der Reihe nach auf die Datenbank an
• Verfolgt, welche Migrationen angewendet wurden

Baseline für eine Datenbank, gegen die Rebase bereits gebootet hat

Jeder Rebase-Start stellt das Schema sicher, und rebase db push wendet es direkt an. Eine Datenbank, gegen die je eines von beiden gelaufen ist, hat die Tabellen und Typen also bereits, die die erste Migration anlegen würde — und rebase db migrate bricht mit pq: type "posts_status" already exists (42710) ab.

An der Migration ist nichts falsch: Die Datenbank wurde auf einem anderen Weg bereitgestellt. Halten Sie fest, wo sie bereits steht, und migrieren Sie dann normal:

rebase db migrate --baseline 20260906101530
rebase db migrate

Die Version ist das Zahlenpräfix der Migrationsdatei, die den aktuellen Stand der Datenbank beschreibt. Diese Migration und alle davor gelten als angewendet; alles danach läuft. Gegen eine Datenbank, gegen die nie gebootet wurde, braucht es keine Baseline — migrieren Sie einfach direkt.

rebase db branch

Datenbank-Branching für parallele Entwicklung:

rebase db branch create feature_auth
rebase db branch list
rebase db branch delete feature_auth

rebase doctor

Erkennen Sie Drei-Wege-Drift zwischen Ihren Collection-Definitionen, dem generierten Drizzle-Schema und der laufenden PostgreSQL-Datenbank:

rebase doctor

Was er prüft:

• Collections ↔ Generiertes Schema — sind sie synchron?
• Generiertes Schema ↔ Datenbank — gibt es nicht angewendete Änderungen?
• Collections ↔ Datenbank — gibt es unerwarteten Drift?

Führen Sie doctor aus, wann immer sich etwas nicht synchron anfühlt. Es zeigt genau, wo die Diskrepanz liegt.

rebase generate-sdk

Generieren Sie ein typisiertes Client-SDK aus Ihren Collection-Definitionen:

rebase generate-sdk

Was er tut:

• Liest Collections aus config/collections/ (unterstützt index.ts-Barrel-Exports oder einzelne Dateien)
• Generiert TypeScript-Typen für alle Entitäten in generated/sdk/
• Erzeugt eine database.types.ts-Datei zur Verwendung mit createRebaseClient<Database>()

Optionen:

Flag	Beschreibung
-c, --collections-dir	Pfad zum Collections-Verzeichnis (Standard: config/collections/)
-o, --output	Ausgabeverzeichnis für das SDK (Standard: generated/sdk/)
--from <link|url>	Liest das Schema von einem laufenden Projekt statt aus lokalem Quellcode. link verwendet das verknüpfte Projekt dieses Checkouts.
--token	Bearer-Token für den Contract-Endpunkt (Standard: $REBASE_SERVICE_KEY)

Mit --from kann ein Repository ohne eigene Collections — ein separates Frontend, eine zweite Web-App, eine Mobile-App — einen typisierten Client für das Projekt generieren, mit dem es spricht. REBASE_SERVICE_KEY wird nur an das Projekt gesendet, mit dem dieses Checkout verknüpft ist; für jeden anderen Host ist --token explizit anzugeben.

Verwendung nach der Generierung:

import { createRebaseClient } from "@rebasepro/client";
import { collectionsDictionary, type Database } from "./generated/sdk/database.types";

const client = createRebaseClient<Database>({
    baseUrl: import.meta.env.VITE_API_URL,
    collections: collectionsDictionary,
});

// Full type safety and autocomplete
const { data } = await client.data.products.find();

Feldnamen in den generierten Typen sind unverändert die, die die API liefert — eine Spalte createdAt ist row.createdAt. Nur der Collection-Accessor wird in einen Property-Namen umgewandelt (my-notes → client.data.myNotes); genau diese Zuordnung stellt collectionsDictionary auf den Slug zurück.

Entwicklungs-Workflow

Der Workflow für schnelle Iteration in der Entwicklung:

# 1. Edit your collection in config/collections/
# 2. Generate the Drizzle schema
rebase schema generate

# 3. Push directly to dev database
rebase db push

Produktions-Workflow

Der sichere, überprüfbare Workflow für die Produktion:

# 1. Edit your collection in config/collections/
# 2. Generate the Drizzle schema
rebase schema generate

# 3. Generate SQL migration files
rebase db generate

# 4. Review the generated SQL in drizzle/
# 5. Commit the migration to version control
git add drizzle/

# 6. Apply in production
#    A database Rebase has already booted needs a baseline the first time —
#    see the baselining section above.
rebase db migrate

Fehlerbehebung

Symptom	Lösung
Could not detect an active database plugin	Installieren Sie @rebasepro/server-postgres in backend/package.json
Schemadatei wird nicht aktualisiert	Prüfen Sie, ob der --collections-Pfad auf das richtige Verzeichnis zeigt
Migration zeigt unerwartete Änderungen	Führen Sie rebase doctor aus, um den Drift zu identifizieren
db push schlägt in der Produktion fehl	Verwenden Sie stattdessen db generate + db migrate
db migrate scheitert mit already exists (42710)	Start oder db push haben das Schema bereits bereitgestellt — halten Sie es mit rebase db migrate --baseline <version> fest

Nächste Schritte

• Collections — Definieren Sie Ihr Datenmodell
• CLI-Referenz — Alle CLI-Befehle
• Client-SDK — Verwenden Sie das generierte SDK