Настройка Prisma 7 у проекте Next.js 16 з TypeScript
Выявіце, як установіць, налаштаваць і перайсці на Prisma 7 з PostgreSQL у прыкладе аплікацыі Next.js 16, а пасля створыце кліент-сінглтон, каб узбегчыць витэканне з’яносоў.
У гэтым карце паказана, як наладзіць Prisma 7 у прыемлі Next.js 16, які взаўмадзейнае з PostgreSQL, выкарыстоўваючы TypeScript і pnpm як менеджар пакетаў.
Шаг 1: Дадзіце пакеты Prisma
pnpm add prisma @prisma/client @prisma/adapter-pg
- prisma — інструмент у лінійным рэжыме, які будзе выкарыстоўвацца для запуску міграцый, стварэння кліента і керавання схемай.
- @prisma/client — створаная бібліятэка кліента, яку будзе безпасячна вызываць код вашага прыемлі.
- @prisma/adapter-pg — адаптар драйвера PostgreSQL, які быў уведжаны Prisma 7 для падключэння да Postgres.
Пасля установкі гэтых трох пакетаў вы готавы запусціць наладку Prisma.
Шаг 2: Запуск Prisma
pnpm dlx prisma init
Заўядзенне гэтага кода ствараяць базовыя файлы і папкі, якія неабходны для пачатку работы.
prisma.config.ts
prisma/
└── schema.prisma
Розумэнне prisma.config.ts
У гэтым файле знаходзяцца настройкі, неабходныя Prisma для роботы, уключаючы спосаб з’ўязку з вашай базой дадзенаў і працэс генеравання кліента.
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"],
},
});
Розумэнне schema.prisma
Кожныя табелі, якія вы плануеце зберагаць у PostgreSQL, згодна будуць практычна як апісанні модэляў у гэтым файле.
generator client {
provider = "prisma-client"
output = "../lib/generated/prisma"
}
datasource db {
provider = "postgresql"
}
// models that You want to create
Шаг 3: Настаўкі Prisma на вашу базу дадзенаў
Prisma патрэбна строчка з’ўязку, каб магчыма было весты са вашай базой дадзенаў. Яе можна атрымаць у адпаведнам прадаўцы сервісаў, такім как Neon, або запусканнем экзампляра Postgres локальна за дапамогою Docker.
DATABASE_URL="postgresql://username:password@localhost:5432/my_database"
Як толькі гэтая зменная сераўысу будзе заданая, Prisma зможа прайсці да вашай базы дадзенаў.
Шаг 4: Апісанне пачатковага модэля
Prisma Client не можа быць створаны, пакуль у схеме не існуе хаця бы адного модэлю.
Паколькі база дадзеных зараз яшчэ порожняя, трэба дадзіць мінімальны модэль-заместак, каб Prisma мела на шта працаваць.
model Test {
id Int @id @default(autoincrement())
}
Мета тут — не стварыць значычную табліцу, а проста запропанаваць генератору валідную схему для будовы.
Шаг 5: Застосаваць вашу першую міграцыю
Далей трэба ператворыць гэтую схему на рэальныя табліцы базы дадзеных, запускнуўшы міграцыю.
pnpm dlx prisma migrate dev
Эты ўсьмох команда автаматычна адрабоўвае калькі задач:
- Яна стварае новы файл міграцыі.
- Яна застосоўвае гэтую міграцыю да вашай настроеныя базы дадзеных.
- Яна падтрымлівае сінхронізацыю структуры вашай базы дадзеных з тым, што задана ў
schema.prisma.
Калі ёна успешна завершыцца, табліца Test будзе існаваць у вашай базе дадзеных.
Крок 6: Стварэнне кліента Prisma
Адна з самых значных змян у Prisma 7 — гэта тое, што кліент больш не ствараецца для вас аўтаматычна.
Тепер вам неабходна явна запускать процес стварэння.
pnpm dlx prisma generate dev
Пасля таго, як гэта завершыцца, Prisma стварае кліент з абсолютным типаваннем, прыстосаваны да вашага схэмы.
Этот кліент адкрывае ўсія методы, якія вам патрабуюцца для запытанняў і змены дадзэнняў.
generated/
└── prisma/
Кожны модэль, заданы ў вашай схэме, тепер адкрываецца як самастоятельны API з типаваннем у TypeScript.
Крок 7: Стварэнне кліента Prisma у формате Singleton
У змену на стварэнне новага кліента Prisma за кожны запыт, наявнасць адной спільнай інстанцыі ў всім праекте є кращой практыкай.
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;
}
Чаму тут важліва інстанцыя Singleton
Падчас разработкі Next.js постаўляе модулі з перзапускам у рэальны час.
Якщо з кожнай перзагрузкі буда ствараны новы PrismaClient, вы будете ствараць значна большая колькасць з’ўязкаваў з базай дадзеных, чым планавалі.
Якщо гэта не карміцца, згодна часу гэта выражаецца ў падобных да гэтага адказах пра аблык:
Too many database connections
Іспользованне шаблону Singleton гарантуе, што адна інстанцыя Prisma Client застаецца пра весь час жыцця аплікацыі.
Гэты падход сам Prisma рекамендуе для проектаў Next.js.
Крок 8: Іспользаваць кліента ў всій аплікацыі
Калі ўжо є спяльная інстанцыя кліента, вы можете імпортаваць яе з будзь-каго месца ў вашым проекте.
import { prisma } from "@/lib/prisma";
З гэтага момента будзь-які серверны компонент, маршрут API або дзеянне сервера маюць прымітны доступ да вашай базы дадзеных.
Для абавесці пра гэтыя настройкі больш дакладна, абмерцавайце офіцыяльную дакументацыю Prisma па інтеграцыі з Next.js, якая доступна на прыёмку prisma.io/docs/guides/nextjs.
Супаўязаная літэратура
- Стварэнне павтораспрытных шаблонаў-стартараў для Next.js, каб ухіліцца ад базовага коду — Дазвольце дакладна разабраць, як разработчык заменіў павтараючыяся процесы чысткі коду ў Next.js на набор шаблонаў-стартараў, якія зменшуюць колькасць неабавязковага коду.
- Міграцыя з Prisma на Drizzle: аналіз за шасць месцаў — Разработчык дзеліцься рэальнымі показнікамі і наследкамі пераходу з стакана PostgreSQL TypeScript, які выкарыстоўваў Prisma, на Drizzle ORM.