Konfiguracja Prisma 7 z użyciem Accelerate URLs

Prisma 7 (wydany 19 listopada 2025 roku) zmienia konfigurację na tyle, że wiele instrukcji z Prisma 6 już nie jest aktualnych. Poniższe uwagi pochodzą z lektury dokumentacji, analizy generowanych plików deklaracyjnych oraz rozwiązywania błędów pojawiających się podczas pierwszej konfiguracji SQL/Postgres – szczególnie dla osób przychodzących z MongoDB i Mongoose.

Szlak aktualizacji jest szczególnie trudny dla początkujących: pierwsze udane utworzenie obiektu PrismaClient opisane w starszych materiałach często zawiera błędy już od pierwszego dnia pracy z wersją 7. Argumenty konstruktora oraz pliki konfiguracyjne należy traktować jako elementy podstawowego modelu rozumienia narzędzia, a nie jako opcjonalne tematy zaawansowane.

1. Pierwsza duża zmiana: prisma.config.ts

Po zainstalowaniu Prisma generuje nowy plik główny:

prisma.config.ts

We wcześniejszych wersjach wartość DATABASE_URL znajdowała się w pliku schema.prisma. Obecnie ta konfiguracja połączenia znajduje się w pliku prisma.config.ts.

Stworzony kształt:

// 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"),
  },
});

Co się zmieniło?

• env("DATABASE_URL") już nie jest zadaniem schematu.
• Konfiguracja związana ze środowiskiem przenosi się do nowego pliku.
• schema.prisma pozostaje skupiony na modelach.

2. Naprawa problemu z katalogiem głównym tsconfig.json

Jeśli tsconfig.json zawiera:

"rootDir": "./src"

TypeScript odrzuca plik prisma.config.ts znajdujący się poza katalogiem src. Należy rozszerzyć katalog główny:

"rootDir": "./"

3. Migracja i generowanie klienta

Gdy modele już istnieją:

npx prisma migrate dev
npx prisma generate

Blok generujący schematu wskazuje klientowi drogę do źródeł kodu:

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

Proces generowania może wyglądać poprawnie aż do utworzenia obiektu PrismaClient.

4. Najbardziej mylący błąd: „Oczekiwano 1 argumentu, otrzymano 0”

Taki sposób tworzenia obiektu bez argumentów:

const prisma = new PrismaClient();

Importuj PrismaClient z wygenerowanego modułu client – a nie z pliku klasy siostrzanej. Mimo to Prisma 7 może odrzucić zero argumentów:

Expected 1 argument, but got 0.

Stare tutoriale nadal pokazują konstruktor bez argumentów. Analiza wygenerowanych plików client / class pokazuje, że konstruktor teraz wymaga konfiguracji, w tym:

accelerateURL

5. Prezentacja accelerateURL (nowość w Prisma 7)

Prisma 7 ściśle integruje się z Prisma Accelerate – globalnym cache’owaniem zapytań oraz zarządzaniem pulą połączeń. Accelerate ma na celu:

• cache’owanie zapytań na poziomie globalnym
• zmniejszenie opóźnień
• zarządzanie pulą połączeń dla rozwiązań serverless

W tym trybie PrismaClient wymaga pola accelerateURL.

6. Prisma dostarcza teraz własną chmurową bazę danych

Panel sterowania Prisma może:

• stworzenie bazy danych
• wygenerowanie klucza API Accelerate
• dostarczenie wartości accelerateURL dla klienta

Praktyczna trudność: zwykłe adresy URL w stylu Neon, które zaczynają się od:

" postgresql:// "

nie spełniają wymaganych protokołów Accelerate:

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

Niespójność powoduje błędy dotyczące:

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

7. Ostateczna konfiguracja PrismaClient (Prisma 7)

Przykład funkcjonalnego rozwiązania:

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());

Czym jest $extends?

$extends() umożliwia dodanie funkcji takich jak Accelerate do klienta.

8. Ważna uwaga: potrzebne są dwie zmienne środowiskowe

Konfiguracje Prisma 7 w tym trybie zazwyczaj wymagają:

DATABASE_URL → adres URL Accelerate

DIRECT_DATABASE_URL → bezpośrednia ścieżka połączenia z PostgreSQL

prisma.config.ts powinien używać bezpośredniego adresu URL do migracji:

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

Następnie przeprowadź migrację i utwórz plik ponownie:

npx prisma migrate dev
npx prisma generate

Ustawienia skoncentrowane na Accelerate zmieniają również nawyki operacyjne. Migracje oraz analiza wewnętrzna nadal wymagają bezpośredniej adresacji bazy danych, podczas gdy ruch aplikacyjny może przepływać przez endpoint Accelerate. Mieszanie tych dwóch adresów – umieszczanie bezpośredniej adresacji Postgres tam, gdzie wymagana jest adresa Accelerate, lub odwrotnie – powoduje błędy, które nie wydają się związane z edytowanym kodem aplikacji. Upewnij się, że obie wartości są jasno oznaczone w przykładach pliku .env, oraz sprawdź szybko podczas uruchamiania, czy prefiks protokołu nie jest błędny.

Dla zespołów przechodzących z Prisma 6 należy oczekiwać listy kontrolnej, a nie natychmiastowej aktualizacji: dodaj plik prisma.config.ts, w razie potrzeby rozszerz pole rootDir, przestań tworzyć obiekt PrismaClient bez żadnych argumentów, gdy używany jest Accelerate, włącz instrukcję $extends(withAccelerate()) oraz rozdziel zmienne środowiskowe. Gdy ta lista kontrolna stanie się częścią nawyku, codzienne modelowanie znów będzie wydawać się znajome.

Wniosek

Zmiany w Prisma 7 – takie jak plik prisma.config.ts, obowiązkowe argumenty klienta, accelerateURL oraz $extends – są słabo opisane w dokumentacji Prisma 6. Gdy zasady URL w Accelerate oraz rozdzielanie środowisk staną się jasne, konfiguracja klienta staje się przewidywalna zarówno dla osób po raz pierwszy korzystających z SQL, jak i dla tych aktualizujących się z wersji 6.

Pozycje pokrewne

• Pierwsze kroki z Prismą w Node.js i PostgreSQL — Zainstaluj Prisamę, utwórz schemat w PostgreSQL, przeprowadź migracje, wygeneruj klienta oraz uruchom pierwsze zapytania odczytu i zapisu.
• Next.js Server Actions z Prisamą i PostgreSQL — Połącz Server Actions bezpośrednio z wspólnym klientem Prisamy i bazą PostgreSQL, dzięki czemu operacje CRUD nie wymagają tras API ani żądania od klienta.
• Prisma 7 z NestJS i adaptatorami drivera MySQL — Skonfiguruj klienta Prisamy 7 w języku TypeScript, plik prisma.config.ts oraz adapter MariaDB w ramach globalnego modułu NestJS.

Prisma kontra zapytania SQL dostosowane pod potrzeby w PostgreSQL — Używaj Prismy dla szybkiego tworzenia i edycji danych z typowaniem, a przechodź na zapytania SQL z parametrami, gdy konieczna jest większa kontrola przy łączeniach tabel, agregacjach lub korzystaniu z funkcji Postgresa.

Next.js, Tailwind i Prisma z Docker Postgres — Krok po kroku: utwórz aplikację Next.js w języku TypeScript, uruchom Postgresa w Dockerze, skonfiguruj Prisma migrate i seed, a następnie wyświetl dane użytkowników z komponentu serwerowego.