Skip to main content
Kysely — это типобезопасный конструктор SQL-запросов для TypeScript. В этом руководстве вы подключите Kysely к ClickHouse Managed Postgres через драйвер pg с проверкой сертификата TLS, создадите таблицу с помощью миграций Kysely и развернёте на Node.js небольшой API для списка задач.

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

  • Node.js 22.18 или новее: начиная с этой версии файлы TypeScript запускаются напрямую, без этапа сборки. Файлы в этом руководстве имеют расширение .mts, поэтому Node.js обрабатывает их как ES-модули независимо от того, использует ли проект CommonJS или ES-модули.
  • Аккаунт ClickHouse Cloud.
  • psql для создания базы данных. Также можно выполнить оператор CREATE DATABASE в консоли SQL.
  • curl для обращения к API.
Руководство протестировано с Node.js 24.21, Kysely 0.29.6, pg 8.23.1, TypeScript 7.0.2 и PostgreSQL 18.

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

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

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

Нажмите Connect на левой боковой панели вашего сервиса. Оставьте выбранным вариант Directly и включите Use SSL: теперь строка подключения url заканчивается на sslmode=verify-full&sslrootcert=.... Нажмите Download CA certificate, чтобы скачать CA‑сертификат вашего сервиса (файл <service-name>-ca-certificate.pem), и скопируйте строку подключения. В этом руководстве подключение к Postgres выполняется напрямую через порт 5432. На то есть две причины:
  • Сервер Node.js — это долгоживущий процесс. Pool из pg и так держит открытыми несколько соединений и переиспользует их, поэтому пулер на стороне сервера почти ничего не дает.
  • Migrator в Kysely на время выполнения миграций удерживает рекомендательную блокировку уровня сеанса (pg_advisory_lock). PgBouncer работает в режиме пулинга транзакций, поэтому захват блокировки, выполнение миграций и освобождение блокировки могут попасть на разные backend-соединения. В результате при работе через PgBouncer блокировка может так и остаться на одном из соединений пула, а последующие запуски миграций будут зависать в ее ожидании.
Если позже вы будете запускать много инстансов приложения или serverless-функций, строку подключения приложения можно перенаправить на PgBouncer (порт 6432, тот же хост). Kysely с pg корректно работает в режиме пулинга транзакций, поскольку pg по умолчанию использует безымянные подготовленные операторы. Миграции же по-прежнему выполняйте через порт 5432. См. раздел Пулинг соединений PgBouncer.

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

Создайте проект и установите Kysely, драйвер pg и TypeScript:
Добавляете в существующее приложение?Пропустите mkdir kysely-todo && cd kysely-todo и npm init -y. Выполните в своём проекте следующие команды — они добавят скрипты migrate и typecheck, не затрагивая ваш скрипт start, — а затем переходите к разделу Настройка соединения.

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

Переместите загруженный CA‑сертификат в каталог проекта и переименуйте его в ca-certificate.pem. Затем создайте базу данных для приложения:
Добавьте скопированную строку подключения в новый файл .env или в уже существующий .env. Замените <PASSWORD> на свой пароль, имя базы данных — на guide_kysely, а параметру sslrootcert задайте значение ca-certificate.pem:
.env
pg считывает sslmode и sslrootcert из строки подключения: при значении verify-full он проверяет, что сертификат сервера подписан CA вашего сервиса и соответствует имени хоста. Путь sslrootcert разрешается относительно рабочего каталога — при использовании npm run это корень проекта.
Не удаляйте sslmode=verify-full из URL. Без sslmode pg не использует TLS и не проверяет сервер. Не передавайте в Pool ещё и объект ssl: если URL содержит sslmode, настройки из URL заменяют ваш объект ssl. Если CA нужно загружать не из файла, удалите sslmode и sslrootcert из URL и передайте в Pool параметр ssl: { ca }.
Добавьте файл tsconfig.json, чтобы tsc проверял типы в тех же файлах, которые запускает Node.js. Если в вашем приложении уже есть tsconfig.json, объедините его с этими compilerOptions и добавьте в него папку migrations:
tsconfig.json

Определение интерфейса базы данных

Kysely типизирует каждый запрос на основе интерфейса, описывающего ваши таблицы. Создайте файл src/db.mts, содержащий этот интерфейс и экземпляр Kysely, который использует PostgresDialect с Pool из pg:
src/db.mts
Generated помечает столбцы, значения которых заполняет база данных, поэтому при вставке их можно не указывать.

Создание и запуск миграции

В этом руководстве используется встроенный в Kysely класс Migrator вместе с FileMigrationProvider, который входит в основной пакет kysely. Отдельная CLI-утилита kysely-ctl не обязательна и является обёрткой над тем же Migrator. Создайте файл миграции. Kysely выполняет миграции в алфавитно-цифровом порядке имён файлов, поэтому начинайте имя файла с даты:
migrations/2026-09-30_create_todo.mts
Создайте файл src/migrate.mts, который будет применять все ещё не применённые миграции. В Kysely 0.29 импортируйте Migrator и FileMigrationProvider из kysely/migration:
src/migrate.mts
Запустите миграцию:
Kysely фиксирует применённые миграции в таблице kysely_migration, поэтому повторный запуск команды ни к чему не приведёт.
Чтобы убедиться, что pg действительно проверяет сертификат, запустите миграцию без sslrootcert. По умолчанию Node.js не доверяет CA вашего сервиса, поэтому установить соединение не удастся:

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

Создайте src/server.mts — небольшой HTTP-сервер, который с помощью Kysely создаёт, читает, обновляет и удаляет задачи (to-do). В существующем приложении те же запросы можно использовать в собственных обработчиках маршрутов:
src/server.mts
Поскольку каждый запрос проверяется на соответствие интерфейсу Database, опечатка в имени таблицы или столбца, как и вставка без обязательного поля title, приводит к ошибке проверки типов. Проверьте проект:

Проверка

Запустите сервер:
Если вы работаете с уже существующим приложением, где npm start запускает ваше собственное приложение, запустите пример сервера командой node --env-file=.env src/server.mts. В другом терминале создайте, измените и удалите несколько задач:
Откройте http://localhost:3000/todos в браузере, чтобы просмотреть список оставшихся задач. Ответ будет выглядеть так:
Чтобы увидеть те же данные в консоли, откройте консоль SQL на левой боковой панели вашего сервиса, разверните guide_kysely и схему public, затем выберите таблицу todo. Рядом с ней отображаются созданные Kysely таблицы kysely_migration и kysely_migration_lock:

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

Последнее изменение 14 октября 2026 г.