Prisma bietet zwei unterschiedliche Workflows für die Anwendung von Schema-Änderungen auf deine Datenbank — einen für Entwicklungsgeschwindigkeit optimierten und einen für Produktionssicherheit. Diese Seite behandelt beide, plus die Einrichtung der pgvector-Erweiterung und das Befüllen der Datenbank mit Testdaten.
Entwicklungs-Workflow
Verwende während der Entwicklung
prisma db push, um Schema-Änderungen sofort anzuwenden. Es liest deine schema.prisma-Datei, vergleicht sie mit dem aktuellen Datenbankzustand und wendet den Diff an — keine Migrations-Dateien, keine SQL-Überprüfung.1
Schema bearbeiten
Öffne
apps/boilerplate/prisma/schema.prisma und nimm deine Änderungen vor. Zum Beispiel ein neues Feld hinzufügen:prisma
model User {
// ... existing fields
bio String? // NEU: Benutzer-Biografie
}
2
Schema pushen
Die Änderung auf deine lokale Datenbank anwenden:
bash
cd apps/boilerplate && npx prisma db push
Dieser Befehl:
- Berechnet den Diff zwischen deinem Schema und der Datenbank
- Generiert und führt das notwendige SQL aus (
ALTER TABLE) - Regeneriert den Prisma-Client automatisch
3
In Prisma Studio überprüfen
Optional Prisma Studio öffnen, um die Datenbank visuell zu inspizieren:
bash
pnpm db:studio
Dies startet eine browserbasierte GUI unter
http://localhost:5555, in der du Tabellen durchsuchen, Datensätze anzeigen und Daten bearbeiten kannst.prisma db push ist schnell und perfekt für das Prototyping, erstellt aber keine Migrations-Dateien. Wenn du einen überprüfbaren Migrations-Verlauf benötigst (für die Produktion empfohlen), verwende den unten beschriebenen Produktions-Workflow.Wann db push verwenden
| Szenario | db push verwenden | migrate verwenden |
|---|---|---|
| Lokales Prototyping | Ja | Nein |
| Schema-Designs erkunden | Ja | Nein |
| CI/CD-Pipeline | Nein | Ja |
| Produktions-Deployment | Nein | Ja |
| Team-Zusammenarbeit (gemeinsame DB) | Nein | Ja |
| Schema-Verlauf verfolgen | Nein | Ja |
Produktions-Migrationen
Für Produktionsdatenbanken verwende Prisma Migrate. Es erstellt versionierte SQL-Migrations-Dateien, die überprüft, in Git committet und über deine CI/CD-Pipeline deployt werden.
Eine neue Migration aus deinen Schema-Änderungen erstellen:
cd apps/boilerplate && npx prisma migrate dev --name add-user-bio
Dieser Befehl:
- Berechnet den Schema-Diff
- Generiert eine SQL-Migrations-Datei in
apps/boilerplate/prisma/migrations/ - Wendet die Migration auf deine lokale Datenbank an
- Regeneriert den Prisma-Client
Die generierte Migrations-Datei sieht so aus:
apps/boilerplate/prisma/migrations/
20260214120000_add_user_bio/
migration.sql
-- prisma/migrations/20260214120000_add_user_bio/migration.sql
ALTER TABLE "User" ADD COLUMN "bio" TEXT;
Best Practices für Migrationen
Manche Schema-Änderungen verursachen Datenverlust. Prisma wird dich warnen, aber überprüfe immer das generierte SQL, bevor du es in der Produktion deployst:
- Eine Spalte löschen — Alle Daten in dieser Spalte gehen verloren
- Eine Tabelle löschen — Alle Daten in der Tabelle gehen verloren
- Einen Spaltentyp ändern — Kann fehlschlagen, wenn bestehende Daten nicht konvertiert werden können
- Ein Pflichtfeld ohne Standardwert hinzufügen — Schlägt fehl, wenn die Tabelle bereits Zeilen enthält
Sichere Muster für häufige Änderungen:
prisma
// Optionales Feld hinzufügen — immer sicher
bio String?
// Pflichtfeld mit Standardwert hinzufügen — sicher für bestehende Zeilen
role String @default("member")
// Feld umbenennen — @map verwenden, um Datenverlust zu vermeiden
displayName String @map("name")
Vollständiger Schema-Änderungs-Workflow
Das Ändern von
schema.prisma erfordert Aktualisierungen an fünf Stellen — nicht nur in der Datenbank. Das Auslassen eines dieser Schritte verursacht Typ-Fehler, Test-Fehlschläge oder veraltete Mock-Daten in der Entwicklung:- Prisma Client —
cd apps/boilerplate && npx prisma generate(automatisch mitdb push/migrate dev) - Datenbank —
cd apps/boilerplate && npx prisma db push(Entwicklung) odercd apps/boilerplate && npx prisma migrate dev(Produktion) - Query-Module —
apps/boilerplate/src/lib/db/queries/aktualisieren, wenn Felder geändert wurden - MSW Mock-Handler — Inline-Typdefinitionen in
apps/boilerplate/src/mocks/*-handlers.tsauf neue Felder anpassen. Denk daran: MSW-Handler können nicht aus@prisma/clientimportieren (Browser-Bundle), daher müssen Typen inline definiert werden. - Test-Factories —
apps/boilerplate/src/test/factories/aktualisieren, um neue Pflichtfelder einzuschließen
Führe
pnpm typecheck && pnpm test:unit nach jeder Schema-Änderung aus, um versäumte Aktualisierungen zu erkennen.Häufige Schema-Änderungen
Ein neues Modell hinzufügen
- Das Modell in
schema.prismadefinieren (siehe Eigene Modelle hinzufügen) - Eine Migration erstellen:
cd apps/boilerplate && npx prisma migrate dev --name add-blog-post - Ein Query-Modul in
apps/boilerplate/src/lib/db/queries/erstellen - Aus
apps/boilerplate/src/lib/db/queries/index.tsexportieren - MSW-Mock-Handler in
apps/boilerplate/src/mocks/mit Inline-Mock-Typen hinzufügen - Test-Factories in
apps/boilerplate/src/test/factories/für das neue Modell hinzufügen
Ein Feld zu einem bestehenden Modell hinzufügen
prisma
model User {
// ... existing fields
avatarUrl String? // Neues Feld — nullable, daher keine Migrations-Probleme
}
bash
cd apps/boilerplate && npx prisma migrate dev --name add-user-avatar
Eine Relation hinzufügen
Um zwei Modelle zu verbinden, ein Fremdschlüssel-Feld und eine
@relation-Direktive hinzufügen:prisma
model Comment {
id String @id @default(uuid())
content String @db.Text
userId String
postId String
createdAt DateTime @default(now())
user User @relation(fields: [userId], references: [id], onDelete: Cascade)
post BlogPost @relation(fields: [postId], references: [id], onDelete: Cascade)
@@index([userId])
@@index([postId])
}
Denk daran, die umgekehrten Relations-Arrays sowohl bei
User als auch bei BlogPost hinzuzufügen:prisma
model User {
// ...
comments Comment[]
}
model BlogPost {
// ...
comments Comment[]
}
Ein Feld sicher entfernen
1
Feld zunächst als optional markieren
Wenn das Feld aktuell erforderlich ist, mache es in der ersten Migration optional:
prisma
// Vorher
bio String
// Nachher (erste Migration)
bio String?
2
Deployen und verifizieren
Die erste Migration deployen. Sicherstellen, dass kein Anwendungscode dieses Feld als erforderlich liest.
3
Feld entfernen
In einer zweiten Migration das Feld vollständig entfernen:
prisma
// Zeile aus schema.prisma entfernen
bash
cd apps/boilerplate && npx prisma migrate dev --name remove-user-bio
Dieser zweistufige Ansatz verhindert Laufzeitfehler, wenn dein Anwendungscode während des Deployments noch auf das Feld verweist.
pgvector-Setup
Kit verwendet die pgvector-Erweiterung für semantische Suche im RAG-System. Nach dem Erstellen deiner Supabase-Datenbank musst du die Erweiterung aktivieren und den Vektor-Suchindex erstellen.
1
Supabase SQL-Editor öffnen
Gehe zu deinem Supabase-Dashboard → SQL Editor → New query.
2
Setup-Skript ausführen
Das pgvector-Setup-SQL kopieren und ausführen:
prisma/setup-pgvector.sql
-- ============================================
-- Supabase pgvector Setup for FAQ RAG System
-- ============================================
-- Run this script in Supabase SQL Editor
-- (https://supabase.com/dashboard/project/YOUR_PROJECT_ID/sql/new)
-- 1. Enable pgvector extension
-- This adds vector data type and similarity search operators
CREATE EXTENSION IF NOT EXISTS vector;
-- 2. Verify extension is installed
SELECT
extname AS "Extension Name",
extversion AS "Version",
'Installed successfully' AS "Status"
FROM pg_extension
WHERE extname = 'vector';
-- 3. Create IVFFlat index for fast similarity search
-- IVFFlat: Inverted File with Flat compression
-- Good balance between speed and accuracy for < 1M vectors
-- vector_cosine_ops: Uses cosine similarity (1 - cosine distance)
CREATE INDEX IF NOT EXISTS faq_chunks_embedding_idx
ON faq_chunks
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);
-- Lists = 100 is good for ~10K-50K vectors
-- Adjust based on dataset size:
-- < 10K vectors: lists = 50
-- 10K-50K: lists = 100
-- 50K-100K: lists = 200
-- > 100K: lists = sqrt(row_count)
Der IVFFlat-Index verwendet
lists = 100, was für 10.000–50.000 Vektoren optimiert ist. Passe den lists-Parameter basierend auf deiner Datensatzgröße an:| Vektor-Anzahl | Empfohlene Lists |
|---|---|
| < 10.000 | 50 |
| 10.000 – 50.000 | 100 |
| 50.000 – 100.000 | 200 |
| > 100.000 | sqrt(row_count) |
3
Installation überprüfen
Das Skript enthält Überprüfungsabfragen. Du solltest sehen:
- Die
vector-Erweiterung aufgelistet mit Version 0.5.1 oder höher - Den
faq_chunks_embedding_idx-Index, erstellt auf derfaq_chunks-Tabelle - Die
embedding-Spalte mit dem TypUSER-DEFINEDin der Spaltenauflistung
Die pgvector-Erweiterung muss aktiviert sein, bevor du
prisma db push oder prisma migrate deploy zum ersten Mal ausführst. Ohne sie kann Prisma die faq_chunks-Tabelle nicht erstellen, weil der Spaltentyp vector(1536) noch nicht existiert.Seeding
Kit wird ohne Seed-Datei ausgeliefert — die Datenbank wird durch normale Anwendungsnutzung befüllt (Benutzerregistrierung, Clerk-Webhooks, Zahlungs-Events). Du kannst jedoch ein Seed-Skript für Entwicklung und Tests erstellen.
Ein Seed-Skript erstellen
Erstelle
apps/boilerplate/prisma/seed.ts:typescript
import { PrismaClient } from '@prisma/client'
const prisma = new PrismaClient()
async function main() {
console.log('Seeding database...')
// Einen Testbenutzer erstellen
const user = await prisma.user.upsert({
where: { clerkId: 'user_test_123' },
update: {},
create: {
clerkId: 'user_test_123',
email: 'test@example.com',
name: 'Test User',
tier: 'pro',
creditBalance: 100.00,
creditsPerMonth: 100.00,
},
})
console.log(`Created user: ${user.id}`)
// Eine Subscription erstellen
await prisma.subscription.upsert({
where: { userId: user.id },
update: {},
create: {
userId: user.id,
customerId: 'cus_test_123',
subscriptionId: 'sub_test_123',
productId: 'prod_test_123',
variantId: 'var_test_123',
status: 'active',
currentPeriodEnd: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 Tage
},
})
console.log('Created subscription')
// Beispiel-FAQ-Chunks erstellen (für RAG-Tests)
await prisma.fAQChunk.createMany({
data: [
{
content: 'How do I reset my password? Go to the login page and click "Forgot password?".',
question: 'How do I reset my password?',
answer: 'Go to the login page and click "Forgot password?" to receive a reset email.',
category: 'Getting Started',
},
{
content: 'How do I upgrade my plan? Go to Dashboard > Billing and select a new plan.',
question: 'How do I upgrade my plan?',
answer: 'Navigate to Dashboard > Billing and click "Upgrade" on the plan you want.',
category: 'Billing',
},
],
skipDuplicates: true,
})
console.log('Created FAQ chunks')
console.log('Seeding complete!')
}
main()
.catch((e) => {
console.error('Seeding failed:', e)
process.exit(1)
})
.finally(async () => {
await prisma.$disconnect()
})
Den Seed-Befehl konfigurieren
Die Seed-Konfiguration in
apps/boilerplate/package.json hinzufügen:json
{
"prisma": {
"seed": "npx tsx prisma/seed.ts"
}
}
Dann ausführen:
bash
cd apps/boilerplate && npx prisma db seed
Die Verwendung von
upsert statt create macht Seed-Skripte idempotent — du kannst sie mehrmals ausführen, ohne doppelte Datensätze zu erstellen. Das ist besonders nützlich beim Zurücksetzen lokaler Datenbanken.Die Datenbank zurücksetzen
Um die Datenbank zu leeren und von Grund auf neu zu befüllen:
bash
# Datenbank zurücksetzen (löscht alle Tabellen, wendet Migrationen erneut an, führt Seed aus)
cd apps/boilerplate && npx prisma migrate reset
# Oder Schema pushen und Seed separat ausführen
cd apps/boilerplate && npx prisma db push --force-reset
cd apps/boilerplate && npx prisma db seed
migrate reset und db push --force-reset löschen alle Daten in der Datenbank. Verwende diese Befehle nur in der Entwicklung.Fehlerbehebung
Befehlsreferenz
| Befehl | Zweck | Wann verwenden |
|---|---|---|
cd apps/boilerplate && npx prisma db push | Schema-Änderungen direkt anwenden | Entwicklung, Prototyping |
cd apps/boilerplate && npx prisma migrate dev --name <name> | Migration erstellen und anwenden | Vor dem Committen von Schema-Änderungen |
cd apps/boilerplate && npx prisma migrate dev --create-only | Migration erstellen ohne Anwendung | Code-Review vor Anwendung |
cd apps/boilerplate && npx prisma migrate deploy | Ausstehende Migrationen anwenden | CI/CD, Produktions-Deployment |
cd apps/boilerplate && npx prisma migrate reset | Alle Tabellen löschen, neu migrieren, Seed ausführen | Lokale Datenbank zurücksetzen |
cd apps/boilerplate && npx prisma generate | TypeScript-Client neu generieren | Nach jeder Schema-Änderung |
pnpm db:studio | Datenbank-GUI öffnen | Daten inspizieren und bearbeiten |
cd apps/boilerplate && npx prisma db pull | Datenbank in Schema introspektieren | Bestehende DB rückwärts entwickeln |
cd apps/boilerplate && npx prisma db seed | Seed-Skript ausführen | Entwicklungsdaten befüllen |