Skip to main content
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, 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> и хост значениями из модального окна Подключение:
Добавьте обе строки подключения в файл .env в корне проекта или в уже существующий .env. Они отличаются только портом, и обе указывают на базу данных guide_drizzle:
.env
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
Создайте файл drizzle.config.ts в корне проекта. В нём для drizzle-kit указываются путь к схеме и параметры прямого соединения:
drizzle.config.ts

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

Сгенерируйте SQL-миграцию на основе схемы:
Сгенерированный файл drizzle/0000_init.sql содержит оператор CREATE TABLE. Проверьте его и закоммитьте папку drizzle вместе с остальным кодом. Затем примените миграцию:
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
Создайте src/server.ts — небольшой HTTP-сервер, который выполняет по одному запросу Drizzle на каждый маршрут. В существующем приложении те же запросы db можно вызывать из собственных обработчиков маршрутов:
src/server.ts
Для работы с PgBouncer настраивать драйвер не нужно. Запросы Drizzle по умолчанию используют безымянные операторы, а встроенный PgBouncer в режиме пулинга транзакций также поддерживает именованные подготовленные операторы, например созданные с помощью .prepare в Drizzle. Возможности уровня сеанса, такие как LISTEN и сеансовые рекомендательные блокировки (advisory locks), через PgBouncer не работают. Подробнее см. в FAQ.

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

Запустите сервер:
Во втором терминале создайте две задачи, отметьте первую как выполненную и удалите вторую:
Запрос PATCH возвращает обновлённую строку:
Откройте http://localhost:3101/todos в браузере, чтобы получить список оставшихся задач. Ответ будет выглядеть так:
Чтобы просмотреть данные в консоли, откройте консоль SQL на левой боковой панели сервиса, разверните guide_drizzle, затем public и нажмите на таблицу todos. В схеме drizzle хранится таблица истории миграций. В таблице осталась одна строка:

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