Встановлення 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 не може бути створений, поки у схемі не існує принаймні одної моделі.
Оскільки на цьому етапі база даних ще порожня, додайте мінімальну модель-замінник, щоб у Prisma було з чим працювати.
model Test {
id Int @id @default(autoincrement())
}
Метою тут не є створення змістовної таблиці — це лише надання генератору коректної схеми для роботи.
Крок 5: Застосуйте першу міграцію
Далі перетворіть цю схему на справжні таблиці бази даних, виконавши міграцію.
pnpm dlx prisma migrate dev
Ця одна команда автоматично виконує кілька завдань:
- Вона створює новий файл міграції.
- Вона застосовує цю міграцію до налаштованої бази даних.
- Вона підтримує синхронність структури вашої бази даних із тим, що оголошено в
schema.prisma.
Як тільки це буде успішно завершено, таблиця Test з’явиться у вашій базі даних.
Крок 6: Створення клієнта Prisma
більше не генерується автоматично.
pnpm dlx prisma generate dev
generated/
└── prisma/
Крок 7: Створення одиничного клієнта 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;
}
Чому тут важливий одиничний клієнт
Якщо при кожному перезавантаженні створюється новий екземпляр 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.