Налаштування Prisma 7 з використанням Accelerate URLs

Prisma 7 (випущений 19 листопада 2025 року) настільки змінив конфігурацію, що багато посібників для Prisma 6 більше не є актуальними. Наведені нижче примітки базуються на читанні документації, перевірці створених файлів оголошень та усуненні помилок, які з’являються під час першої налаштування SQL/Postgres — особливо для тих, хто раніше працював з MongoDB та Mongoose.

Шлях оновлення є особливо складним для тих, хто починає з нуля: перше успішне створення об’єкта PrismaClient у старих матеріалах часто є неправильним вже з першого дня роботи з версією 7. Розглядайте аргументи конструктора та файли конфігурації як частину основної моделі розуміння, а не як додаткові складні теми.

1. Перша значна зміна: prisma.config.ts

Після встановлення Prisma створює новий кореневий файл:

prisma.config.ts

У попередніх версіях параметр DATABASE_URL знаходився всередині файлу schema.prisma. Тепер ця конфігурація з’єднання розташована у файлі prisma.config.ts.

Сформована форма:

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

Що змінилося?

• env("DATABASE_URL") більше не є завданням схеми.
• Конфігурація, пов’язана з середовищем, переміщується до нового файлу.
• schema.prisma залишається зосередженим на моделях.

2. Виправлення проблеми з кореневим каталогом tsconfig.json

Якщо tsconfig.json містить:

"rootDir": "./src"

TypeScript відхиляє prisma.config.ts, розташований поза каталогом src. Розширте кореневий каталог:

"rootDir": "./"

3. Міграція та створення клієнта

Після створення моделей:

npx prisma migrate dev
npx prisma generate

Блок генератора схеми вказує клієнту на джерело коду:

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

Процес генерації може виглядати нормальним до моменту створення об’єкта PrismaClient.

4. Найбільш заплутана помилка: “Очікується 1 аргумент, отримано 0”

Цей спосіб створення об’єкта без аргументів:

const prisma = new PrismaClient();

Імпортуйте PrismaClient з генерованого модуля client — а не з сусіднього файлу класу. Навіть у цьому випадку Prisma 7 може відхилити запуск із нульом аргументів:

Expected 1 argument, but got 0.

У старіших посібниках досі показують конструктор без аргументів. Огляд генерованих файлів client / class показує, що тепер конструктор очікує налаштувань, зокрема:

accelerateURL

5. Представлено accelerateURL (новинка Prisma 7)

Prisma 7 тісно інтегрується з Prisma Accelerate — це глобальне кешування запитів та пулінг з’єднань. Метою Accelerate є:

• глобальне кешування запитів
• зниження затримок
• створення пулів з’єднань для серверлесс-рішень

У цьому режимі PrismaClient вимагає наявності параметра accelerateURL.

6. Prisma тепер пропонує власну хмарну базу даних

Панель керування Prisma може:

• створити базу даних
• отримати ключ API Accelerate
• надати accelerateURL для клієнта

Практична проблема: звичайні URL у стилі Neon, які починаються з:

" postgresql:// "

не відповідають очікуваним протоколам Accelerate:

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

Невідповідність спричиняє помилки, пов’язані з:

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

7. Остаточна налаштування PrismaClient (Prisma 7)

Функціональний патерн:

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

Що таке $extends?

$extends() додає такі функції, як Accelerate, до клієнта.

8. Важлива примітка: потрібні дві змінні середовища

Налаштування Prisma 7 у цьому режимі зазвичай вимагають:

DATABASE_URL → URL Accelerate

DIRECT_DATABASE_URL → пряма строка підключення до PostgreSQL

prisma.config.ts має використовувати прямий URL для міграцій:

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

Потім здійсніть міграцію та створіть знову:

npx prisma migrate dev
npx prisma generate

Налаштування, орієнтовані на прискорення, також змінюють робочі звички. Для міграцій та аналізу все ще потрібен прямий URL бази даних, тоді як трафік додатку може проходити через кінцеву точку Accelerate. Змішування цих двох URL — використання прямого URL Postgres там, де потрібен URL Accelerate, або навпаки — призводить до помилок, які не мають відношення до рядка коду додатку, який переглядається. Зберігайте ці два значення з чіткими назвами у прикладах файлу .env, і якщо будь-який з префіксів протоколу є неправильним, додаток має швидко зупинитися під час запуску.

Для команд, які мігрують з Prisma 6, очікуйте перелік кроків, а не миттєве оновлення: додайте prisma.config.ts, за потреби розширте rootDir, при використанні Accelerate припиніть створювати PrismaClient з нульовими аргументами, підключіть $extends(withAccelerate()) та розділіть змінні середовища. Коли цей перелік кроків стане частиною вашої робочої практики, щоденна робота з моделюванням знову стане знайомою.

Висновок

Зміни в Prisma 7 — prisma.config.ts, обов’язкові аргументи клієнта, accelerateURL та $extends — погано описані в матеріалах до Prisma 6. Як тільки правила URL Accelerate та розділення середовищ стануть зрозумілими, налаштування клієнта стане передбачуваним як для нових користувачів SQL, так і для тих, хто оновлюється з версії 6.