Konfigurieren von Prisma 7 mit Accelerate-URLs

Prisma 7 (veröffentlicht am 19. November 2025) ändert die Konfiguration so stark, dass viele Tutorials für Prisma 6 nicht mehr gelten. Die untenstehenden Anmerkungen stammen aus der Lektüre der Dokumentation, der Prüfung der generierten Deklarationsdateien sowie aus der Bearbeitung der Fehler, die bei einer ersten Einrichtung mit SQL/Postgres auftreten – insbesondere für Nutzer, die von MongoDB und Mongoose kommen.

Der Upgrade-Weg ist für Anfänger besonders schwierig: Die erste erfolgreiche Erstellung eines PrismaClient-Objekts in älteren Materialien ist oft bereits am ersten Tag von Prisma 7 fehlerhaft. Betrachten Sie die Konstruktorargumente sowie die Konfigurationsdateien als Teil des grundlegenden Verständnisses und nicht als optionale, fortgeschrittene Themen.

1. Erste große Änderung: prisma.config.ts

Nach der Installation generiert Prisma eine neue Root-Datei:

prisma.config.ts

In früheren Versionen wurde DATABASE_URL in schema.prisma gespeichert. Diese Verbindungskonfiguration befindet sich nun in prisma.config.ts.

Erstellte Form:

// This file was generated by Prisma and assumes you have installed the following:
// npm install --save-dev prisma dotenv
import "dotenv/config";
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: {
    path: "prisma/migrations",
  },
  datasource: {
    url: env("DATABASE_URL"),
  },
});

Was hat sich geändert?

• env("DATABASE_URL") ist nicht mehr die Aufgabe des Schemas.
• Konfigurationen, die mit der Umgebung zusammenhängen, werden in die neue Datei verschoben.
• schema.prisma konzentriert sich weiterhin auf Modelle.

2. Behebung des Problems mit dem Root-Verzeichnis in tsconfig.json

Falls tsconfig.json Folgendes enthält:

"rootDir": "./src"

TypeScript lehnt prisma.config.ts, das außerhalb von src liegt, ab. Erweitern Sie das Root-Verzeichnis:

"rootDir": "./"

3. Migration und Erstellung des Clients

Sobald die Modelle vorhanden sind:

npx prisma migrate dev
npx prisma generate

Der Generierungsblock des Schemas weist den Client auf die Quelldateien hin:

generator client {
  provider = "prisma-client"
  output   = "../src/generated/prisma"
}

Die Erstellung scheint in Ordnung zu sein, bis zur Konstruktion von PrismaClient.

4. Der verwirrendste Fehler: „Erwartet 1 Argument, erhalten 0“

Diese Konstruktion mit null Argumenten:

const prisma = new PrismaClient();

Importieren Sie PrismaClient aus dem generierten client-Modul – nicht aus einer zugehörigen Klassendatei. Selbst dann kann Prisma 7 Null-Argumente ablehnen:

Expected 1 argument, but got 0.

Ältere Tutorials zeigen immer noch einen Konstruktor ohne Argumente. Eine Untersuchung der generierten client/class-Dateien zeigt, dass der Konstruktor nun Konfiguration erfordert, darunter:

accelerateURL

5. Einführung von accelerateURL (neu in Prisma 7)

Prisma 7 ist eng mit Prisma Accelerate integriert – globales Abfragespeichern sowie Verbindungs-Pooling. Accelerate zielt darauf ab:

• Abfragen global zu speichern
• Die Latenz zu verringern
• Verbindungen für Serverless-Umgebungen zu poolen

In diesem Modus erfordert PrismaClient einen accelerateURL.

6. Prisma bietet nun seine eigene Cloud-Datenbank an

Das Prisma-Dashboard kann:

• eine Datenbank erstellen
• einen Accelerate API-Schlüssel generieren
• für den Client einen accelerateURL bereitstellen

Eine praktische Einschränkung: gewöhnliche URLs im Neon-Stil, die mit folgendem beginnen:

" postgresql:// "

erfüllen die von Accelerate erwarteten Protokolle nicht:

" prisma:// " or " prisma+postgres:// "

Unstimmigkeiten führen zu Fehlern mit folgendem Inhalt:

InvalidDatasourceError: Error validating `accelerateUrl`: the URL must
start with the protocol `prisma://` or `prisma+postgres://`

7. Endgültige Einrichtung von PrismaClient (Prisma 7)

Ein funktionierendes Muster:

import { withAccelerate } from "@prisma/extension-accelerate";
import { PrismaClient } from "../src/generated/prisma/client.js";
import { DATABASE_URL } from "../config/index.js";

export const prisma = new PrismaClient({
  accelerateUrl: DATABASE_URL as string
}).$extends(withAccelerate());

Was ist $extends?

$extends() fügt dem Client Funktionen wie Accelerate hinzu.

8. Wichtiger Hinweis: Zwei Umgebungsvariablen erforderlich

Prisma 7-Einrichtungen in diesem Modus benötigen in der Regel:

DATABASE_URL → Accelerate-URL

DIRECT_DATABASE_URL → direkte PostgreSQL-Verbindungszeichenkette

prisma.config.ts sollte für Migrationsarbeiten die direkte URL verwenden:

export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: {
    path: "prisma/migrations",
  },
  datasource: {
    url: env("DIRECT_DATABASE_URL"),
  },
});

Dann migrieren und erneut generieren:

npx prisma migrate dev
npx prisma generate

Aufsetzungen, die auf Accelerate ausgerichtet sind, verändern ebenfalls die Arbeitsgewohnheiten. Migrationsvorgänge und Selbstuntersuchungen benötigen weiterhin eine direkte Datenbank-URL, während der Anwendungsverkehr über den Accelerate-Endpunkt fließen kann. Das Mischen dieser beiden URLs – das Einfügen einer direkten Postgres-URL anstelle einer Accelerate-URL oder umgekehrt – führt zu Fehlern, die nicht mit der bearbeiteten Anwendungscodezeile in Verbindung zu stehen scheinen. Halten Sie die beiden Werte in den .env-Beispielen klar benannt und sorgen Sie dafür, dass bei einem falschen Protokollpräfix bereits beim Start Fehler auftreten.

Für Teams, die von Prisma 6 migrieren, sollten Sie mit einer Checkliste statt mit einem direkten Upgrade rechnen: Fügen Sie prisma.config.ts hinzu, erweitern Sie gegebenenfalls rootDir, stoppen Sie die Erstellung von PrismaClient mit null Argumenten, wenn Accelerate aktiv ist, verknüpfen Sie $extends(withAccelerate()) und teilen Sie die Umgebungsvariablen auf. Sobald diese Checkliste zur Gewohnheit geworden ist, wirkt das tägliche Modellieren wieder vertraut.

Fazit

Die Neuerungen in Prisma 7 – prisma.config.ts, erforderliche Client-Argumente, accelerateURL und $extends – werden in den Prisma 6-Dokumentationen nur unzureichend behandelt. Sobald die URL-Regeln von Accelerate sowie die Trennung in mehrere Umgebungen klar sind, wird die Client-Einrichtung sowohl für Anfänger im Umgang mit SQL als auch bei Upgrades von v6 vorhersehbar.