Konfiguracja Prismy 7 w projekcie Next.js 16 z TypeScriptem
Dowiedz się, jak zainstalować, skonfigurować i przenieść Prisma 7 z PostgreSQL w aplikacji Next.js 16, a następnie stworzyć klienta typu singleton, aby uniknąć wycieków połączeń.
To przewodnik pokazuje, jak skonfigurować Prisma 7 w aplikacji Next.js 16, która komunikuje się z bazą PostgreSQL, wykorzystując TypeScript oraz pnpm jako menedżer pakietów.
Krok 1: Dodanie pakietów Prisma
pnpm add prisma @prisma/client @prisma/adapter-pg
- prisma — narzędzie wiersza poleceń służące do uruchamiania migracji, generowania klienta oraz zarządzania schematem.
- @prisma/client — biblioteka klienta wygenerowana, do której bezpośrednio będzie się odwoływał kod aplikacji.
- @prisma/adapter-pg — adapter sterownika PostgreSQL wprowadzony przez Prisma 7 do połączenia z bazą Postgres.
Gdy te trzy pakiety zostaną zainstalowane, możesz rozpocząć konfigurację Prisma.
Krok 2: Uruchomienie Prisma
pnpm dlx prisma init
Uruchomienie tego skryptu tworzy podstawowe pliki i foldery niezbędne do rozpoczęcia pracy.
prisma.config.ts
prisma/
└── schema.prisma
Rozumienie pliku prisma.config.ts
W tym pliku znajdują się ustawienia potrzebne do działania Prismy, w tym informacje o sposobie połączenia z bazą danych oraz zachowanie generatora klienta.
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"],
},
});
Rozumienie pliku schema.prisma
Każda tabela, którą planujesz przechowywać w PostgreSQL, zostanie ostatecznie umieszczona tutaj jako definicja modelu.
generator client {
provider = "prisma-client"
output = "../lib/generated/prisma"
}
datasource db {
provider = "postgresql"
}
// models that You want to create
Krok 3: Wskazanie Prismie bazy danych
Prisma potrzebuje łańcucha połączenia, zanim będzie mogła w ogóle komunikować się z bazą danych. Możesz go uzyskać od dostawcy usług hostowanych, takiego jak Neon, lub uruchamiając lokalnie instancję Postgresa za pomocą Dockera.
DATABASE_URL="postgresql://username:password@localhost:5432/my_database"
Gdy tylko ta zmienna środowiskowa zostanie ustawiona, Prisma może uzyskać dostęp do twojej bazy danych.
Krok 4: Definicja początkowego modelu
Prisma Client nie może zostać wygenerowany, dopóki w schemacie nie będzie przynajmniej jednego modelu.
Ponieważ baza danych jest w tym momencie pusta, dodaj minimalny model-templat, aby Prisma miało z czym pracować.
model Test {
id Int @id @default(autoincrement())
}
Celem tutaj nie jest stworzenie sensownej tabeli — chodzi po prostu o dostarczenie generatorowi ważnego schematu, na podstawie którego może działać.
Krok 5: Zastosuj pierwszą migrację
Następnie przekształć ten schemat w rzeczywiste tabele bazy danych, uruchamiając migrację.
pnpm dlx prisma migrate dev
To pojedyncze polecenie automatycznie zajmuje się kilkoma rzeczami:
- Generuje nowy plik migracji.
- Zastosowuje tę migrację w skonfigurowanej bazie danych.
- Podtrzymuje synchronizację struktury bazy danych z tym, co jest zadeklarowane w
schema.prisma.
Gdy operacja zakończy się pomyślnie, tabela Test pojawi się w twojej bazie danych.
Krok 6: Generowanie klienta Prisma
Jedną z najważniejszych zmian w Prisma 7 jest to, że klient nie jest już generowany automatycznie.
Teraz musisz ręcznie uruchomić proces generowania.
pnpm dlx prisma generate dev
Gdy to się zakończy, Prisma tworzy w pełni typowany klient dostosowany do twojego schematu.
Ten klient udostępnia wszystkie metody potrzebne do zapytania i modyfikacji danych.
generated/
└── prisma/
Każdy model zdefiniowany w twoim schemacie jest teraz dostępny jako odrębna, typowana API w TypeScript.
Krok 7: Tworzenie singlu klienta Prisma
Zamiast tworzyć nowy instancję klienta Prisma przy każdym żądaniu, zgodnie z najlepszymi praktykami należy używać jednej wspólnej instancji w całym aplikacji.
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;
}
Dlaczego singiel jest tu ważny
Podczas rozwoju Next.js ciągle ponownie ładowuje moduły.
Jeśli przy każdym ponownym załadowaniu tworzony jest nowy PrismaClient, ostatecznie otwierasz znacznie więcej połączeń z bazą danych, niż zamierzałeś.
Jeśli tego nie skorygujesz, w końcu pojawi się błąd o podobnym charakterze:
Too many database connections
Użycie wzorca Singleton gwarantuje, że jedna instancja Prisma Client będzie istnieć przez cały czas trwania aplikacji.
To jest podejście zalecane przez samą Prismę dla projektów Next.js.
Krok 8: Używaj klienta we wszystkich częściach aplikacji
Gdy masz już dostępną wspólną instancję klienta, możesz ją importować z dowolnego miejsca w projekcie.
import { prisma } from "@/lib/prisma";
Od tego momentu każdy komponent serwerowy, ścieżka API lub akcja serwera ma bezpośredni dostęp do twojej bazy danych.
Aby uzyskać więcej informacji na temat tej konfiguracji, zapoznaj się z oficjalną dokumentacją Prismy dotyczącą integracji z Next.js, dostępną pod adresem prisma.io/docs/guides/nextjs.
Pozycje pokrewne
- Budowanie używalnych shablonów startowych dla Next.js w celu uniknięcia kodu pierwotnego — Dowiedz się, jak programista zastąpił powtarzalne czynności oczyszczania w Next.js rosnącym zestawem minimalistycznych shablonów startowych dla sklepów internetowych i stron docelowych.
- Migracja z Prisma na Drizzle: Opis sześciu miesięcy — Programista dzieli się rzeczywistymi wynikami pomiarów i kompromisami związanymi ze zmianą stosu PostgreSQL TypeScript z Prisma na Drizzle ORM.