Канфігурацыя Prisma 7 з викорыстаннем Accelerate URLs

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

Шлях апгрэйда ёсць особліва складным для тых, хто толькі пачынае: першая успешная стварэння об’екта PrismaClient у старых інструкцый часта выходзіць некоректной ў першы ж дзень роботы з версіяй v7. Аргументы канструктара і файлы з канфігурацыяй трэба спрыятаць як частку основнай моделі розумеў, а не як дапаможныя, прыглушаныя тэмы.

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

Блок генератора схемы направляе кліента да выканання з коду з src:

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 Postgres там, дзе трэба URL Accelerate, або наадворс — стварае выклікі, якія здаюцца несувязанымі з часткаю коду аплікацыі, якая выконвалася. Зберагаюце гэтыя два значэння з яснымі назвамі ў прыкладах .env і якнайшчыльней застосавуйце паўтарную памятку пры запуске, якщо хоць адна з прыметак протаколу ўскладнена.

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

Вывад

Новыя элементы Prisma 7 — prisma.config.ts, обав’язковыя аргументы кліента, accelerateURL і $extends — практычна не расглядзеныя ў матэрыялах Prisma 6. Калі правілы URL Accelerate і раздзеленыя сяродавысці стануць зрозумелымі, налаштаванне кліента стане прыемлемым як для тых, хто пачынае работаць з SQL, так і для тых, хто апгрэйдзіць з версіі 6.