Generator modelu Prisma

Co robi generator modelu Prisma

Prisma to ORM dla Node.js i TypeScript. Model w pliku schema.prisma opisuje tabelę (w MongoDB kolekcję) i jej kolumny, a Prisma generuje z niego typowany klient i migracje. Generator modelu Prisma zamienia listę pól wpisaną w formacie nazwa Typ atrybuty na gotowy blok model, opcjonalnie poprzedzony sekcjami generator i datasource, i wypisuje uwagi o typowych błędach, np. braku identyfikatora.

Budowa modelu

Przykład

Dane startowe narzędzia (przycisk „Przywróć przykład”) dają taki model User:

model User {
  id Int @id @default(autoincrement())
  email String @unique
  name String?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

Sekcja generator i datasource

Przy zaznaczonej opcji „Dodaj generator i datasource” (domyślnie włączona) wynik zaczyna się od dwóch bloków:

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

datasource db {
  provider = "postgresql"
  url = env("DATABASE_URL")
}

Wartość provider wybierasz z listy: postgresql, mysql, sqlite, sqlserver, mongodb lub cockroachdb. Adres bazy jest zawsze odczytywany ze zmiennej DATABASE_URL, którą ustawiasz w pliku .env. Jeśli dopisujesz model do istniejącego schematu, odznacz tę opcję: plik może mieć tylko jeden blok datasource.

Migracje

npx prisma validate sprawdza składnię schematu, npx prisma format porządkuje wcięcia. npx prisma migrate dev --name init tworzy i stosuje migrację na podstawie schematu, a npx prisma generate odświeża typowanego klienta.

Jak działa generator modelu Prisma

Narzędzie nie łączy się z bazą danych, nie czyta projektu Node.js i nie zna Twojego istniejącego pliku schema.prisma. Pracuje wyłącznie na tym, co wpiszesz: nazwie modelu, liście pól (jedno w linii), wybranym dostawcy bazy i opcjonalnej nazwie tabeli. Z tych danych składa tekst w składni Prisma: nagłówek modelu, po jednej linii na każde pole w kolejności wpisania, atrybuty całego modelu i nawias zamykający.

Każda linia ma postać nazwa Typ atrybuty. Dwukropek po nazwie (email: String) też jest akceptowany i znika z wyniku. Znak ? po typie oznacza pole opcjonalne, [] listę, a atrybuty muszą zaczynać się od @. Linie zaczynające się od // trafiają do modelu jako komentarze, a linie od @@ (np. @@index([email])) lądują na końcu bloku. Typy wpisane małymi literami narzędzie poprawia (string → String, bool → Boolean, integer → Int), bo Prisma rozróżnia wielkość liter. Typ spoza listy typów skalarnych, np. Post albo Role, jest traktowany jako model lub enum, który musi istnieć w schemacie.

Linie, których nie da się rozpoznać (brak typu, nazwa zaczynająca się cyfrą, atrybut bez @, powtórzona nazwa pola), są pomijane, a pod wynikiem pojawia się uwaga z numerem linii. Lista pól może mieć do 100 linii i 6000 znaków. Nazwa modelu ma najwyżej 60 znaków, zaczyna się od litery i zawiera tylko litery, cyfry oraz znak _.

Generator nie zmienia wielkości liter w nazwach, tylko podpowiada, że modele pisze się zwyczajowo w PascalCase (User, nie user). Kolejność bloków w pliku schema.prisma nie ma znaczenia, ale nazwy modeli muszą być unikalne w całym schemacie.

Co sprawdza narzędzie

• czy model ma identyfikator: pole z @id lub @unique albo wpis @@id / @@unique,
• czy pole z @id nie jest opcjonalne,
• czy @updatedAt stoi przy polu typu DateTime,
• czy przy MongoDB nie użyto autoincrement() (podpowiada zapis z @default(auto()) @map("_id") @db.ObjectId),
• czy listy typów prostych, np. String[], nie trafiły do MySQL, SQLite lub SQL Server; obsługują je PostgreSQL, CockroachDB i MongoDB.

Przykład krok po kroku: model Post

1. W polu „Nazwa modelu” wpisujesz Post. Prisma nie tworzy liczby mnogiej: bez @@map tabela też będzie się nazywać Post.
2. W polu „Pola” wpisujesz sześć linii: id Int @id @default(autoincrement()), title String, slug String @unique, body String?, published Boolean @default(false) i createdAt DateTime @default(now()).
3. Pole slug służy do adresów URL i dzięki @unique nie może się powtarzać między rekordami. Znak zapytania przy body oznacza kolumnę, która dopuszcza wartość pustą.
4. Pole published ma wartość domyślną false, więc nowy rekord startuje jako nieopublikowany, a createdAt wypełnia się czasem utworzenia rekordu.
5. W opcjach wpisujesz nazwę tabeli posts. Narzędzie samo dopisze na końcu modelu @@map("posts").

Po kliknięciu „Generuj model” dostajesz (pomijając sekcje generator i datasource):

model Post {
  id Int @id @default(autoincrement())
  title String
  slug String @unique
  body String?
  published Boolean @default(false)
  createdAt DateTime @default(now())

  @@map("posts")
}

Blok ma 10 linii: nagłówek, sześć pól, pustą linię, @@map i nawias zamykający. Kafelki pokażą 6 pól, 1 opcjonalne, 0 typów własnych i 0 uwag. Gdyby zabrakło linii z id, narzędzie nie zgłosi braku identyfikatora, bo slug ma @unique, co Prisma też akceptuje; klucz główny i tak warto mieć.

Elementy schematu, które warto znać

Praktyczne wskazówki

• Nazywaj modele rzeczownikiem w liczbie pojedynczej: Post, a nie Posts. Prisma nie zmienia liczby przy mapowaniu na tabelę, więc jeśli tabela ma się nazywać posts, wpisz to w polu „Nazwa tabeli w bazie”.
• Ustal konwencję nazw przed pierwszym modelem. Jeśli baza używa snake_case, dodaj @map("created_at") przy polach od razu, zamiast poprawiać kilkadziesiąt pól później.
• Dodawaj indeksy razem z polami, po których filtrujesz. Pole, które w zapytaniach trafia do warunku WHERE lub do sortowania, powinno mieć wpis @@index([pole]) na poziomie modelu.
• Przemyśl opcjonalność od początku. Dodanie wymaganego pola do tabeli, która już ma dane, zwykle wymaga wartości domyślnej albo ręcznej migracji z uzupełnieniem istniejących rekordów.
• Trzymaj plik schema.prisma w repozytorium i przeglądaj jego zmiany jak zwykły kod źródłowy.

Czego narzędzie nie uwzględnia

• Sprawdza format nazw i powtórzenia pól w obrębie modelu, ale nie wie, czy nazwa modelu nie koliduje ze słowem zarezerwowanym Prisma albo z modelem w Twoim schemacie. Wychwyci to dopiero prisma validate.
• Pole relacji z @relation możesz wpisać sam (gotowy przykład daje przycisk „Comment (relacja)”), ale drugą stronę relacji w modelu docelowym musisz dopisać ręcznie.
• Nie tworzy bloków enum ani kilku modeli naraz. Każdy typ własny użyty w polach musi już istnieć w schemacie.
• Nie porównuje wyniku z rzeczywistą strukturą tabel, nie importuje schematu i nie wykryje rozjazdu między modelem a stanem bazy. Do tego służy npx prisma db pull.
• Nie generuje migracji, seedów ani klienta. Polecenia migracyjne i generujące uruchamiasz w projekcie po zapisaniu pliku.
• Sekcje nagłówkowe mają klasyczną postać (prisma-client-js, url = env("DATABASE_URL")). W nowszych wersjach Prisma część konfiguracji przeniesiono do pliku prisma.config.ts, dlatego sprawdź je z dokumentacją wersji, której używasz.