Skip to main content
Bun — это среда выполнения JavaScript и TypeScript со встроенным клиентом Postgres Bun.sql, поэтому устанавливать отдельный драйвер не нужно. В этом руководстве вы подключите Bun к ClickHouse Managed Postgres по TLS с проверкой сертификата, создадите таблицу, выполните запросы и транзакцию, а затем с помощью Bun.serve будете отдавать строки по HTTP.

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

  • Bun версии 1.4 или новее. Это руководство проверено на Bun 1.4.2 и Postgres 18.
  • Аккаунт ClickHouse Cloud.
  • psql для создания базы данных. Также можно выполнить оператор CREATE DATABASE в консоли SQL.

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

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

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

Откройте свой сервис и нажмите Подключение на левой боковой панели. Оставьте выбранным вариант Directly и включите Use SSL. URL теперь будет заканчиваться на sslmode=verify-full&sslrootcert=.... Нажмите Download CA certificate, чтобы скачать CA‑сертификат для вашего инстанса. В этом руководстве используется прямое подключение через порт 5432. Приложение Bun.serve работает как долгоживущий процесс, а Bun.sql поддерживает собственный пул соединений, поэтому пулер на стороне сервера не требуется. Если вы запускаете много кратковременных процессов Bun, см. раздел Подключение через PgBouncer.

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

Создайте проект:
Добавляете в существующее приложение?Пропустите mkdir и bun init -y: Bun.sql встроен в Bun, поэтому устанавливать ничего не нужно. В корне проекта перейдите к разделу Настройка соединения, а также добавьте NODE_EXTRA_CA_CERTS=./ca-certificate.pem перед командой запуска вашего приложения, чтобы оно могло проверить сертификат сервера.

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

Переместите загруженный CA‑сертификат в проект и переименуйте его в ca-certificate.pem:
Создайте базу данных для приложения. Замените <PASSWORD> и хост значениями из модального окна Подключение:
Добавьте URL подключения к базе данных guide_bun в файл .env (если файла нет, создайте его). Bun автоматически загружает .env, а экспорт sql из bun считывает переменную DATABASE_URL:
.env
Если пароль содержит специальные символы, закодируйте его для URL (URL-encoding). Не добавляйте .env в систему контроля версий. Добавьте эти скрипты в package.json; если блок scripts уже существует, объедините их с ним. Эти скрипты передают CA‑сертификат в Bun через NODE_EXTRA_CA_CERTS:
package.json
Как Bun проверяет сертификат сервера
  • sslmode=verify-full заставляет Bun.sql проверять и цепочку сертификатов, и имя хоста.
  • Не копируйте параметр sslrootcert из URL в консоли. Bun.sql не обрабатывает его, а передаёт серверу как параметр времени выполнения, и соединение завершается ошибкой unrecognized configuration parameter "sslrootcert".
  • Переменная NODE_EXTRA_CA_CERTS должна быть задана в окружении до запуска Bun. Bun не считывает её из .env, поэтому она задаётся в скриптах.
  • В Bun 1.4.2 передача скачанного сертификата через параметр tls: { ca } в SQL завершается ошибкой certificate signature failure. Используйте вместо этого NODE_EXTRA_CA_CERTS.

Создание таблицы

Создайте файл setup.ts. Он выводит состояние TLS для текущего сеанса и создаёт таблицу todos:
setup.ts
Выполните его:
Чтобы убедиться, что сертификат действительно проверяется, запустите файл без CA‑сертификата. Соединение будет отклонено:

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

Bun.sql использует тегированные шаблонные строки. Каждое подставляемое значение передаётся как параметр привязки, поэтому пользовательский ввод можно передавать безопасно. Создайте файл queries.ts:
queries.ts
sql.begin выполняет callback-функцию в рамках транзакции. Если callback-функция завершается успешно, транзакция фиксируется (коммит), а если она выбрасывает исключение — откатывается. Запустите пример:

Отдача строк по HTTP

Создайте файл server.ts с конечной точкой /todos, которая возвращает список строк и создаёт новые:
server.ts
Запустите сервер:
В другом терминале добавьте строку:

Проверка

Откройте http://localhost:3106/todos в браузере, чтобы увидеть все строки. Ответ будет выглядеть примерно так (отформатирован для удобства чтения):
В консоли откройте консоль SQL и последовательно разверните guide_bun, public и todos — вы увидите те же строки:

Подключение через PgBouncer

Если вы запускаете много кратковременных процессов Bun, лучше подключаться через встроенный PgBouncer. Выберите via PgBouncer в модальном окне Подключение и замените порт в DATABASE_URL на 6432. CA‑сертификат и sslmode=verify-full остаются без изменений. PgBouncer работает в режиме пулинга на уровне транзакций. Bun.sql по умолчанию использует именованные подготовленные операторы, и в наших тестах они работали через PgBouncer без ошибок. Если возникают ошибки prepared statement does not exist, создайте клиент с параметром prepare: false:
Передавайте prepare как параметр подключения, а не в URL. Как и в случае с sslrootcert, параметр URL prepare=false пересылается на сервер, и тот его отклоняет.

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

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