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

Подключите TypeScript-приложение к ClickHouse Managed Postgres с помощью Drizzle ORM и node-postgres, выполняйте миграции через drizzle-kit и отправляйте запросы по TLS с проверкой сертификата

Drizzle ORM — это ORM для TypeScript с SQL-подобным конструктором запросов, а drizzle-kit — сопутствующий CLI-инструмент для генерации и выполнения миграций. В этом руководстве вы опишете таблицу todos на TypeScript, создадите её с помощью миграции drizzle-kit и реализуете обработку запросов на создание, чтение, обновление и удаление в небольшом HTTP-сервере на Node.js. Все соединения защищены TLS с полной проверкой сертификата.

​

Предварительные требования

• Node.js версии 20 или выше
• Аккаунт ClickHouse Cloud
• psql для создания базы данных. Вместо этого можно выполнить оператор CREATE DATABASE в консоли SQL.

​

Создание сервиса ClickHouse Managed Postgres

В консоли ClickHouse Cloud нажмите New service и выберите Postgres. Инстанс будет готов через несколько минут. Пошаговое описание процесса см. в руководстве по быстрому старту.

​

Получите сведения о подключении

Нажмите Подключение на левой боковой панели вашего сервиса. В открывшемся модальном окне отображаются имя пользователя, пароль, сервер и порт, а также переключатель Directly / via PgBouncer.

В этом руководстве используются две строки подключения:

• Прямое подключение (порт 5432) — для drizzle-kit. Миграции выполняют DDL, могут работать долго и зависеть от состояния сеанса (например, SET lock_timeout), поэтому они должны обращаться к Postgres напрямую.
• PgBouncer (порт 6432) — для приложения. Встроенный PgBouncer работает в режиме пулинга транзакций и позволяет множеству инстансов приложения, включая serverless-функции, совместно использовать небольшое число соединений с Postgres.

Если у вас один долгоживущий сервер Node.js, node-postgres уже поддерживает собственный пул соединений, поэтому приложение можно подключить и напрямую. Подключение через PgBouncer используйте при горизонтальном масштабировании на множество процессов или при работе на serverless-платформах.

Выбрав Directly, включите Use SSL. URL подключения на вкладке url теперь заканчивается на sslmode=verify-full&sslrootcert=<service-name>-ca-certificate.pem, а в качестве порта указан 5432. Выберите via PgBouncer, чтобы увидеть сведения о подключении через пул: порт изменится на 6432, а URL всегда будет содержать sslmode=verify-full.

В модальном окне нажмите Download CA certificate. CA‑сертификат также можно скачать в разделе Settings → CA Certificate. Сертификат уникален для вашего инстанса, поэтому с его помощью драйвер может убедиться, что взаимодействует именно с вашим сервером.

​

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

Создайте проект и установите Drizzle ORM, драйвер node-postgres (pg) и drizzle-kit:

mkdir drizzle-managed-postgres && cd drizzle-managed-postgres
npm init -y
npm pkg set type=module
npm install drizzle-orm pg dotenv
npm install -D drizzle-kit tsx @types/pg

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

Пропустите команды mkdir, npm init и npm pkg set type=module. Вместо этого выполните в своём проекте npm install drizzle-orm pg dotenv и npm install -D drizzle-kit tsx @types/pg, а затем переходите к разделу Настройка соединения.

​

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

Переместите скачанный CA‑сертификат в каталог проекта и переименуйте его в ca-certificate.pem.

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

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

CREATE DATABASE

Добавьте обе строки подключения в файл .env в корне проекта или в уже существующий .env. Они отличаются только портом, и обе указывают на базу данных guide_drizzle:

.env

# Runtime queries go through PgBouncer (port 6432)
DATABASE_URL="postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:6432/guide_drizzle?sslmode=verify-full&sslrootcert=ca-certificate.pem"
# drizzle-kit migrations connect directly to Postgres (port 5432)
DIRECT_DATABASE_URL="postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/guide_drizzle?sslmode=verify-full&sslrootcert=ca-certificate.pem"

node-postgres считывает sslmode=verify-full и sslrootcert из URL. Библиотека загружает файл CA и проверяет как цепочку сертификатов, так и имя хоста, поэтому писать дополнительный код для TLS не нужно. Путь sslrootcert вычисляется относительно каталога, из которого вы запускаете команды. Не добавляйте .env в систему контроля версий.

Если файл CA отсутствует или указан неверно, установить соединение не удастся: возникнет ошибка unable to verify the first certificate. Если имя хоста не совпадает с указанным в сертификате, возникнет ошибка ERR_TLS_CERT_ALTNAME_INVALID. Если пароль содержит специальные символы, например @, / или #, закодируйте их в формате URL-encoding.

​

Определите схему

Создайте файл src/db/schema.ts:

src/db/schema.ts

import { boolean, integer, pgTable, text, timestamp } from "drizzle-orm/pg-core";

export const todos = pgTable("todos", {
  id: integer().primaryKey().generatedAlwaysAsIdentity(),
  title: text().notNull(),
  done: boolean().notNull().default(false),
  createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
});

Создайте файл drizzle.config.ts в корне проекта. В нём для drizzle-kit указываются путь к схеме и параметры прямого соединения:

drizzle.config.ts

import "dotenv/config";
import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: "postgresql",
  schema: "./src/db/schema.ts",
  out: "./drizzle",
  dbCredentials: {
    // Migrations use the direct connection (port 5432)
    url: process.env.DIRECT_DATABASE_URL!,
  },
});

​

Применение миграций

Сгенерируйте SQL-миграцию на основе схемы:

npx drizzle-kit generate --name init

1 tables
todos 4 columns 0 indexes 0 fks

[✓] Your SQL migration file ➜ drizzle/0000_init.sql 🚀

Сгенерированный файл drizzle/0000_init.sql содержит оператор CREATE TABLE. Проверьте его и закоммитьте папку drizzle вместе с остальным кодом. Затем примените миграцию:

npx drizzle-kit migrate

Using 'pg' driver for database querying
[✓] migrations applied successfully!

drizzle-kit migrate записывает применённые миграции в таблицу drizzle.__drizzle_migrations и при последующих запусках выполняет только новые. После каждого изменения schema.ts снова запускайте generate, а затем migrate.

Если drizzle-kit migrate не удаётся подключиться, например из-за неверного пути sslrootcert или неправильного пароля, команда завершается с кодом 1 без какого-либо сообщения об ошибке. В таком случае сначала проверьте DIRECT_DATABASE_URL с помощью psql.

drizzle-kit push применяет изменения схемы без файлов миграций. Это удобно для прототипирования, но для продакшна лучше использовать generate и migrate: они создают SQL-файлы, доступные для ревью, и сохраняют историю изменений.

​

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

Создайте файл src/db/index.ts. В нём создаётся клиент Drizzle на основе пула node-postgres, который использует соединение через PgBouncer:

src/db/index.ts

import "dotenv/config";
import { drizzle } from "drizzle-orm/node-postgres";

// The app uses the PgBouncer connection (port 6432)
export const db = drizzle(process.env.DATABASE_URL!);

Создайте src/server.ts — небольшой HTTP-сервер, который выполняет по одному запросу Drizzle на каждый маршрут. В существующем приложении те же запросы db можно вызывать из собственных обработчиков маршрутов:

src/server.ts

import { createServer } from "node:http";
import { desc, eq, not } from "drizzle-orm";
import { db } from "./db";
import { todos } from "./db/schema";

const server = createServer(async (req, res) => {
  const url = new URL(req.url ?? "/", "http://localhost");
  const id = Number(url.pathname.split("/")[2]);
  let body: unknown;

  try {
    if (req.method === "GET" && url.pathname === "/todos") {
      // Read
      body = await db.select().from(todos).orderBy(desc(todos.id));
    } else if (req.method === "POST" && url.pathname === "/todos") {
      // Create
      const title = url.searchParams.get("title") ?? "Untitled";
      [body] = await db.insert(todos).values({ title }).returning();
    } else if (req.method === "PATCH" && id) {
      // Update: toggle the done flag
      [body] = await db
        .update(todos)
        .set({ done: not(todos.done) })
        .where(eq(todos.id, id))
        .returning();
    } else if (req.method === "DELETE" && id) {
      // Delete
      [body] = await db.delete(todos).where(eq(todos.id, id)).returning();
    } else {
      res.writeHead(404).end();
      return;
    }
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify(body, null, 2) + "\n");
  } catch (err) {
    console.error(err);
    res.writeHead(500).end("Database error\n");
  }
});

server.listen(3101, () => console.log("Listening on http://localhost:3101/todos"));

Для работы с PgBouncer настраивать драйвер не нужно. Запросы Drizzle по умолчанию используют безымянные операторы, а встроенный PgBouncer в режиме пулинга транзакций также поддерживает именованные подготовленные операторы, например созданные с помощью .prepare в Drizzle. Возможности уровня сеанса, такие как LISTEN и сеансовые рекомендательные блокировки (advisory locks), через PgBouncer не работают. Подробнее см. в FAQ.

​

Запуск и проверка

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

npx tsx src/server.ts

Listening on http://localhost:3101/todos

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

curl -X POST "http://localhost:3101/todos?title=Try%20Drizzle%20ORM"
curl -X POST "http://localhost:3101/todos?title=Write%20a%20migration"
curl -X PATCH http://localhost:3101/todos/1
curl -X DELETE http://localhost:3101/todos/2

Запрос PATCH возвращает обновлённую строку:

{
  "id": 1,
  "title": "Try Drizzle ORM",
  "done": true,
  "createdAt": "2026-09-30T16:45:14.610Z"
}

Откройте http://localhost:3101/todos в браузере, чтобы получить список оставшихся задач. Ответ будет выглядеть так:

[
  {
    "id": 1,
    "title": "Try Drizzle ORM",
    "done": true,
    "createdAt": "2026-09-30T16:45:14.610Z"
  }
]

Чтобы просмотреть данные в консоли, откройте консоль SQL на левой боковой панели сервиса, разверните guide_drizzle, затем public и нажмите на таблицу todos. В схеме drizzle хранится таблица истории миграций. В таблице осталась одна строка:

id	title	done	created_at
1	Try Drizzle ORM	true	2026-09-30 16:45:14.610099+00

​

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

• Подключение: строки подключения, PgBouncer и TLS
• Настройки: параметры Postgres и PgBouncer, например max_connections
• Реплики для чтения: масштабирование чтения с помощью withReplicas в Drizzle
• Безопасность: IP Access List и частное сетевое подключение