Ein NestJS- und Prisma-API-Projekt ohne Beziehungsfehler oder P1001-Fehler starten

Fast jede Backend-Funktion, die ein Team später entwickelt – von der Authentifizierung über Multi-Tenancy bis hin zur rollenbasierten Zugriffskontrolle – basiert auf den ersten Stunden der Projekt-Einrichtung. Wenn die Umgebungsvariablen, die Datenbankverbindung, die Schema-Beziehungen sowie die Migrationsdateien zu Beginn unordentlich konfiguriert werden, erbt jeder spätere Pull Request dieses Chaos. Dieser Leitfaden zeigt Schritt für Schritt, wie man eine NestJS-API mit Prisma und PostgreSQL aufbaut, erläutert die drei Probleme, die am häufigsten dazu führen, dass dieses erste Meilenstein nicht erreicht wird, und gibt Ihnen eine Checkliste, um festzustellen, wann die Grundlagen tatsächlich fertig sind.

Wie ein abgeschlossenes Bootstrap aussieht

Es hilft, das Ziel vor dem Umgang mit der CLI zu definieren. Ein Bootstrap ist abgeschlossen, wenn ein Prüfer den Branch klonen und Folgendes bestätigen kann:

• Eine in TypeScript geschriebene NestJS-Anwendung, die ohne Fehler startet

Prisma ist mit einer PostgreSQL-Datenbank verbunden

Die Konfiguration wird aus Umgebungsvariablen geladen statt von fest codierten Werten

Eine anfängliche Gruppe von Datenmodellen, die das Anwendungsbereich widerspiegeln

Eine Migration, die problemlos auf einer leeren Datenbank angewendet werden kann

Ein fokussierter Pull Request, den der Rest des Teams überprüfen und zusammenführen kann

Die Einschränkungen sind absichtlich eng gefasst: NestJS und Prisma als einziges Framework und ORM, PostgreSQL als Datenbank sowie die bestehenden Konventionen des Teams für Konfiguration und Git.

Das Toolset

• Framework und Sprache: NestJS mit TypeScript
• Datenzugriff: prisma (die CLI) und @prisma/client (der generierte Abfrage-Client)
• Konfiguration: @nestjs/config
• Datenbank: eine lokale PostgreSQL-Instanz
• Überprüfung: Die Prisma CLI sowie ein Browser oder API-Client zum Aufrufen der Endpunkte

Einrichtung des Projektgerüsts

Beginnen Sie damit, eine neue Anwendung mit der Nest CLI zu erstellen, fügen Sie anschließend Prisma hinzu und initialisieren Sie es innerhalb des Projekts. Durch die Initialisierung wird ein prisma/-Verzeichnis für das Schema und die Migrationsdateien erstellt, während der Anwendungscode in src/ verbleibt.

Danach erstellen Sie eine .env-Datei, die DATABASE_URL enthält – den PostgreSQL-Verbindungsstring, den Prisma liest. Laden Sie die Konfiguration über das @nestjs/config-Modul, damit die Anwendung Werte aus der Umgebung statt aus im Code verstreuten Literalwerten verwendet. Stellen Sie sicher, dass .env in .gitignore aufgeführt ist; das Einreichen echter Anmeldeinformationen bereits im ersten PR ist ein leichter Fehler, den es schwierig rückgängig zu machen gilt.

Vor dem Schreiben beliebiger Modelle sollten Sie überprüfen, ob Prisma tatsächlich auf die Datenbank zugreifen kann. Wenn Sie eine ausführlichere Erklärung zur Prisma-Seite selbst wünschen, lesen Sie „Setting up Prisma 7 with PostgreSQL in a TypeScript Node.js Project“ und prüfen Sie die aktuellen Prisma-Dokumente nach versionsspezifischen Informationen.

Modellierung der ersten Entitäten

Für ein Produkt mit mehreren Nutzern sollte ein sinnvoller Ausgangsschema aus vier Modellen bestehen:

• Tenant, der eine Organisation darstellt, die das System verwendet
• User, der eine Person darstellt, die sich anmeldet
• Role, zur grundlegenden Zuweisung von Rollen innerhalb eines Tenants
• Invite, zur Einbeziehung neuer Benutzer in einen Tenant

Zusammen erfassen sie das, von dem spätere Funktionen abhängen: Benutzer gehören zu Mietergruppen, haben bestimmte Rollen und werden über Einladungen hinzugefügt. Jede Beziehung benötigt ein Feld auf beiden Seiten, was die Ursache für den ersten Fehler unten ist.

Sobald das Schema validiert wurde, führen Sie die anfängliche Migration durch, damit die Datenbankstruktur dem Schema entspricht. Halten Sie sie frei von Experimenten, da jeder Teammitglied sie lokal anwenden wird.

Hinzufügen eines Health-Endpunkts

Auf der API-Seite fügen Sie einen einzigen Controller hinzu, der /health bereitstellt und dabei einen einfachen OK-Status zurückgibt. Es scheint trivial zu sein, dient aber einem echten Zweck: Er bietet Ihnen, Ihrem CI-Pipeline sowie letztendlich Ihrem Load Balancer oder Orchestrator eine einfache Möglichkeit, herauszufinden, ob der Prozess läuft und Anfragen bearbeitet.

Drei Fehler, die häufig den ersten Meilenstein blockieren

Prisma lehnt eine Beziehung ohne gegenüberstehendes Feld ab

Symptom: Die Schema-Validierung fehlschlägt mit der Meldung, dass eine Beziehung ihr gegenüberstehendes Feld fehlt.

Ursache: Prisma verlangt, dass Beziehungen in beiden Modellen deklariert werden. Wenn User auf Tenant verweist, aber Tenant kein Feld enthält, das seine Benutzer auflistet, ist das Schema aus Prismas Sicht unvollständig.

Lösung: Fügen Sie die fehlenden Rückverweis-Felder zu den entsprechenden Modellen hinzu und führen Sie anschließend prisma format aus. Der Formatierer normalisiert die Datei und kann fehlende Beziehungsfelder für Sie ergänzen, weshalb es sich als gute Gewohnheit erweist, ihn nach jeder Schema-Änderung auszuführen.

P1001: Keine Verbindung zum Datenbankserver möglich

Symptom: Prisma gibt den Fehlercode P1001 an und kann sich nicht mit PostgreSQL verbinden.

Ursache: in der Regel eine von zwei Möglichkeiten. Entweder läuft der PostgreSQL-Server nicht, oder die Portnummer in DATABASE_URL stimmt nicht mit der Portnummer überein, auf der der Server lauscht.

Lösung: Überprüfen Sie, ob der Datenbankprozess lokal läuft, und vergleichen Sie anschließend den Host- und Portnamen in der Verbindungszeile mit der tatsächlichen Konfiguration des Servers.

Ein Pull-Request, der alles zu löschen scheint

Symptom: Ein Prüfer öffnet den PR und stellt fest, dass alle Dateien im Repository gelöscht wurden.

Ursache: Der Commit wurde aus einem falschen Git-Zustand vorgenommen, wodurch der Diff mit etwas völlig anderem verglichen wird als ursprünglich beabsichtigt.

Lösung: Anstatt zu versuchen, die verwickelte Historie zu reparieren, erstellen Sie einen neuen Branch von der richtigen Basis und wenden nur die beabsichtigten Änderungen erneut an. Das Ausführen von git status sowie das Überprüfen von git diff im Vergleich zum Zielbranch vor dem Push ermöglicht es, solche Fehler frühzeitig zu erkennen.

Überprüfung der Einrichtung

Die Überprüfung sollte sich langweilig einfach wiederholen lassen:

• Führen Sie npx prisma migrate dev aus und stellen Sie sicher, dass die Migration ohne Fehler angewendet wird
• Starten Sie den NestJS-Server
• Öffnen Sie /health in einem Browser oder API-Client und überprüfen Sie die OK-Antwort

Sobald die Migration reibungslos abgeschlossen ist und der Health-Endpoint antwortet, ist die Grundlage für die nächste Funktion bereit.

Wichtige Erkenntnisse

• Betrachten Sie das Bootstrap als ein Ergebnis mit klaren Akzeptanzkriterien, nicht als temporäres Gerüst.

Melden Sie jede Prisma-Beziehung auf beiden Seiten an und lassen Sie prisma format das Schema ordentlich halten.

Sieht man P1001, sollte man vor dem Fehlersuchen zunächst überprüfen, ob PostgreSQL läuft und ob die Port-Nummer in DATABASE_URL korrekt ist.

Ein Health-Endpoint kostet nur wenige Minuten, bringt aber Vorteile bei CI-Prozessen, Überwachung und Bereitstellungsprüfungen.

Kleine, gezielte Pull-Requests mit sauberer Historie gehören zum Entwicklungsprozess und nicht erst dazu, wenn alles schon fertig ist.

Verwandte Artikel

• NestJS auf Bun und Prisma 7 zu Cloud Run ohne Build-Fehler bereitstellen — Ein funktionierender GitHub Actions-Pipeline zum Versand einer NestJS-Anwendung auf Bun mit Prisma 7 und Neon zu Cloud Run, sowie die Docker- und Verbindungsprobleme, die Teams behindern.
• MovieVault Walkthrough: Eine Watchlist-API mit Express 5, Prisma 7 und JWT — Eine zeitbasierte Full-Stack-Übung mit den entsprechenden Backend-Technologien Express, Prisma und JWT, inklusive Anmerkungen zu Überprüfungen der Rechteverwaltung, Kaskadenreaktionen und Fehlerbehandlung.