Prisma na Windows: Przewodnik po najczęstszych błędach (i jak nie zwariować)

Windows przebył długą drogę, by stać się przyjaznym środowiskiem dla deweloperów backendowych, ale narzędzia wywodzące się z ekosystemu Node.js wciąż potrafią sprawić niespodziankę. Prisma, choć jest fantastycznym ORM-em, działa w oparciu o silnik napisany w Rust (Query Engine), co oznacza, że jest zależna od binariów systemowych. Na systemach uniksowych dzieje się to zazwyczaj transparentnie. Na Windowsie? Cóż, bywa różnie.

Jeśli utknąłeś przy komendzie npx prisma init lub twoja baza danych odmawia współpracy, prawdopodobnie trafiłeś na jedną z klasycznych pułapek specyficznych dla tego systemu. Oto jak sobie z nimi poradzić.

1. Blokada PowerShell: PSSecurityException

To zazwyczaj pierwszy mur, w który uderzają nowi użytkownicy po zainstalowaniu Prismy globalnie lub próbie uruchomienia skryptów inicjalizujących. PowerShell domyślnie blokuje wykonywanie niepodpisanych skryptów ze względów bezpieczeństwa. Jeśli widzisz czerwony komunikat o treści cannot be loaded because running scripts is disabled on this system, to właśnie to.

Rozwiązanie

Musisz zmienić politykę wykonywania skryptów (Execution Policy). Nie musisz otwierać systemu na oścież (Unrestricted), wystarczy poziom RemoteSigned, który pozwala na uruchamianie lokalnych skryptów, ale wymaga podpisu dla tych pobranych z sieci.

Uruchom PowerShell jako Administrator i wpisz:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Jeśli to nie pomoże, spróbuj używać npx przed każdą komendą (co i tak jest dobrą praktyką, by korzystać z wersji zainstalowanej w projekcie, a nie globalnie):

npx prisma studio

2. Koszmar z OpenSSL i brakującymi bibliotekami

Prisma potrzebuje OpenSSL do nawiązywania bezpiecznych połączeń z bazą danych. Na Linuxie i macOS biblioteki te są standardem. Na Windowsie często ich brakuje, albo zainstalowana jest wersja, której Prisma nie wspiera. Objawia się to błędami o braku pliku libssl lub libcrypto, albo enigmatycznym komunikatem, że silnik zapytań (Query Engine) nie mógł wystartować.

Wymuszenie odpowiedniego Binary Target

Często automatyczna detekcja platformy zawodzi. Możesz ręcznie wskazać Prismie, jakich binariów ma używać w pliku schema.prisma. W sekcji generatora dodaj binaryTargets:

generator client {
  provider      = "prisma-client-js"
  binaryTargets = ["native", "windows"]
}

Po tej zmianie koniecznie uruchom ponownie npx prisma generate. Jeśli nadal masz problemy, upewnij się, że masz zainstalowany OpenSSL w systemie (np. przez Chocolatey lub instalator Git Bash, który często zawiera potrzebne biblioteki).

3. Pułapka "localhost" przy korzystaniu z Dockera

Scenariusz jest typowy: uruchamiasz bazę danych (Postgres lub MySQL) w kontenerze Docker, a aplikację Node.js uruchamiasz natywnie na Windowsie (poza Dockerem). W pliku .env ustawiasz DATABASE_URL na localhost.

Czasami to zadziała, ale często Windowsowy stos sieciowy nie mapuje poprawnie localhost na kontener Dockera, zwłaszcza jeśli używasz starszego Docker Toolbox lub specyficznych konfiguracji WSL 2. Prisma może rzucić błędem P1001: Can't reach database server.

Rozwiązanie

Jeśli standardowy localhost zawodzi, spróbuj użyć adresu IP pętli zwrotnej wprost:

DATABASE_URL="postgresql://user:password@127.0.0.1:5432/mydb"

W skrajnych przypadkach, jeśli aplikacja też jest w kontenerze, a baza na hoście (lub w innym kontenerze bez wspólnej sieci), musisz użyć specjalnego adresu DNS Dockera:

host.docker.internal

4. Problemy z kompilacją natywnych zależności (node-gyp)

Choć sama Prisma unika tego problemu dzięki prekompilowanym binariom Rust, to ekosystem wokół niej często wymaga narzędzi do budowania C++. Jeśli instalacja paczek npm install wywala się na etapie node-gyp przy zależnościach powiązanych z Prismą, zazwyczaj brakuje Ci narzędzi budowania Windows.

Zamiast ręcznie instalować Visual Studio, użyj oficjalnego narzędzia naprawczego od Microsoftu i Node.js. Uruchom PowerShell jako Administrator:

npm install --global windows-build-tools

Alternatywnie, nowsze wersje Node.js instalują skrypt "Tools for Native Modules" w menu Start – uruchom go, a on pobierze Pythona i kompilatory C++.

5. Ostateczne rozwiązanie: Przejście na WSL 2

Jeśli ciągle walczysz z błędami specyficznymi dla Windowsa, ścieżkami plików (backslashe \ vs slashe /) i uprawnieniami, najlepszą radą, jaką może dać ekspert, jest zaprzestanie walki z systemem.

Windows Subsystem for Linux 2 (WSL 2) to obecnie standard w developmencie na maszynach z Windowsem. Instalując Ubuntu wewnątrz Windowsa i uruchamiając projekt tam (korzystając z VS Code z rozszerzeniem Remote - WSL), eliminujesz 99% problemów opisanych powyżej. Prisma w środowisku WSL 2 zachowuje się dokładnie tak jak na natywnym Linuxie – jest stabilna, przewidywalna i szybka. Traktuj natywne uruchamianie na Windowsie jako ostateczność, a WSL 2 jako domyślny tryb pracy.