Einführung von Prisma 7 in einem Next.js 16 TypeScript-Projekt
Erfahren Sie, wie Sie Prisma 7 mit PostgreSQL in einer Next.js 16-Anwendung installieren, konfigurieren und migrieren, und erstellen Sie anschließend einen Singleton-Client, um Verbindungslecks zu vermeiden.
Dieser Leitfaden zeigt, wie Prisma 7 in einer Next.js 16-Anwendung integriert werden kann, die mit PostgreSQL kommuniziert, wobei TypeScript und pnpm als Paketmanager verwendet werden.
Schritt 1: Die Prisma-Pakete hinzufügen
pnpm add prisma @prisma/client @prisma/adapter-pg
- prisma – das Kommandozeilenwerkzeug, das Sie zum Ausführen von Migrationsvorgängen, zur Erstellung des Clients sowie zur Verwaltung Ihres Schemas verwenden.
- @prisma/client – die generierte Client-Bibliothek, auf die Ihr Anwendungscode direkt zugreifen kann.
- @prisma/adapter-pg – der PostgreSQL-Adapter, den Prisma 7 eingeführt hat, um mit Postgres zu verbinden.
Sobald diese drei Pakete installiert sind, können Sie mit der Einrichtung von Prisma fortfahren.
Schritt 2: Prisma initialisieren
pnpm dlx prisma init
Durch Ausführen dieses Befehls werden die grundlegenden Dateien und Verzeichnisse erstellt, die Sie zum Start benötigen.
prisma.config.ts
prisma/
└── schema.prisma
Verständnis von prisma.config.ts
In dieser Datei sind die Einstellungen enthalten, die Prisma zum Funktionieren benötigt, einschließlich der Verbindung zu Ihrer Datenbank und des Verhaltens des Client-Generators.
import "dotenv/config";
import { defineConfig } from "prisma/config";
export default defineConfig({
schema: "prisma/schema.prisma",
migrations: {
path: "prisma/migrations",
},
datasource: {
url: process.env["DATABASE_URL"],
},
});
Verständnis von schema.prisma
Jede Tabelle, die Sie in PostgreSQL speichern möchten, erscheint hier letztendlich als Modelldefinition.
generator client {
provider = "prisma-client"
output = "../lib/generated/prisma"
}
datasource db {
provider = "postgresql"
}
// models that You want to create
Schritt 3: Prisma auf Ihre Datenbank verweisen
Prisma benötigt eine Verbindungszeichenkette, bevor es überhaupt mit Ihrer Datenbank kommunizieren kann. Sie können diese von einem gehosteten Anbieter wie Neon erhalten oder indem Sie eine Postgres-Instanz lokal über Docker ausführen.
DATABASE_URL="postgresql://username:password@localhost:5432/my_database"
Sobald diese Umgebungsvariable gesetzt ist, kann Prisma auf Ihre Datenbank zugreifen.
Schritt 4: Ein erstes Modell definieren
Der Prisma Client kann erst generiert werden, wenn im Schema mindestens ein Modell vorhanden ist.
Da die Datenbank zu diesem Zeitpunkt noch leer ist, fügen Sie ein minimales Platzhaltermodell hinzu, damit Prisma etwas zum Arbeiten hat.
model Test {
id Int @id @default(autoincrement())
}
Das Ziel hier ist nicht eine sinnvolle Tabelle – es geht lediglich darum, dem Generator ein gültiges Schema zur Verfügung zu stellen, auf dem er aufbauen kann.
Schritt 5: Ihre erste Migration anwenden
Danach wandeln Sie dieses Schema in echte Datenbanktabellen um, indem Sie eine Migration ausführen.
pnpm dlx prisma migrate dev
Dieser einzige Befehl erledigt automatisch mehrere Dinge:
- Er generiert eine neue Migrationdatei.
- Er wendet diese Migration auf Ihre konfigurierte Datenbank an.
- Er hält die Struktur Ihrer laufenden Datenbank in Einklang mit dem, was in
schema.prismadeklariert ist.
Sobald die Ausführung erfolgreich abgeschlossen ist, wird die Test-Tabelle in Ihrer Datenbank vorhanden sein.
Schritt 6: Erstellen des Prisma Clients
Eine der auffälligsten Änderungen in Prisma 7 ist, dass der Client nicht mehr automatisch für Sie erzeugt wird.
Sie müssen die Erstellung nun explizit auslösen.
pnpm dlx prisma generate dev
Sobald dies abgeschlossen ist, erstellt Prisma einen vollständig typisierten Client, der auf Ihrem Schema basiert.
Der Client stellt alle Methoden bereit, die Sie zur Abfrage und Änderung Ihrer Daten benötigen.
generated/
└── prisma/
Jedes in Ihrem Schema definierte Modell wird nun als eigene typisierte TypeScript-API bereitgestellt.
Schritt 7: Erstellen eines Singleton-Prisma Clients
Anstatt bei jeder Anfrage einen neuen Prisma Client zu instanzieren, ist es nach besten Praktiken, eine einzige gemeinsame Instanz in Ihrer Anwendung zu wiederverwenden.
File: lib/prisma.ts
import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "./generated/prisma/client";
const globalForPrisma = globalThis as unknown as {
prisma: PrismaClient | undefined;
};
function createPrismaClient() {
const url = process.env.DATABASE_URL;
if (!url) {
throw new Error("DATABASE_URL is not set");
}
const adapter = new PrismaPg({ connectionString: url });
return new PrismaClient({ adapter });
}
export const prisma = globalForPrisma.prisma ?? createPrismaClient();
if (process.env.NODE_ENV !== "production") {
globalForPrisma.prisma = prisma;
}
Warum ein Singleton hier wichtig ist
Während der Entwicklung lädt Next.js die Module ständig neu.
Falls bei jedem Neuladen ein neuer PrismaClient erstellt wird, entstehen letztendlich weitaus mehr Datenbankverbindungen, als beabsichtigt.
Wenn dies unkontrolliert bleibt, tritt schließlich ein Fehler in dieser Art auf:
Too many database connections
Durch die Verwendung des Singleton-Musters wird sichergestellt, dass nur eine einzige Prisma Client-Instanz während der gesamten Laufzeit der Anwendung vorhanden bleibt.
Das ist der Ansatz, den Prisma selbst für Next.js-Projekte empfiehlt.
Schritt 8: Den Client in Ihrer gesamten Anwendung verwenden
Sobald die gemeinsame Client-Instanz vorhanden ist, können Sie sie von überall in Ihrem Projekt importieren.
import { prisma } from "@/lib/prisma";
Von hier aus haben alle Serverkomponenten, API-Endpunkte oder Server-Aktionen direkten Zugriff auf Ihre Datenbank.
Weitere Details zu dieser Einrichtung finden Sie in der offiziellen Prisma-Dokumentation zur Next.js-Integration unter prisma.io/docs/guides/nextjs.
Zusätzliche Literatur
- Erstellung wiederverwendbarer Next.js-Startervorlagen, um Boilerplate zu vermeiden — Erfahren Sie, wie ein Entwickler wiederholende Next.js-Aufbereitungsarbeiten durch eine wachsende Sammlung minimalistischer Startervorlagen für Shops und Landing Pages ersetzt hat.
- Migration von Prisma zu Drizzle: Eine Rückblick über sechs Monate — Ein Entwickler teilt praktische Vergleiche und Abwägungen aus dem Umgang mit einem PostgreSQL-TypeScript-Stack, der von Prisma auf Drizzle ORM umgestellt wurde.