Что такое шаг генерации @prisma/client и почему нужно запускать prisma generate после изменений схемы?

Зачем это нужно

Prisma Client — это не generic ORM с runtime-рефлексией. Это сгенерированный код, который знает о структуре вашей базы на этапе компиляции. Когда вы пишете:

const user = await prisma.user.findUnique({
  where: { id: '123' },
  select: { name: true, email: true },
});

TypeScript знает, что user.name — это string, а user.age не существует, потому что такого поля нет в схеме. Это возможно только если клиент был сгенерирован из актуальной схемы.

Что такое prisma generate

prisma generate — команда, которая читает файл prisma/schema.prisma и генерирует TypeScript-клиент в node_modules/@prisma/client. Этот клиент содержит типизированные методы (findMany, create, update и т.д.) точно под вашу схему — с правильными типами для каждой модели, поля и связи.

Что происходит при generate

1. Prisma CLI парсит schema.prisma.
2. На основе моделей генерирует TypeScript-типы и JavaScript-код в node_modules/@prisma/client.
3. Также генерирует prisma/runtime/ — платформо-специфичные бинарники для Query Engine (нативные библиотеки для вашей ОС).

# Запускаем генерацию
npx prisma generate

# Вывод:
# Prisma schema loaded from prisma/schema.prisma
# ✔ Generated Prisma Client (v5.x.x) to ./node_modules/@prisma/client in 234ms

Когда обязательно запускать

• После любого изменения в schema.prisma — добавили поле, модель, связь, изменили тип.
• После npm install / yarn install — если @prisma/client был обновлён.
• После prisma migrate dev — она запускает generate автоматически, но явный вызов безопаснее в CI.
• В Docker при сборке образа — если клиент не сгенерирован, приложение упадёт при старте.

Типичный Dockerfile

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY prisma ./prisma
RUN npx prisma generate   # <-- обязательно до копирования src
COPY src ./src
RUN npm run build

postinstall хук

Хорошая практика — добавить generate в postinstall, чтобы он запускался автоматически после npm install:

// package.json
{
  "scripts": {
    "postinstall": "prisma generate"
  }
}

Что будет если не запустить

TypeScript не найдёт тип нового поля и выдаст ошибку компиляции. Или, если изменение некритичное (добавили опциональное поле), TypeScript промолчит, но IDE не подскажет автодополнение для нового поля. В runtime Prisma обращается к базе, а тип в клиенте устарел — это путаница, которую сложно диагностировать.

Подводные камни

• В production-образах нет Prisma CLI — нужно запускать generate во время сборки, а не при старте контейнера.
• После npm ci клиент не генерируется автоматически без postinstall — в CI это частая причина «Cannot find module @prisma/client».
• Monorepo: если schema.prisma в одном пакете, а код в другом, нужно настроить output в generator client так, чтобы путь был корректным относительно кода.
• Разные платформы требуют разных бинарников Query Engine — для Docker нужен binaryTargets = ["native", "linux-musl"] в schema.prisma.
• Генерация не проверяет соответствие схемы реальной БД — это делает prisma migrate status. Можно иметь «свежий» клиент, но устаревшую базу.
• В .gitignore обычно добавляют node_modules/, но некоторые команды коммитят сгенерированный клиент — это плохая практика и источник конфликтов.

• Путает Prisma Client API с гарантиями базы данных: индексы, блокировки и isolation level не создаются магически.
• Не объясняет, где в lifecycle находится шаг prisma generate.
• Не разделяет validation, authorization, business logic и persistence.
• Игнорирует ошибки, лимиты входных данных, observability и тестирование.

• Может объяснить шаг prisma generate на примере кода.
• Называет ключевые API: prisma generate.
• Отделяет ORM/query builder поведение от реального поведения СУБД.
• Видит production-риски: безопасность, отказоустойчивость, логирование и тесты.