Настройка Prisma 7 з PostgreSQL у проекте на TypeScript і Node.js

Выконанне касоўкі запуску Prisma ў звычным проекте TypeScript для Node.js часта заканчываецца великай колькасцю памылак компілятора ўжо перад тым, як будзе выкарыстоўвана хоць адна запытка. Проблемы не ў вашых моделях; яны вынікаюць з таго, як компілятор TypeScript, новы файл налаштавання Prisma і створены кліент взаімадзейнуюць з традыцыйным структурам src/dist. У гэтым кяліку пояснююцца тры памылкі, з якімі вы, верагодна, станэце супрацоўваць, прычыны їх вынікнення, а таксама пасляэтапная наладка з PostgreSQL, якая дазволяе без проблемаў выконваць компіляцыю. Prisma 7 змяніў калькі значэнняў за замовчаннем, таму пераканайцеся, што вы чыталі актуальную документацыю Prisma, каб з’ясаваць, чы не змінілася ў чым-небудзь справа з моменту напісання гэтага матерыялу.

Тры памылкі, якія спантовуюць новую наладку

Адреса з’ўязку, увведзеная як строка або не вызначаная

У файле prisma.config.ts адреса базы дадзеных зазвычай чытаецца за дапамою process.env.DATABASE_URL. TypeScript класіфікуе кожную зменную сяродовышча як string | undefined, таму што нічога не гарантуе, што яна будзе заданая пад час выконання. Конфігурацыя чакае звычайны string, таму кампайлер адхоўляе такое прызначэнне.

prisma.config.ts за межами корневага каталогу

Тыповы проект на TypeScript задае rootDir як src, а outDir — як dist. Prisma стварае файл prisma.config.ts у корані проекту, і за замовчанням кампайляр уключае ўсі знайдзеныя файлы .ts. Пасля чаго ён паведамляе пра проблему, калі файл, які знаходзится за межамі rootDir, ўключаецца ў програму. Перыявленне канфігурацыі ў src могла б паспакоўваць гэтую памылку, але гэта неправільны спосаб рашэння: src прызначаны для коду аплікацыі, такога як маршруты, кантролеры і механізмы доступу да дадзэнняў, а не для канфігурацыі інструментаў.

Створаны кліент за межамі корневага каталогу

То ж самае выходзіць з створаным кліентам. Якщо Prisma запісвае яго ў падметку generated/prisma у корні проекту, кампайлер знову знаходзіць файлы TypeScript за межамі rootDir. Перакладанне створанага коду ў src таксама ёстся пасляднім выборам, адколі гэта є рэзультат запуску prisma generate, а не выхідны код, які трэба падтрымваць.

Якщо гэтыя проблемы не рашыць, яны заважаюць запуску проекту. Іншы непрыемны наследк – скомпіляваны JavaScript для prisma.config.ts можа застацца за межамі dist, чым заплямавае репазітарый. Устранэнне проблем по адной часто прыводзіць да новых, таму кращэ выправіць усю структуру проекта цалкам.

Шаг 1: стварыць проект і установіць залежнасці

Пачатакніце з порожняго проекта TypeScript. Установіце кампляйзар, tsx для безпасэчнага запуску TypeScript, а таксама значэнні типаў для Node, пасля чаго створыце файл tsconfig.json:

npm init
npm install typescript tsx @types/node --save-dev
npx tsc --init

Далей установіце Prisma. Командна лінія і значэнні типаў pg ёсць залежнасцямі для разработкі; кліент, адаптар драйвера PostgreSQL, драйвер pg і dotenv — залежнасцямі для выканання:

npm install prisma @types/pg --save-dev
npm install @prisma/client @prisma/adapter-pg pg dotenv

У гэтым случае важліва пакетная структура @prisma/adapter-pg. У Prisma 7 кліент вяршыць роботу з базай дадзеных через адаптар драйвера на JavaScript, таму яму пасылаецца настроеныя з’ѐеднанне з pg, а не толькі URL, указанный у схеме.

Шаг 2: настроўка ES-модуляў і структуры кампляйзара

У файле package.json пакет трэба пазначыць як ES-модуль:

{
  "type": "module"
}

Пасля таго задаюцца катэгорыяс źródła і выходу ў файле tsconfig.json, а таксама ствараецца папка src:

"rootDir": "./src",
"outDir": "./dist",

Шаг 3: ініцыялізацыя Prisma

Запускайце CLI аднойчы (гэта проста выведзе доступныя каманды і паказае, што установка працюе):

npx prisma

Пасля таго ініцыялізуецца Prisma для PostgreSQL:

npx prisma init --datasource-provider postgresql --output ../generated/prisma

Гэта стварае файл prisma.config.ts, папку prisma, якая містіць файл schema.prisma, а таксама файл .env з адресайом базы дадзеных. Параметр --output задае месца, дзе будзе створены кліент; у шагу 4 знова рассматрываецца гэты выбор. Самэўсёле пасля гэтага шагу з’являюцца вышэўказаныіяі бягі.

Шаг 4: выправленне канфігурацыі

Тры цялеспрямованыя змены выправляюць усі тры бягі.

Чытанне адреса з дапамогай функцыі env пры Prisma

Заменіце вмест на prisma.config.ts на наступны. эты файл напісаны на TypeScript, хоць у фрагменте прыводзіцца інша інформацыя.

import "dotenv/config";
import type { PrismaConfig } from "prisma";
import { env } from "prisma/config";

export default {
  schema: "prisma/schema.prisma",
  migrations: {
    path: "prisma/migrations",
    seed: "tsx prisma/seed.ts",
  },
  datasource: {
    url: env("DATABASE_URL"),
  },
} satisfies PrismaConfig;

Што трэба з’явіць:

• import "dotenv/config" чытае файл .env раней, чым ён можа быць прачытаны іншымі частямі коду. У Prisma 7 гэты файл больш не завантажваецца автоматычна ў такой настройцы.
• env("DATABASE_URL") з модуля prisma/config вяртае значэння типу string, і якщо зменная не існуе, выдае чытальныя паведамлення пра абэрасію, што усунеляе можлівасць падачы значэння типу string | undefined.
• satisfies PrismaConfig адрабатвае об’ект на наявнасць патрэбных умов, не расширюяйчы його тип.
• У настройках таксама вказываецца, дзе знаходзяцца схемы і міграцыі, а таксама які каманды запускаецца для заполнення базы дадзенаў.

Абмежыце тое, што включае компіляр

Дадзіце элемент include у канцы файла tsconfig.json:

"include": ["src"],

Гэта паведамляе кампайлеру ствараць толькі файлы, якія знаходзяцца ў падпапке src. Prisma CLI яшчэ чытае файл prisma.config.ts сама, але tsc перестае спрацоўваць яго як частку вашага програмнага коду, таму зникае памылка rootDir і жаданага JavaScript не выдаўаецца за межы папкі dist.

Стварыце кліент у node_modules

На завершанне зменіце файл schema.prisma, ўбедзіўшыся, што генератор не будзе выкарыстоўваць жаданыя спецыяльныя шляхі выходу:

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"

Без параметра output генератор prisma-client-js запісвае кліент у каталог node_modules, таму нічага згенераванага не застоіцца ў корні проекту, і праблема з параметрам rootDir зникае. Фрагмент коду заканчваецца пасля элемента provider для джэранта даных; блок трэба закрыць клаўзурамі. У Prisma 7 адреса з’яўлення ў базе дадзеных знаходзіцца ў файле prisma.config.ts, а не ў схеме.

Згадайце, што гэта ўзаемная замена. Новейшы генератор Prisma — prisma-client — прадуманы з урахоўваннем чыста вызначанаг каталогу выходных файлоў, тады як prisma-client-js є старэйшым генераторам. Якщо вы выберазеце новейшы варыянт, трэба заставіць выходны каталог параду src і не включаць яго ў процес компіляцыі за дапамогою параметра include, як паказана вышэй.

Шаг 5: дадзіце адресу базы дадзеных і адконфігуруйце міграцыі

Запішыце странг з’яўлення ў файл .env. Значэнне, якое паказана, ўжо є місцем для заполнення; выкорыстаўце свой базовы дадзеныях, і ніколі не зберагаўце рэальных значэнняў:

DATABASE_URL="postgresql://johndoe:randompassword@localhost:5432/mydb?schema=public"

Задаце своія модэлі ў файле schema.prisma, а пасля створыце і застосаваце першую міграцыю:

npx prisma migrate dev --name init

Шаг 6: стварэнне кліента

Створыце типаванага кліента на адной з основах схемы:

npx prisma generate

Запускайце гэты крок знову ўсё час, калі змянюецца схема, ўпэўніваючыся, што типы застаюцца сінхроннымі з вашымі модэлямі.

Шаг 7: стварэнне спяльнай інстанцыі Prisma

Створыце файл src/lib/prisma.ts, куды будзе зберагвацца адні кліент для всей прыкладной програмы. У гэтым файле ствараецца адаптар для PostgreSQL на адной з основаў странга з’яўлення і ён перадаецца класу PrismaClient. Гэты код таксама напісаны на TypeScript:

import "dotenv/config";
import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "../../node_modules/@prisma/client/index.js";

const connectionString = `${process.env.DATABASE_URL}`;

const adapter = new PrismaPg({ connectionString });
const prisma = new PrismaClient({ adapter });

export default prisma;

Кліент імпортуецца чераз явны абсалютны шлях у папку node_modules:

import { PrismaClient } from "../../node_modules/@prisma/client/index.js";

Этый шлях работае, таму ў кроку 4 кліент быў створаны ў папцы node_modules. У большасці налаштаванняў простае пазначэнне @prisma/client ведае да таго ж пакету, таму спачатку спробуйце гэта; перайдзіце да явнага шляху толькі тады, калі налаштаванні рашэння модуляў гэта выклекаюць.

Адна з прычын проблем у гэтым фрагменте: абгортаванне process.env.DATABASE_URL у строчку-шаблон ператварае відсутняе значэнне на буквальны текст "undefined", што пазней вызывае плутаныя памылкі з’ўязку. Короткая перапалох, якая кідае памылку, калі зменная відсутняя, робіць проблемы зрозумелымі.

Тепер імпортуйце гэты экземпляр там, дзе вам патрабуецца доступ да базы дадзеных, напрыклад у кантролерах чы сэрвісах, і выконвуйце вашы запиты CRUD чераз яго. Зберагчы аднаго спільнага кліента, вы ухіліваецеся ад стварэння новага пула з’ўязкаў для кожнага файла.

Ключовыя выводы

• Большая частка памылак установкі Prisma 7 ў TypeScript выходзіць з правіл rootDir кампайляра, а не з самага Prisma.
• Ўжывайце env() з prisma/config адзінаваўшы яго з dotenv/config, каб URL базы дадзеных быў правильна типаваны і явна заванесены.
• Абмежыце tsc за дапамою "include": ["src"], ўбачымаючы такім чынам, каб файлы інструментаў і створаны код не патраплялі ў процес зборкі.
• Зберагаеце створаныя кліенты праз src, у node_modules або ў папку выходных даўэнняў, якія ўключаны не будуць.
• Створыце аднаго спяльнага PrismaClient з адаптарам PrismaPg і пераканайцеся ў правільнасці строчкі з’яўлення звязку пад час запуску.

Якщо вы викорыстоўваеце Next.js замест простага сервісу Node.js, наша інструкцыя па налаштаванню Prisma 7 у проекте Next.js 16 на TypeScript пакрывае деталі, спецыфічныя для гэтага фреймворку.