Uruchomienie API NestJS i Prisma bez błędów związanych z relacjami lub P1001

Prawie każda funkcja backendu, którą zespół rozwija później – od autoryzacji po model wielu najemców i kontrolę dostępu opartą na rolach – opiera się na pierwszych kilku godzinach konfiguracji projektu. Jeśli zmienne środowiskowe, połączenie z bazą danych, relacje w schemacie oraz migracje zostaną źle skonfigurowane na początku, każda późniejsza prośba o integrację odziedziczy ten bałagan. Ten przewodnik opisuje proces uruchomienia API NestJS wspieranego przez Prismę i PostgreSQL, wyjaśnia trzy problemy, które najczęściej utrudniają osiągnięcie tego pierwszego etapu, oraz dostarcza listę kontrolną pomagającą stwierdzić, gdy fundamenty są faktycznie gotowe.

Jak wygląda ukończony proces bootstrapowania

Pomaga określić cel przed rozpoczęciem pracy z interfejsem wiersza poleceń. Proces bootstrapowania jest ukończony, gdy osoba przeglądająca kod może sklonować gałąź i potwierdzić obecność wszystkich poniższych elementów:

• Aplikacja NestJS napisana w TypeScript, która uruchamia się bez błędów

Prisma połączona z bazą danych PostgreSQL

Konfiguracja ładowana ze zmiennych środowiskowych, a nie z wartości hard‑coded

Pierwotny zestaw modeli danych odzwierciedlający domenę

Migracja, która może być bezproblemowo zastosowana do pustej bazy danych

Skupiony pull request, który reszta zespołu może przejrzeć i połączyć

Ograniczenia są celowo wąskie: NestJS i Prisma jako jedyne framework i ORM, PostgreSQL jako baza danych oraz istniejące konwencje zespołu dotyczące konfiguracji i Git.

Narzędzia

• Framework i język: NestJS z TypeScript
• Dostęp do danych: prisma (CLI) oraz @prisma/client (generowany klient zapytań)
• Konfiguracja: @nestjs/config
• Baza danych: lokalna instancja PostgreSQL
• Weryfikacja: narzędzie Prisma CLI w połączeniu z przeglądarką lub klientem API do żądania danych z punktów końcowych

Ustawianie szkieletu projektu

Najpierw utwórz nową aplikację za pomocą Nest CLI, a następnie dodaj Prisma i zainicjuj je w projekcie. Proces inicjalizacji tworzy katalog prisma/ przeznaczony na schematy i migracje, podczas gdy kod aplikacji znajduje się w katalogu src/.

Następnie utwórz plik .env zawierający wartość DATABASE_URL – ciąg łączenia do PostgreSQL, który jest odczytywany przez Prisma. Załaduj konfigurację za pomocą modułu @nestjs/config, aby aplikacja pobierała wartości z środowiska zamiast z literów rozrzuconych w kodzie. Upewnij się, że plik .env znajduje się na liście w pliku .gitignore; dodawanie prawdziwych danych uwierzytelniających już w pierwszym PR to łatwy błąd, którego trudno jest później naprawić.

Zanim napiszesz jakiekolwiek modele, upewnij się, że Prisma rzeczywiście może uzyskać dostęp do bazy danych. Jeśli chcesz bardziej szczegółowego opisu funkcjonowania Prismy, zobacz jak skonfigurować Prismę 7 z PostgreSQL w projekcie TypeScript Node.js oraz sprawdź aktualne dokumentację Prismy w celu uzyskania informacji specyficznych dla danej wersji.

Modelowanie pierwszych entytetów

Dla produktu typu multi-tenant rozsądnym punktem wyjścia jest schemat składający się z czterech modeli:

• Tenant – reprezentuje organizację korzystającą z systemu
• User – reprezentuje osobę, która się loguje
• Role – służy do podstawowego przydzielania ról w ramach tenanta
• Invite – służy do zapraszania nowych użytkowników do tenanta

Razem określają one to, od czego zależą późniejsze funkcjonalności: użytkownicy należą do najemców, pełnią określone role i trafiają dzięki zaproszeniom. Każda relacja wymaga pola po obu stronach, co jest przyczyną pierwszego błędu poniżej.

Gdy schemat zostanie zweryfikowany, uruchom początkową migrację, aby struktura bazy danych odpowiadała schematowi. Unikaj w niej eksperymentów, ponieważ każdy kolega z zespołu będzie ją stosować lokalnie.

Dodawanie punktu końcowego do sprawdzania stanu

Z strony API dodaj jeden kontroler, który exponuje adres /health i zwraca prosty komunikat OK. Wydaje się to banalne, ale pełni ważną funkcję: umożliwia to tobie, twojemu pipeline’owi CI oraz ostatecznie buforowi obciążeń lub orkiestratorowi tanie sposoby sprawdzenia, czy proces jest uruchomiony i obsługuje żądania.

Trzy błędy, które często blokują pierwszy etap

Prisma odrzuca relację bez odpowiadającego jej pola

Symptom: walidacja schematu nie udaje się, ponieważ brakuje pola odpowiadającego danej relacji.

Priyczyna: Prisma wymaga, aby relacje były zadeklarowane w obu modelach. Jeśli User odnosi się do Tenant, ale Tenant nie ma pola przedstawiającego jego użytkowników, z punktu widzenia Prismy schemat jest niekompletny.

Rozwiązanie: dodaj brakujące pola odniesień w powiązanych modelach, a następnie uruchom prisma format. Ten narzędzie normalizuje plik i może uzupełnić brakujące pola relacji, dlatego warto go uruchamiać po każdej modyfikacji schematu.

P1001: nie można połączyć się z serwerem bazy danych

Symptom: Prisma zgłasza kod błędu P1001 i nie może nawiązać połączenia z PostgreSQL.

Powód: zazwyczaj jedna z dwóch możliwości. Albo serwer PostgreSQL nie jest uruchomiony, albo port w DATABASE_URL nie odpowiada portowi, na którym serwer nasłuchuje.

Rozwiązanie: upewnij się, że proces bazy danych działa lokalnie, a następnie porównaj host i port w łańcuchu połączenia z rzeczywistą konfiguracją serwera.

Zapytanie o pull request, które wydaje się usuwać wszystko

Symptomy: osoba sprawdzająca otwiera PR i stwierdza, że wszystkie pliki w repozytorium zostały usunięte.

Powód: komit został wykonany z niewłaściwego stanu Git, więc różnica jest porównywana z czymś zupełnie innym niż to, co było zamierzone.

Rozwiązanie: zamiast próbować naprawić skomplikowaną historię zmian, utwórz nowy gałąź od prawidłowej bazy i zastosuj tylko te zmiany, które są zamierzone. Wykonanie polecenia git status oraz sprawdzenie wyników git diff w porównaniu z docelową gałęzią przed wysłaniem zmian pozwala wcześnie wykryć tego typu błędy.

Weryfikacja konfiguracji

Proces weryfikacji powinien być monotonnie powtarzalny:

• Zainstaluj i uruchom npx prisma migrate dev, a następnie upewnij się, że migracja przebiega bez błędów
• Zapuść serwer NestJS
• Otwórz adres /health w przeglądarce lub kliencie API i sprawdź odpowiedź typu OK

Gdy migracja zakończy się pomyślnie, a endpoint /health odpowie, fundamenty są gotowe do dodania kolejnej funkcjonalności.

Główne wnioski

• Traktuj strukturę początkową jako element o określonych kryteriach przyjęcia, a nie jako tymczasowe narzędzie.

Zadeklaruj każdą relację Prisma po obu stronach i pozwól prisma format utrzymać schemat w uporządkowanym stanie.

Gdy zobaczysz P1001, sprawdź najpierw, czy PostgreSQL jest uruchomiony oraz czy port w DATABASE_URL jest poprawny, zanim będziesz debugować cokolwiek innego.

Koniec punktu sprawdzającego stan aplikacji zajmuje zaledwie kilka minut, ale przynosi korzyści w postaci testów CI, monitoringu oraz procesów wdrażania.

Małe, skoncentrowane prośby o pull request z czystą historią zmian stanowią część pracy inżynierskiej, a nie coś dodanego później.

Pozycje pokrewne

• Wdrażanie NestJS na Bun i Prisma 7 do Cloud Run bez błędów kompilacji — Działający pipeline GitHub Actions do wysyłania aplikacji NestJS na Bun z Prisma 7 i Neon do Cloud Run, wraz z poprawkami dotyczącymi Dockera i połączeń, które sprawiają problemy zespołom.
• Przewodnik po MovieVault: API do listy obserwowanych filmów z Express 5, Prisma 7 i JWT — Specyfikacja ćwiczenia typu full-stack z wyznaczonym czasem realizacji oraz backend oparty na Express, Prisma i JWT, wraz z notatkami dotyczącymi sprawdzania uprawnień, mechanizmów kaskadowych i obsługi błędów.