7.10.0) — текущий стабильный релиз.
Предварительные требования
- Node.js 20.19, 22.12 или 24 и выше
- Сервис ClickHouse Managed Postgres
psqlдля создания базы данных. ОператорCREATE DATABASEтакже можно выполнить в консоли SQL.- В macOS: Docker для запуска Prisma Migrate (см. Выполнение миграции)
Создание сервиса ClickHouse Managed Postgres
В консоли ClickHouse Cloud нажмите New service и выберите Postgres. Инстанс будет готов через несколько минут. Пошаговое описание процесса приведено в кратком руководстве по началу работы.Получите сведения о подключении
Нажмите Connect на левой боковой панели вашего сервиса. В открывшемся модальном окне отображаются имя пользователя, пароль, сервер и порт, а также готовые строки подключения. В этом руководстве используются два соединения, поскольку в Prisma есть два компонента, которые обращаются к базе данных:- Ваше приложение (Prisma Client) подключается через PgBouncer на порту
6432. PgBouncer объединяет соединения в пул, поэтому множество процессов приложения или serverless-инстансов могут совместно использовать небольшое число backend-соединений Postgres. - Prisma CLI (Prisma Migrate) подключается напрямую на порту
5432. Во время работы Prisma Migrate захватывает рекомендательную блокировку (advisory lock) на уровне сеанса. В режиме пулинга транзакций PgBouncer эта блокировка может так и остаться на backend-соединении из пула, которое затем обслуживает других клиентов, и последующие миграции будут ждать её снятия.
<service-name>-ca-certificate.pem. Его также можно найти в разделе Settings → CA‑сертификат. Сертификат уникален для вашего инстанса и используется для подключения с sslmode=verify-full: этот режим проверяет, что вы подключаетесь именно к своему серверу.
Настройка проекта
Создайте проект на TypeScript и установите Prisma CLI, Prisma Client, адаптер драйвера node-postgres иdotenv:
Явно укажите версии при установке:
prisma@7 и @prisma/client@7. На момент написания этого руководства npm-тег latest пакета prisma указывает на релиз-кандидат Prisma 8, который настраивается иначе, чем описано здесь.tsconfig.json:
Инициализация Prisma
1
Запустите prisma init
prisma/schema.prisma и файл конфигурации Prisma prisma7.config.ts, добавляет плейсхолдер DATABASE_URL в .env, а сгенерированный клиент — в .gitignore (при необходимости создавая эти файлы), а также устанавливает навыки Prisma для AI-агентов для написания кода. Начиная с версии Prisma 7.10, файл конфигурации называется prisma7.config.ts, чтобы не возникало конфликта с форматом Prisma 8.2
Добавьте CA‑сертификат
Переместите скачанный CA‑сертификат в корень проекта и переименуйте его в Относительные пути к сертификатам вычисляются от каталога, в котором выполняются команды, поэтому запускайте все команды из этого руководства из корня проекта.
ca-certificate.pem:Настройка соединения
1
Создайте базу данных
Создайте базу данных для приложения. Замените
<PASSWORD> и хост значениями из модального окна Connect:2
Задайте URL-адреса соединений
В файле В этих URL используются разные параметры TLS, поскольку их считывают разные драйверы:
.env замените плейсхолдер DATABASE_URL, добавленный командой prisma init, двумя URL-адресами соединений, оба из которых указывают на базу данных guide_prisma. Используйте пароль из модального окна Connect:DATABASE_URLсчитывает node-postgres через@prisma/adapter-pg. Он поддерживает стандартные параметрыsslmode=verify-full&sslrootcert=...— те же, что указаны в модальном окне Connect.DIRECT_URLсчитывает движок схем Prisma CLI, у которого свои параметры:sslcert— путь к CA‑сертификату, аsslaccept=strictвключает проверку сертификата и имени хоста.
3
Направьте Prisma CLI на прямое соединение
Замените содержимое файла В Prisma 7 URL из файла конфигурации использует только CLI. Prisma Client получает соединение от адаптера драйвера, который настраивается в разделе Запросы к базе данных.
prisma7.config.ts:Определение схемы и выполнение миграции
1
Добавьте модель
Добавьте модель
Todo в конец файла prisma/schema.prisma:2
Выполните миграцию
В Linux запустите Prisma Migrate напрямую:В macOS выполните ту же команду в Linux-контейнере:Prisma создаёт SQL-миграцию в
prisma/migrations/ и применяет её:3
Сгенерируйте Prisma Client
generated/prisma. Эта команда не подключается к базе данных, поэтому её можно запускать на любой платформе.Выполнение запросов к базе данных
1
Создайте Prisma Client
Создайте
lib/prisma.ts. Адаптер PrismaPg подключается через PgBouncer, используя DATABASE_URL:2
Выполните CRUD-запросы
Создайте Запустите скрипт:
script.ts:3
Предоставьте доступ к данным по HTTP
Создайте Запустите сервер:В другом терминале добавьте две задачи:Чтобы увидеть их, откройте в браузере http://localhost:3000/todos. Ответ будет выглядеть так:
server.ts — минимальный HTTP-сервер, который создаёт задачи по запросу POST /todos и возвращает их список на любой запрос GET:Проверка в консоли SQL
В консоли ClickHouse Cloud откройте консоль SQL для своего сервиса, разверните свою базу данных и схемуpublic, затем выберите таблицу Todo. Там же вы увидите таблицу _prisma_migrations, в которой Prisma Migrate фиксирует применённые миграции.
Таблица Todo содержит две строки, добавленные через конечную точку HTTP:
Устранение неполадок
Дальнейшие шаги
- Соединение: строки соединения, PgBouncer и TLS
- Настройки: настройка параметров Postgres и PgBouncer
- Реплики для чтения: масштабирование рабочих нагрузок с преобладанием операций чтения
- Локальная разработка: разработка с локальным Postgres в Docker
- Prisma Migrate в продакшне: используйте
prisma migrate deployв конвейере CI