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.
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 блокировка может так и остаться на одном из соединений пула, а последующие запуски миграций будут зависать в ее ожидании.
6432, тот же хост). Kysely с pg корректно работает в режиме пулинга транзакций, поскольку pg по умолчанию использует безымянные подготовленные операторы. Миграции же по-прежнему выполняйте через порт 5432. См. раздел Пулинг соединений PgBouncer.
Настройка проекта
Создайте проект и установите Kysely, драйверpg и TypeScript:
Настройка соединения
Переместите загруженный CA‑сертификат в каталог проекта и переименуйте его вca-certificate.pem. Затем создайте базу данных для приложения:
.env или в уже существующий .env. Замените <PASSWORD> на свой пароль, имя базы данных — на guide_kysely, а параметру sslrootcert задайте значение ca-certificate.pem:
.env
pg считывает sslmode и sslrootcert из строки подключения: при значении verify-full он проверяет, что сертификат сервера подписан CA вашего сервиса и соответствует имени хоста. Путь sslrootcert разрешается относительно рабочего каталога — при использовании npm run это корень проекта.
Добавьте файл 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_migration, поэтому повторный запуск команды ни к чему не приведёт.
Выполнение запросов к базе данных
Создайтеsrc/server.mts — небольшой HTTP-сервер, который с помощью Kysely создаёт, читает, обновляет и удаляет задачи (to-do). В существующем приложении те же запросы можно использовать в собственных обработчиках маршрутов:
src/server.mts
Database, опечатка в имени таблицы или столбца, как и вставка без обязательного поля title, приводит к ошибке проверки типов. Проверьте проект:
Проверка
Запустите сервер:npm start запускает ваше собственное приложение, запустите пример сервера командой node --env-file=.env src/server.mts.
В другом терминале создайте, измените и удалите несколько задач:
guide_kysely и схему public, затем выберите таблицу todo. Рядом с ней отображаются созданные Kysely таблицы kysely_migration и kysely_migration_lock:
Дальнейшие шаги
- Подключение: строки подключения, PgBouncer и TLS.
- Настройки: настройка параметров PostgreSQL и PgBouncer, например
max_connections. - Реплики для чтения: масштабирование рабочих нагрузок с интенсивным чтением.
- Документация Kysely: JOIN, транзакции и генерация типов.