Использование Prisma с ClickHouse Managed Postgres

Подключите приложение на TypeScript к ClickHouse Managed Postgres с помощью Prisma ORM, выполняйте миграции через Prisma Migrate и отправляйте запросы через PgBouncer с проверкой сертификата TLS

Prisma ORM — это ORM для TypeScript с декларативной схемой, инструментом миграций (Prisma Migrate) и генерируемым типобезопасным клиентом. В этом руководстве вы подключите Prisma к ClickHouse Managed Postgres, создадите таблицу с помощью миграции и будете выполнять к ней запросы из скрипта и через небольшую HTTP-конечную точку.

В руководстве используется Prisma ORM 7 (проверено на версии 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-соединении из пула, которое затем обслуживает других клиентов, и последующие миграции будут ждать её снятия.

В верхней части модального окна переключайтесь между Directly и via PgBouncer, чтобы увидеть порт для каждого варианта. Сервер и учётные данные для обоих соединений одинаковы — отличается только порт.

Выбрав via PgBouncer, нажмите Download CA‑сертификат. Если выбран вариант Directly, сначала включите Use SSL — только тогда появится эта кнопка. Файл называется <service-name>-ca-certificate.pem. Его также можно найти в разделе Settings → CA‑сертификат. Сертификат уникален для вашего инстанса и используется для подключения с sslmode=verify-full: этот режим проверяет, что вы подключаетесь именно к своему серверу.

​

Настройка проекта

Создайте проект на TypeScript и установите Prisma CLI, Prisma Client, адаптер драйвера node-postgres и dotenv:

mkdir hello-prisma
cd hello-prisma
npm init -y
npm pkg set type=module
npm install typescript tsx @types/node @types/pg --save-dev
npm install prisma@7 --save-dev
npm install @prisma/client@7 @prisma/adapter-pg pg dotenv

Явно укажите версии при установке: prisma@7 и @prisma/client@7. На момент написания этого руководства npm-тег latest пакета prisma указывает на релиз-кандидат Prisma 8, который настраивается иначе, чем описано здесь.

Создайте файл tsconfig.json:

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "target": "ES2023",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "types": ["node"]
  }
}

Добавляете в существующее приложение?

Пропустите mkdir, npm init и создание tsconfig.json. В своём проекте выполните npm install tsx @types/pg prisma@7 --save-dev и npm install @prisma/client@7 @prisma/adapter-pg pg dotenv, а затем переходите к разделу Инициализация Prisma.

​

Инициализация Prisma

1. Запустите prisma init

   npx prisma init --datasource-provider postgresql --output ../generated/prisma
   

   Эта команда создаёт 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:

   mv ~/Downloads/<service-name>-ca-certificate.pem ca-certificate.pem
   

   Относительные пути к сертификатам вычисляются от каталога, в котором выполняются команды, поэтому запускайте все команды из этого руководства из корня проекта.

​

Настройка соединения

1. Создайте базу данных

   Создайте базу данных для приложения. Замените <PASSWORD> и хост значениями из модального окна Connect:

   psql "postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/postgres?sslmode=verify-full&sslrootcert=ca-certificate.pem" -c "CREATE DATABASE guide_prisma;"
   

   CREATE DATABASE
   
2. Задайте URL-адреса соединений

   В файле .env замените плейсхолдер DATABASE_URL, добавленный командой prisma init, двумя URL-адресами соединений, оба из которых указывают на базу данных guide_prisma. Используйте пароль из модального окна Connect:

   # Prisma Client (ваше приложение): через PgBouncer, порт 6432
   DATABASE_URL="postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:6432/guide_prisma?sslmode=verify-full&sslrootcert=ca-certificate.pem"
   
   # Prisma CLI (миграции): прямое соединение, порт 5432
   DIRECT_URL="postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/guide_prisma?sslmode=require&sslaccept=strict&sslcert=ca-certificate.pem"
   

   В этих URL используются разные параметры TLS, поскольку их считывают разные драйверы:

   • DATABASE_URL считывает node-postgres через @prisma/adapter-pg. Он поддерживает стандартные параметры sslmode=verify-full&sslrootcert=... — те же, что указаны в модальном окне Connect.
   • DIRECT_URL считывает движок схем Prisma CLI, у которого свои параметры: sslcert — путь к CA‑сертификату, а sslaccept=strict включает проверку сертификата и имени хоста.

   Не используйте sslmode=verify-full&sslrootcert=... в URL для Prisma CLI. Движок схем игнорирует sslrootcert, а без sslaccept=strict вообще не проверяет сертификат сервера: соединение будет зашифровано, но подлинность сервера не будет подтверждена.

3. Направьте Prisma CLI на прямое соединение

   Замените содержимое файла prisma7.config.ts:

   import "dotenv/config";
   import { defineConfig, env } from "prisma/config";
   
   export default defineConfig({
     schema: "prisma/schema.prisma",
     migrations: {
       path: "prisma/migrations",
     },
     datasource: {
       url: env("DIRECT_URL"),
     },
   });
   

   В Prisma 7 URL из файла конфигурации использует только CLI. Prisma Client получает соединение от адаптера драйвера, который настраивается в разделе Запросы к базе данных.

​

Определение схемы и выполнение миграции

1. Добавьте модель

   Добавьте модель Todo в конец файла prisma/schema.prisma:

   model Todo {
     id        Int      @id @default(autoincrement())
     title     String
     done      Boolean  @default(false)
     createdAt DateTime @default(now())
   }
   
2. Выполните миграцию

   В Linux запустите Prisma Migrate напрямую:

   npx prisma migrate dev --name init
   

   В macOS выполните ту же команду в Linux-контейнере:

   docker run --rm -it -v "$PWD":/app -w /app node:24 npx prisma migrate dev --name init
   

   ClickHouse Managed Postgres поддерживает только TLS 1.3. В macOS движок схем Prisma CLI использует системную библиотеку TLS, которая не может установить соединение с такими настройками. Команда завершается ошибкой P1011: Error opening a TLS connection: One or more parameters passed to a function were not valid, а если удалить sslcert, — ошибкой bad protocol version (prisma/orm#29600). Проблема касается только команд CLI, которые подключаются к базе данных, например prisma migrate и prisma db pull. На Prisma Client она не влияет, поскольку он подключается через node-postgres. Чтобы обойти проблему, запускайте CLI в Linux-контейнере или в конвейере CI на базе Linux.

   Prisma создаёт SQL-миграцию в prisma/migrations/ и применяет её:

   Applying migration `20260930165244_init`
   
   The following migration(s) have been created and applied from new schema changes:
   
   prisma/migrations/
     └─ 20260930165244_init/
       └─ migration.sql
   
   Your database is now in sync with your schema.
   
3. Сгенерируйте Prisma Client

   npx prisma generate
   

   Клиент генерируется в каталог generated/prisma. Эта команда не подключается к базе данных, поэтому её можно запускать на любой платформе.

​

Выполнение запросов к базе данных

1. Создайте Prisma Client

   Создайте lib/prisma.ts. Адаптер PrismaPg подключается через PgBouncer, используя DATABASE_URL:

   import "dotenv/config";
   import { PrismaPg } from "@prisma/adapter-pg";
   import { PrismaClient } from "../generated/prisma/client";
   
   const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL });
   
   export const prisma = new PrismaClient({ adapter });
   

   Настраивать PgBouncer не нужно

   @prisma/adapter-pg отправляет каждый запрос как безымянный подготовленный оператор и никогда не выполняет DEALLOCATE, поэтому он совместим с режимом пулинга транзакций PgBouncer. Адаптер без ошибок обрабатывает сотни различных запросов, параллельно выполняемых на backend-соединениях из пула. Параметр URL pgbouncer=true из старых версий Prisma не нужен: с адаптером драйвера он ни на что не влияет.

2. Выполните CRUD-запросы

   Создайте script.ts:

   import { prisma } from "./lib/prisma";
   
   async function main() {
     // Создание
     const todo = await prisma.todo.create({
       data: { title: "Connect Prisma to ClickHouse Managed Postgres" },
     });
     console.log("Created:", todo);
   
     // Чтение
     const open = await prisma.todo.findMany({ where: { done: false } });
     console.log("Open todos:", open.length);
   
     // Обновление
     const updated = await prisma.todo.update({
       where: { id: todo.id },
       data: { done: true },
     });
     console.log("Updated:", updated);
   
     // Удаление
     await prisma.todo.delete({ where: { id: todo.id } });
     console.log("Deleted todo", todo.id);
   }
   
   main().finally(() => prisma.$disconnect());
   

   Запустите скрипт:

   npx tsx script.ts
   

   Created: {
     id: 1,
     title: 'Connect Prisma to ClickHouse Managed Postgres',
     done: false,
     createdAt: 2026-09-30T16:52:57.116Z
   }
   Open todos: 1
   Updated: {
     id: 1,
     title: 'Connect Prisma to ClickHouse Managed Postgres',
     done: true,
     createdAt: 2026-09-30T16:52:57.116Z
   }
   Deleted todo 1
   
3. Предоставьте доступ к данным по HTTP

   Создайте server.ts — минимальный HTTP-сервер, который создаёт задачи по запросу POST /todos и возвращает их список на любой запрос GET:

   import { createServer } from "node:http";
   import { prisma } from "./lib/prisma";
   
   const port = Number(process.env.PORT ?? 3000);
   
   createServer(async (req, res) => {
     if (req.method === "POST" && req.url === "/todos") {
       let body = "";
       for await (const chunk of req) body += chunk;
       const todo = await prisma.todo.create({ data: { title: JSON.parse(body).title } });
       res.writeHead(201, { "Content-Type": "application/json" });
       res.end(JSON.stringify(todo));
       return;
     }
   
     const todos = await prisma.todo.findMany({ orderBy: { id: "asc" } });
     res.writeHead(200, { "Content-Type": "application/json" });
     res.end(JSON.stringify(todos, null, 2));
   }).listen(port, () => console.log(`Listening on http://localhost:${port}`));
   

   Запустите сервер:

   npx tsx server.ts
   

   В другом терминале добавьте две задачи:

   curl -X POST localhost:3000/todos -H "Content-Type: application/json" -d '{"title": "Try Prisma with ClickHouse Managed Postgres"}'
   curl -X POST localhost:3000/todos -H "Content-Type: application/json" -d '{"title": "Add a read replica"}'
   

   Чтобы увидеть их, откройте в браузере http://localhost:3000/todos. Ответ будет выглядеть так:

   [
     {
       "id": 2,
       "title": "Try Prisma with ClickHouse Managed Postgres",
       "done": false,
       "createdAt": "2026-09-30T16:53:06.098Z"
     },
     {
       "id": 3,
       "title": "Add a read replica",
       "done": false,
       "createdAt": "2026-09-30T16:53:06.184Z"
     }
   ]
   

​

Проверка в консоли SQL

В консоли ClickHouse Cloud откройте консоль SQL для своего сервиса, разверните свою базу данных и схему public, затем выберите таблицу Todo. Там же вы увидите таблицу _prisma_migrations, в которой Prisma Migrate фиксирует применённые миграции.

Таблица Todo содержит две строки, добавленные через конечную точку HTTP:

id	title	done	createdAt
2	Try Prisma with ClickHouse Managed Postgres	false	2026-09-30 16:53:06.098
3	Add a read replica	false	2026-09-30 16:53:06.184

​

Устранение неполадок

Ошибка	Причина и решение
P1011: Error opening a TLS connection: One or more parameters passed to a function were not valid или bad protocol version	Prisma CLI запущен на macOS. Запустите его в Linux‑контейнере, как показано в разделе Выполнение миграции.
P1011: ... certificate verify failed	Prisma CLI не может проверить подлинность сервера. Убедитесь, что sslcert в DIRECT_URL указывает на CA‑сертификат вашего инстанса.
P1011: ... cert file not found	Неверно указан путь sslcert в DIRECT_URL. Запускайте CLI из корневого каталога проекта или укажите абсолютный путь.
unable to verify the first certificate	Prisma Client не может проверить подлинность сервера. Убедитесь, что sslrootcert в DATABASE_URL указывает на CA‑сертификат вашего инстанса.
ENOENT: no such file or directory	Неверно указан путь sslrootcert в DATABASE_URL. Запускайте приложение из корневого каталога проекта или укажите абсолютный путь.

​

Дальнейшие шаги

• Соединение: строки соединения, PgBouncer и TLS
• Настройки: настройка параметров Postgres и PgBouncer
• Реплики для чтения: масштабирование рабочих нагрузок с преобладанием операций чтения
• Локальная разработка: разработка с локальным Postgres в Docker
• Prisma Migrate в продакшне: используйте prisma migrate deploy в конвейере CI