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.
Настройка проекта
Создайте проект:Настройка соединения
Переместите загруженный CA‑сертификат в проект и переименуйте его вca-certificate.pem:
<PASSWORD> и хост значениями из модального окна Подключение:
guide_bun в файл .env (если файла нет, создайте его). Bun автоматически загружает .env, а экспорт sql из bun считывает переменную DATABASE_URL:
.env
.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
Выполнение запросов к базе данных
Bun.sql использует тегированные шаблонные строки. Каждое подставляемое значение передаётся как параметр привязки, поэтому пользовательский ввод можно передавать безопасно. Создайте файл queries.ts:
queries.ts
sql.begin выполняет callback-функцию в рамках транзакции. Если callback-функция завершается успешно, транзакция фиксируется (коммит), а если она выбрасывает исключение — откатывается.
Запустите пример:
Отдача строк по HTTP
Создайте файлserver.ts с конечной точкой /todos, которая возвращает список строк и создаёт новые:
server.ts
Проверка
Откройте http://localhost:3106/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 пересылается на сервер, и тот его отклоняет.
Дальнейшие шаги
- Подключение: строки подключения, PgBouncer и TLS
- Настройки: изменение параметров Postgres и PgBouncer
- Реплики для чтения: масштабирование нагрузки на чтение
- Документация Bun SQL: полное описание API
Bun.sql