Migrationen

Motoko Base nutzt Drizzle Kit, um Datenbank-Migrationen zu verwalten. Das Schema ist in TypeScript definiert (src/lib/db/schema/); Drizzle erzeugt SQL-Migrationsdateien und wendet sie auf deine Postgres-Datenbank an.

Alle drei Befehle sind in package.json definiert:

"db:generate": "drizzle-kit generate",
"db:migrate": "drizzle-kit migrate",
"db:studio": "drizzle-kit studio"

Die Konfiguration liegt in drizzle.config.ts:

export default defineConfig({
  schema: "./src/lib/db/schema/schema.ts",
  out: "./drizzle/migrations",
  dialect: "postgresql",
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});

DATABASE_URL muss in .env gesetzt sein, bevor du einen Befehl ausführst. Bei Supabase nutze die Direct Connection (Port 5432), wenn Migrationen über den Transaction-Pooler scheitern.

pnpm db:generate

Erzeugt eine neue Migrationsdatei aus den Unterschieden zwischen deinem TypeScript-Schema und dem letzten Migrations-Snapshot.

When to use

• Nach dem Hinzufügen oder Bearbeiten einer Tabelle in src/lib/db/schema/
• Nach dem Hinzufügen von Spalten, Indizes, Fremdschlüsseln oder Constraints
• Nach dem Exportieren einer neuen Schema-Datei aus schema.ts

When not to use

• Zum Anwenden von Migrationen — nutze stattdessen db:migrate
• Zum Durchsuchen von Daten — nutze stattdessen db:studio
• Bei einem frischen Clone ohne Schema-Änderungen — es gibt nichts Neues zu erzeugen

What it does

1. Liest src/lib/db/schema/schema.ts und alle exportierten Tabellen
2. Vergleicht mit dem neuesten Snapshot in drizzle/migrations/
3. Erstellt einen neuen Ordner unter drizzle/migrations/ mit:
   • migration.sql — dem auszuführenden SQL
   • snapshot.json — Schema-Zustand für den nächsten Diff

Example

Du hast eine Tabelle notes zum Schema hinzugefügt:

pnpm db:generate

Ausgabe (Beispiel):

drizzle/migrations/20260824120000_some_name/migration.sql

Prüfe das erzeugte SQL vor dem Migrieren. Drizzle Kit ist für die meisten Änderungen korrekt, aber prüfe destruktive Operationen (drops, renames) immer.

pnpm db:migrate

Wendet ausstehende Migrationen auf die über DATABASE_URL verbundene Datenbank an.

When to use

• Nach pnpm db:generate — um deine neue Migration anzuwenden
• Nach dem Pull aus Git, wenn ein Teammitglied (oder Upstream) Migrationen hinzugefügt hat
• Auf einer frischen Datenbank — um alle Tabellen von Grund auf zu erstellen
• Beim lokalen Setup — direkt nach dem Klonen (siehe Installation)

When not to use

• Wenn du das Schema geändert, aber noch kein db:generate ausgeführt hast — zuerst generieren
• Zum Prüfen von Daten — nutze db:studio

What it does

1. Verbindet sich mit Postgres über DATABASE_URL
2. Führt Migrations-SQL aus, das noch nicht im Migrations-Journal der Datenbank steht
3. Aktualisiert das Journal, damit dieselbe Migration nicht zweimal angewendet wird

Example

pnpm db:migrate

Führe das nach jedem Schema-Änderungs-Workflow aus:

pnpm db:generate && pnpm db:migrate

In CI oder bei Production-Deploys führe pnpm db:migrate als Teil des Release-Schritts aus (nachdem Env-Vars verfügbar sind).

Troubleshooting

pnpm db:studio

Öffnet Drizzle Studio — eine lokale Web-UI zum Durchsuchen von Tabellen, Anzeigen von Zeilen und Ausführen von Ad-hoc-Queries.

When to use

• Daten prüfen während der Entwicklung (users, links, files, sessions)
• Debuggen, ob eine Migration die erwarteten Spalten erzeugt hat
• Verifizieren, dass Test-Sign-ups die richtigen Zeilen geschrieben haben
• Unbekannte Tabellen erkunden nach dem Pull neuer Migrationen

When not to use

• Zum Ändern des Schemas — TypeScript-Schema-Dateien bearbeiten und db:generate + db:migrate ausführen
• In Produktion als primäres Admin-Tool — nutze das Supabase Dashboard oder ein dediziertes Admin für Produktionsdaten
• Als Ersatz für richtige Seed-Skripte — Studio dient der Inspektion, nicht dem wiederholbaren Setup

What it does

Startet einen lokalen Server (Drizzle Kit gibt die URL aus, typischerweise https://local.drizzle.studio). Die Verbindung nutzt DATABASE_URL aus .env.

Example

pnpm db:studio

Lass das Terminal geöffnet, während du Studio nutzt. Mit Ctrl+C beenden, wenn du fertig bist.

Typical workflows

First-time local setup

cp .env.example .env
# fill in DATABASE_URL
pnpm db:migrate
pnpm dev

Kein db:generate nötig — Migrationen liegen bereits im Repo.

You changed the schema

# 1. Edit src/lib/db/schema/*.ts and export from schema.ts
pnpm db:generate
pnpm db:migrate
pnpm db:studio   # optional — verify the new table

You pulled new migrations from git

pnpm db:migrate

You want to inspect data without changing anything

pnpm db:studio

Migration files in the repo

Angewendete Migrationen liegen in drizzle/migrations/. Jeder Ordner enthält:

• migration.sql — von db:migrate ausgeführtes SQL
• snapshot.json — interner Schema-Snapshot für den nächsten db:generate-Diff

Committe Migrationsdateien in Git. Teammitglieder und Production-Deploys verlassen sich auf dieselbe geordnete SQL-Historie.

Bearbeite angewendete Migrationen in Produktion nicht von Hand. Wenn du einen Fehler beheben musst, bevor jemand migriert hat, lösche den nicht angewendeten Migrationsordner und regeneriere. Wenn bereits angewendet, erstelle eine neue korrigierende Migration.

Next steps

Adding a New Table — Vollständiges Tutorial: Schema → Export → Generate → Migrate → Queries.

Database — Architekturüberblick, Schema-Konventionen und Query-Muster.