Migrationen & Seeding

Datenbank-Workflow für Entwicklung und Produktion — Prisma Push, Migrate, pgvector-Setup und Seed-Skripte

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:
  1. Berechnet den Diff zwischen deinem Schema und der Datenbank
  2. Generiert und führt das notwendige SQL aus (ALTER TABLE)
  3. 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.

Wann db push verwenden

Szenariodb push verwendenmigrate verwenden
Lokales PrototypingJaNein
Schema-Designs erkundenJaNein
CI/CD-PipelineNeinJa
Produktions-DeploymentNeinJa
Team-Zusammenarbeit (gemeinsame DB)NeinJa
Schema-Verlauf verfolgenNeinJa

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:
  1. Berechnet den Schema-Diff
  2. Generiert eine SQL-Migrations-Datei in apps/boilerplate/prisma/migrations/
  3. Wendet die Migration auf deine lokale Datenbank an
  4. 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

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

Häufige Schema-Änderungen

Ein neues Modell hinzufügen

  1. Das Modell in schema.prisma definieren (siehe Eigene Modelle hinzufügen)
  2. Eine Migration erstellen: cd apps/boilerplate && npx prisma migrate dev --name add-blog-post
  3. Ein Query-Modul in apps/boilerplate/src/lib/db/queries/ erstellen
  4. Aus apps/boilerplate/src/lib/db/queries/index.ts exportieren
  5. MSW-Mock-Handler in apps/boilerplate/src/mocks/ mit Inline-Mock-Typen hinzufügen
  6. 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 EditorNew 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-AnzahlEmpfohlene Lists
< 10.00050
10.000 – 50.000100
50.000 – 100.000200
> 100.000sqrt(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 der faq_chunks-Tabelle
  • Die embedding-Spalte mit dem Typ USER-DEFINED in der Spaltenauflistung

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

Fehlerbehebung

Befehlsreferenz

BefehlZweckWann verwenden
cd apps/boilerplate && npx prisma db pushSchema-Änderungen direkt anwendenEntwicklung, Prototyping
cd apps/boilerplate && npx prisma migrate dev --name <name>Migration erstellen und anwendenVor dem Committen von Schema-Änderungen
cd apps/boilerplate && npx prisma migrate dev --create-onlyMigration erstellen ohne AnwendungCode-Review vor Anwendung
cd apps/boilerplate && npx prisma migrate deployAusstehende Migrationen anwendenCI/CD, Produktions-Deployment
cd apps/boilerplate && npx prisma migrate resetAlle Tabellen löschen, neu migrieren, Seed ausführenLokale Datenbank zurücksetzen
cd apps/boilerplate && npx prisma generateTypeScript-Client neu generierenNach jeder Schema-Änderung
pnpm db:studioDatenbank-GUI öffnenDaten inspizieren und bearbeiten
cd apps/boilerplate && npx prisma db pullDatenbank in Schema introspektierenBestehende DB rückwärts entwickeln
cd apps/boilerplate && npx prisma db seedSeed-Skript ausführenEntwicklungsdaten befüllen