Ошибка Can't reach database server или пустой ответ prisma.user.findMany() после установки Prisma почти всегда означает одно: ORM подключена, но не настроена — не заполнен файл .env, не описана схема или не выполнена миграция. Настройка Prisma сводится к четырём обязательным шагам: установка пакетов, инициализация через prisma init, описание моделей в schema.prisma и генерация клиента.
Ниже разберём каждый этап подробно: от выбора базы данных до типичных ошибок подключения. Инструкция подходит для проектов на Node.js и TypeScript — именно в этой связке Prisma используется чаще всего. Команды приведены для актуальной линейки Prisma; если у вас старая версия CLI, сверяйтесь с официальной документацией, так как синтаксис отдельных команд мог измениться.
Установка Prisma и инициализация проекта
Для начала понадобится установленный Node.js и созданная папка проекта с package.json. Prisma состоит из двух частей: CLI (инструмент командной строки для миграций и генерации) и клиента, который импортируется в код приложения.
Установите CLI как dev-зависимость и клиент как обычную зависимость:
npm install prisma --save-dev
npm install @prisma/client
После установки выполните инициализацию. Команда создаст папку prisma с файлом schema.prisma и файл .env в корне проекта:
npx prisma initЕсли база данных уже существует и содержит таблицы, можно не писать схему вручную, а подтянуть её командой npx prisma db pull — Prisma проанализирует структуру БД и сгенерирует модели автоматически.
- 📦 prisma — CLI для миграций, генерации и интроспекции
- 🔌 @prisma/client — типизированный клиент для запросов из кода
- 📄 schema.prisma — главный файл конфигурации и описания моделей
- 🔐 .env — строка подключения к базе данных
Настройка строки подключения в .env
Prisma читает адрес базы данных из переменной DATABASE_URL в файле .env. Формат строки зависит от СУБД и выглядит так: протокол://пользователь:пароль@хост:порт/имя_базы. Для локальной разработки на PostgreSQL это может быть:
DATABASE_URL="postgresql://postgres:password@localhost:5432/mydb"Для SQLite строка проще — указывается путь к файлу: DATABASE_URL="file:./dev.db". Для MySQL используется протокол mysql://. Убедитесь, что хост, порт и имя базы совпадают с реальными параметрами вашего сервера БД — несовпадение порта или имени базы является самой частой причиной ошибки подключения.
⚠️ Внимание: если пароль содержит спецсимволы (@,#,:), их нужно закодировать в URL-формате, иначе Prisma не сможет распарсить строку подключения. Например, символ@заменяется на%40.
Проверить, что переменная подхватывается корректно, можно командой npx prisma validate — она проверит схему и доступность конфигурации без обращения к самой базе.
Описание схемы данных в schema.prisma
Файл schema.prisma состоит из трёх блоков. Блок generator указывает, какой клиент генерировать, блок datasource — к какой базе подключаться, а блоки model описывают таблицы. Без корректно заполненных всех трёх частей клиент работать не будет.
generator client {
provider = "prisma-client-js"
}
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
}
model User {
id Int @id @default(autoincrement())
email String @unique
name String?
posts Post[]
}
model Post {
id Int @id @default(autoincrement())
title String
author User @relation(fields: [authorId], references: [id])
authorId Int
}
Обратите внимание на атрибуты: @id помечает первичный ключ, @unique — уникальное поле, а @relation связывает модели между собой. Значок ? после типа делает поле необязательным (nullable). Значение provider в блоке datasource должно точно совпадать с типом вашей СУБД — нельзя указать postgresql и подключаться к MySQL.
Миграции и генерация Prisma Client
Когда схема готова, её нужно применить к базе данных. Для этого служит команда миграции — она создаст SQL-файл миграции и выполнит его:
npx prisma migrate dev --name initЭта же команда автоматически запускает генерацию Prisma Client. Если схему меняли вручную без миграции, клиент перегенерируется отдельно:
npx prisma generate☑️ Проверка перед первым запуском
⚠️ Внимание: командуmigrate devиспользуйте только в разработке — она может сбрасывать базу при конфликте миграций. На продакшене применяйтеnpx prisma migrate deploy, которая лишь накатывает готовые миграции без интерактивных подтверждений.
Подключение клиента в коде приложения
После генерации клиент импортируется из пакета @prisma/client. Рекомендуемый паттерн — создать один экземпляр PrismaClient и переиспользовать его во всём приложении, а не создавать новое подключение на каждый запрос:
import { PrismaClient } from '@prisma/client'
const prisma = new PrismaClient()
const users = await prisma.user.findMany()
В средах с горячей перезагрузкой модулей (например, Next.js в dev-режиме) многократное создание экземпляров приводит к исчерпанию пула подключений. Общепринятое решение — сохранять клиент в глобальном объекте; точный код этого паттерна приведён в официальной документации Prisma для вашего фреймворка.
Сравнение настроек для разных СУБД
Конфигурация блока datasource и формат строки подключения различаются в зависимости от выбранной базы. Соберём основные варианты в таблицу:
| СУБД | provider | Формат DATABASE_URL | Особенности |
|---|---|---|---|
| PostgreSQL | postgresql | postgresql://user:pass@host:5432/db | Полная поддержка всех функций Prisma |
| MySQL | mysql | mysql://user:pass@host:3306/db | Проверяйте версию сервера на совместимость |
| SQLite | sqlite | file:./dev.db | Нет параллельной записи, для разработки |
| MongoDB | mongodb | mongodb+srv://user:pass@cluster/db | Другая модель ID, нет реляционных миграций |
Выбор СУБД влияет не только на строку подключения, но и на доступные типы полей и поведение миграций. Например, в SQLite часть типов данных эмулируется, а MongoDB вообще не использует классические SQL-миграции. Перед стартом проекта стоит убедиться, что нужные вам возможности поддерживаются выбранным коннектором — актуальная матрица поддержки есть в документации Prisma.
Типичные ошибки и их диагностика
Разберём симптомы, с которыми чаще всего сталкиваются при первой настройке. Большинство проблем диагностируется по тексту ошибки в терминале — Prisma выводит достаточно подробные сообщения.
- 🔴 P1001 Can't reach database server — сервер БД не запущен, неверный хост или порт, либо подключение блокирует файрвол
- 🔴 P1003 Database does not exist — база с указанным именем не создана; создайте её вручную или через СУБД
- 🔴 Environment variable not found — файл
.envотсутствует, лежит не в корне проекта или переменная названа иначе - 🔴 Модели нет в клиенте — после изменения схемы не выполнена команда
prisma generate
Как сбросить базу при конфликте миграций
В dev-окружении выполните npx prisma migrate reset — команда удалит базу, накатит все миграции заново и запустит seed-скрипт, если он настроен. Все данные будут потеряны, поэтому команду нельзя запускать на продакшене.
Если ошибка не воспроизводится по описанным сценариям, включите подробное логирование запросов: при создании клиента передайте параметр log: ['query', 'error'] в конструктор PrismaClient. Это покажет, какие SQL-запросы реально уходят в базу.
Часто задаваемые вопросы
Нужно ли коммитить папку prisma в Git?
Да, файл schema.prisma и папку migrations следует хранить в репозитории — без них команда не сможет воспроизвести структуру базы. Исключение — файл .env с паролями, он должен быть в .gitignore.
Чем migrate dev отличается от db push?
Команда db push синхронизирует схему с базой напрямую, без создания файлов миграций — подходит для быстрых экспериментов. migrate dev создаёт историю миграций, что необходимо для командной работы и продакшена.
Можно ли использовать Prisma без TypeScript?
Да, клиент работает и в обычном JavaScript-проекте. Однако типизация — одно из главных преимуществ Prisma, поэтому с TypeScript вы получите автодополнение полей и проверку запросов на этапе компиляции.
Где должен лежать файл .env?
По умолчанию Prisma ищет .env в корне проекта. Если файл расположен иначе, путь можно задать флагом --env-file или через переменную окружения DOTENV_CONFIG_PATH, в зависимости от версии CLI и способа запуска.
Что делать, если prisma generate зависает или падает?
Проверьте, что схема валидна командой npx prisma validate, обновите пакеты prisma и @prisma/client до одинаковой версии и очистите кэш генерации, удалив папку node_modules/.prisma, после чего запустите генерацию заново.