Datenbank einrichten

Was eine Migration ist

Eine frische Datenbank ist leer — sie hat keine Tabellen für Benutzer, Arbeitsbereiche oder Datensätze. Eine Migration ist eine gespeicherte, geordnete Datenbankänderung: eine Datei, die besagt „erstelle diese Tabelle, füge jene Spalte hinzu“. Das Kit liefert seine Migrationen fertig mit; der Befehl db:migrate wendet jede ausstehende auf die Datenbank an, die DATABASE_URL benennt.

Sie auszuführen ist keine optionale Einrichtung — genau das macht ein leeres Postgres zur Datenbank Ihrer App. Anmeldung, Arbeitsbereiche, Abrechnungsdatensätze und gespeicherte Daten liegen alle in diesen Tabellen.

Deshalb brechen Konten, wenn die Anmeldung vor den Migrationen erfolgt: Die App schreibt den neuen Benutzer in eine Tabelle, die noch nicht existiert, und hinterlässt ein halb angelegtes Konto. Migrieren Sie immer zuerst — die Einrichtungsschritte unten tun genau das vor der ersten echten Anmeldung.

Einrichtung und Konfiguration

Lesen Sie vor jedem Schritt Bevor Sie beginnen und Terminal-Grundlagen. Bei diesen Anweisungen wird davon ausgegangen, dass Sie das vollständige Supastack-Monorepo in VS Code geöffnet haben. Sein Stamm package.json markiert den Repository-Stamm. In pnpm-Befehlen ist ein Arbeitsbereichspaket eine App oder ein Ordner mit gemeinsam genutztem Code. Im Produkt ist ein Arbeitsbereich der Datencontainer und die Sicherheitsgrenze eines Teams. corepack pnpm --filter ... wählt ein Paket aus dem Monorepo aus, während Befehle von seinem Stammverzeichnis aus ausgeführt werden. Wenn Sie nur einen synchronisierten Mobil- oder Desktop-Ordner geöffnet haben, enthält dieser weder das Web-Backend, Docker-Setup noch Root-Skripte: Führen Sie das Backend von diesem Monorepo oder einem erreichbaren gehosteten Server aus und verwenden Sie die eigenen Skripte des Plattformordners. Eine Umgebungsvariable ist eine benannte Einstellung, die in einer lokalen .env-Datei oder Ihrem Hosting-Dashboard gespeichert ist; Starten Sie die entsprechende App neu, nachdem Sie sie geändert haben, und halten Sie Servergeheimnisse von den Werten NEXT_PUBLIC_ und EXPO_PUBLIC_ fern.

1. Installieren und starten Sie Docker Desktop.

2. Kopieren Sie .env.example nach .env im Stammverzeichnis für Migrationstools und nach apps/web/.env.local für Next.js (PowerShell: Copy-Item .env.example .env; Copy-Item .env.example apps/web/.env.local. macOS/Linux/Git Bash: cp .env.example .env; cp .env.example apps/web/.env.local). Halten Sie DATABASE_URL in beiden Dateien gleich; Das Beispiel stimmt bereits mit der lokalen Docker-Datenbank überein.

3. Führen Sie im Repository-Root „docker compose up -d postgres“ und „docker compose ps“ aus; Warten Sie, bis Postgres einen gesunden Zustand meldet.

4. Führen Sie corepack pnpm --filter @supastack/db db:migrate vom Stammverzeichnis aus aus, um die bereits mit dem Kit gelieferten Migrationen anzuwenden. Führen Sie erst nach der Bearbeitung von packages/db/src/schema.ts db:generate aus, überprüfen Sie das generierte SQL und führen Sie dann db:migrate aus. Erwartet: Der lokale Postgres-Container ist fehlerfrei und die Web-App verwendet seine migrierte Datenbank. Richten Sie diesen ersten Lauf niemals auf die Produktion aus.

Konfigurieren Sie DATABASE_URL für die vorgesehene Postgres-Datenbank in der Serverumgebung. Verwenden Sie für Integrationsabnahmen eine separate Wegwerf-Datenbank. Richten Sie Testmigrationen niemals auf eine Produktionsdatenbank.

Der Datenbank-Workspace exportiert Schemadefinitionen und Persistenzhilfen. Prüfen Sie packages/db/src/schema.ts und das Migrationsverzeichnis, bevor Sie eine Tabelle oder Spalte hinzufügen.

docker compose up -d postgres
docker compose ps
corepack pnpm --filter @supastack/db db:migrate

# Only after changing packages/db/src/schema.ts:
corepack pnpm --filter @supastack/db db:generate
corepack pnpm --filter @supastack/db db:migrate

# Optional Compose / Supabase settings in .env:
# POSTGRES_PASSWORD=supastack
# SUPABASE_ACCESS_TOKEN=
# DATABASE_POOLER=transaction

Befehle zum Kopieren

Befolgen Sie die Kommentare, um zu sehen, in welchem Ordner ein Befehl ausgeführt wird. Wenn zwei Terminals gekennzeichnet sind, öffnen Sie zwei Terminalfenster und lassen Sie den ersten Befehl laufen, während Sie den zweiten verwenden.

# Choose one copy method for your terminal:
# PowerShell:
Copy-Item .env.example .env
Copy-Item .env.example apps/web/.env.local

# macOS/Linux/Git Bash alternative:
# cp .env.example .env
# cp .env.example apps/web/.env.local

docker compose up -d postgres
docker compose ps
corepack pnpm --filter @supastack/db db:migrate

Implementierungsablauf

Erzeugen Sie nach einer Schemaänderung eine Migration, prüfen Sie das erzeugte SQL und committen Sie sie zusammen mit der Schemaänderung. Planen Sie, wie bestehende Datensätze Werte erhalten, bevor Sie eine Pflichtspalte ergänzen.

Fügen Sie jedem benutzereigenen Datensatz workspaceId hinzu und übernehmen Sie diese Abgrenzung in Lese- und Schreibzugriffe. Verwenden Sie für die KI-Abrechnung einen unveränderlichen Modellpreisverlauf, statt Preise umzuschreiben, die bestehenden Nutzungsdatensätzen zugrunde liegen.

Überprüfung und Fehlerbehebung

Kann Docker keine Verbindung zur Engine herstellen, starten Sie Docker Desktop und warten Sie, bis es geladen ist. Meldet postgres keinen Status healthy, führen Sie im Stammverzeichnis docker compose logs postgres aus und beheben Sie den Fehler vor der Migration. Meldet Web, dass DATABASE_URL fehlt, prüfen Sie apps/web/.env.local; kann db:migrate keine Verbindung herstellen, prüfen Sie die Stamm-.env. Ändern Sie die Datenbank, aktualisieren Sie beide Dateien. Lesen Sie bei einem Migrationsfehler die erste fehlgeschlagene Anweisung, bevor Sie es erneut versuchen. Wiederholen Sie den Lauf niemals gegen Produktion.

Wenden Sie Migrationen auf eine isolierte Datenbank an und führen Sie dort datenbankabhängige Tests aus. Fehlende Zugangsdaten müssen den Prüfschritt ausdrücklich überspringen, statt fälschlich erfolgreiche Persistenz zu melden. Wenn eine Migration fehlschlägt, prüfen Sie vor einem erneuten Versuch das betroffene Statement und den aktuellen Schema-Stand.