Запуск API NestJS та Prisma без помилок relation чи P1001

Майже кожна функція бекенду, яку команда розробляє пізніше — від автентифікації до моделі багатьох орендарів та контролю доступу за ролями — ґрунтується на роботі, виконаній протягом перших кількох годин налаштування проекту. Якщо змінні середовища, підключення до бази даних, взаємозв’язки схем та процеси міграцій будуть налаштовані недбало з самого початку, кожен наступний pull request успадкує цей безлад. У цьому посібнику описано процес створення API на NestJS з використанням Prisma та PostgreSQL, пояснюються три проблеми, які найчастіше заважають досягти першої віхи, а також наведений чек-лист для перевірки того, чи справді закінчено будівництво основи.

Як виглядає готовий процес стартування

Корисно визначити мету ще до того, як почати працювати з CLI. Процес стартування вважається завершеним, коли перевіряючий може клонувати гілку та підтвердити наявність усього наступного:

• Додаток NestJS, написаний на TypeScript, який запускається без помилок

Prisma підключений до бази даних PostgreSQL

Конфігурація завантажується з змінних середовища, а не з жорстко закодованих значень

Початковий набір моделей даних, які відображають структуру домену

Міграція, яка може бути легко застосована до порожньої бази даних

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

Обмеження встановлені навмисно обмежено: NestJS та Prisma як єдині фреймворк та ORM, PostgreSQL як база даних, а також існуючі у команди стандарти щодо конфігурації та Git.

Набір інструментів

• Фреймворк та мова: NestJS з TypeScript
• Доступ до даних: prisma (CLI) та @prisma/client (генерований клієнт запитів)
• Конфігурація: @nestjs/config
• База даних: локальна інстанція PostgreSQL
• Перевірка: Prisma CLI, а також браузер чи клієнт API для виклику кінцевих точок

Налаштування скелета проекту

Спочатку створіть новий додаток за допомогою Nest CLI, потім додайте Prisma та ініціалізуйте його всередині проекту. Під час ініціалізації створюється каталог prisma/ для схеми та міграцій, тоді як код додатку залишається у каталозі src/.

Далі створіть файл .env, який міститиме значення DATABASE_URL — рядок підключення до PostgreSQL, який читає Prisma. Завантажуйте конфігурацію через модуль @nestjs/config, щоб додаток отримував значення з середовища, а не з літералів, розкиданих у коді. Переконайтеся, що файл .env включений до списку у .gitignore; збереження справжніх облікових даних у першому ж PR — це поширена помилка, яку важко виправити.

Перш ніж писати будь-які моделі, переконайтеся, що Prisma дійсно може отримати доступ до бази даних. Якщо ви хочете більш детального огляду функцій Prisma окремо, перегляньте інструкції з налаштування Prisma 7 з PostgreSQL у проекті TypeScript Node.js, а також ознайомтесь із поточною документацією Prisma для отримання інформації, специфічної для конкретної версії.

Моделювання перших ентитетів

Для продукту з підтримкою кількох користувачів розумною початковою схемою є наявність чотирьох моделей:

• Tenant — представляє організацію, яка використовує систему
• User — представляє особу, яка увійшла в систему
• Role — використовується для базового призначення ролей у межах одного Tenant
• Invite — використовується для залучення нових користувачів до проекту

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

Як тільки схема буде перевірена, запустіть початкову міграцію, щоб структура бази даних відповідала схемі. Уникайте експериментів, адже кожен колега буде застосовувати її локально.

Додавання кінцевої точки стану

З боку API додайте один контролер, який відкриває доступ до /health та повертає просте значення OK. Це здається простим, але має реальну мету: воно дає вам, вашій CI-пайплайну, а згодом і балансуючому пристрою чи оркестратору можливість легко перевірити, чи процес працює та обробляє запити.

Три поширені помилки, які часто блокують досягнення першої мети

Prisma відхиляє взаємодію без відповідного поля з іншого боку

Симптом: перевірка схеми провалюється з повідомленням про відсутність протилежного поля у зв’язку.

Причина: Prisma вимагає, щоб зв’язки були оголошені в обох моделях. Якщо User посилається на Tenant, але у Tenant немає поля, яке б вказувало на його користувачів, з точки зору Prisma схема є неповною.

Виправлення: додайте відсутні поля зворотного посилання у пов’язані моделі, а потім запустіть prisma format. Цей інструмент нормалізує файл та може автоматично додати відсутні поля зв’язків, тому доцільно запускати його після кожної зміни схеми.

P1001: неможливо досягти сервера бази даних

Симптом: Prisma повідомляє про код помилки P1001 та не може під’єднатися до PostgreSQL.

Причина: зазвичай одна з двох можливостей. Або сервер PostgreSQL не працює, або порт у DATABASE_URL не збігається з портом, на якому прослуховує сервер.

Виправлення: переконайтеся, що процес бази даних працює локально, потім порівняйте хост та порт у рядку підключення з фактичною конфігурацією сервера.

Запит на зміни, який, здається, видаляє все

Симптом: рецензент відкриває запит на зміни та бачить, що всі файли у репозиторії були видалені.

Причина: коміт було створено з неправильного стану Git, тому результати порівняння відрізняються від того, що було заплановано.

Виправлення: замість спроби виправити заплутану історію змін створіть нову гілку від правильної бази та застосуйте лише бажані зміни. Виконання команди git status та перегляду git diff порівняно з цільовою гілкою перед пушем дозволяє рано виявити такі помилки.

Перевірка налаштувань

Перевірка має бути однаковою щоразу:

• Виконайте npx prisma migrate dev та переконайтеся, що міграція виконується без помилок
• Запустіть сервер NestJS
• Відкрийте /health у браузері чи клієнті API та перевірте наявність відповіді OK

Якщо міграція завершується без проблем, а ендпоінт стану відповідає, основа готова до реалізації наступної функціональності.

Ключові висновки

• Розглядайте процес ініціалізації як результат, що має чіткі критерії прийняття, а не як тимчасову структуру.

Оголошіть кожну зв’язку Prisma з обох боків та дозвольте prisma format підтримувати схему у порядку.

Якщо ви бачите P1001, спочатку перевірте, чи працює PostgreSQL та чи правильний порт у DATABASE_URL, перш ніж починати дебагування чогось іншого.

Ендпоїнт стану коштує кількох хвилин, але допомагає під час перевірок у CI, моніторингу та розгортання.

Невеликі, зосереджені pull-запити з чистою історією є частиною інженерної роботи, а не щось додаткове.

Пов’язана література

• Розгортання NestJS на Bun та Prisma 7 у Cloud Run без помилок під час компіляції — працюючий пайплайн GitHub Actions для розгортання додатку NestJS на Bun з Prisma 7 та Neon у Cloud Run, а також виправлення проблем з Docker та підключенням, які створюють труднощі у командах.
• MovieVault Walkthrough: API для списку перегляду з Express 5, Prisma 7 та JWT — опис завдання для роботи з повним стеком із часовими обмеженнями та його бекенд на Express, Prisma та JWT, із примітками щодо перевірки прав власності, каскадних дій та обробки помилок.