pg) — самый популярный драйвер Postgres для Node.js. В этом руководстве вы подключитесь к ClickHouse Managed Postgres через pg.Pool с полной проверкой TLS-сертификата, создадите две таблицы, переведёте деньги между счетами в рамках транзакции и организуете отдачу данных с помощью небольшого сервера на node:http.
Предварительные требования
- Node.js версии 20.6 или новее (для встроенного флага
--env-file). Это руководство проверено на Node.js 24.21.0 иpg8.23.1. - Аккаунт ClickHouse Cloud
psqlдля создания базы данных
Создание сервиса ClickHouse Managed Postgres
В консоли ClickHouse Cloud нажмите New service и выберите Postgres. Инстанс будет готов через несколько минут. Пошаговые инструкции приведены в кратком руководстве.Получите сведения о подключении
Нажмите Connect на левой боковой панели вашего сервиса. Выбрав Directly, скопируйте URL подключения на вкладке url. Параметр Use SSL оставьте выключенным: приложение передаёт CA‑сертификат в коде, а не в URL (см. Настройка пула соединений). В этом руководстве используется прямое подключение к Postgres через порт5432. Долго работающий сервер Node.js и так поддерживает собственный пул соединений через pg.Pool, поэтому дополнительный пулер перед Postgres ему не нужен. Если вы запускаете много процессов или serverless-функций, используйте вместо этого встроенный PgBouncer (см. Использование PgBouncer).
Затем скачайте CA‑сертификат для своего инстанса. Включите Use SSL и нажмите Download CA certificate или перейдите в Settings → CA Certificate → Download CA certificate. У каждого инстанса свой уникальный сертификат.
Настройка проекта
Создайте проект и установитеpg:
.mjs, поэтому они работают независимо от того, какая система модулей указана в вашем package.json: CommonJS или ES-модули.
Создайте базу данных
Переместите скачанный файл<service-name>-ca-certificate.pem в каталог проекта и переименуйте его в ca-certificate.pem. Затем создайте базу данных для приложения:
.env и укажите в нём скопированный URL подключения, заменив имя базы данных на guide_nodejs, а также путь к сертификату:
.env
@, / или #, закодируйте их в URL с помощью процентного кодирования (percent-encoding).
Настройка пула соединений
Создайте файлdb.mjs. Он экспортирует единый пул, общий для всего остального приложения:
db.mjs
ssl: { ca } эквивалентна sslmode=verify-full: pg проверяет, что сертификат сервера подписан CA вашего инстанса и соответствует имени хоста. По умолчанию rejectUnauthorized имеет значение true; не меняйте его на false.
Создание схемы
Создайте файлsetup.mjs. Он создаёт таблицы, вставляет два аккаунта с помощью параметризованных запросов, а затем считывает их:
setup.mjs
$1, $2, …), а не встраивайте их в строку SQL с помощью конкатенации. pg отправляет их отдельно от текста запроса, что защищает от SQL-инъекций. Массивы JavaScript преобразуются в массивы Postgres, как в запросе с ANY($1).
Запустите его:
pg возвращает значения типа numeric (и bigint) в виде строк, чтобы избежать потери точности. Если вам нужны числа, явно преобразуйте их.
Выполнение запросов в транзакции
Транзакция должна выполняться в рамках одного соединения, поэтому получите клиент из пула с помощьюpool.connect и обязательно освобождайте его после использования. Создайте файл transfer.mjs:
transfer.mjs
pool.query для выполнения операторов внутри транзакции: каждый вызов pool.query может выполняться через другое соединение.
Отдача данных по HTTP
Создайте файлserver.mjs. Он отдаёт аккаунты и переводы в формате JSON на порту 3107, принимает новые переводы и корректно завершает работу по сигналу SIGINT (Ctrl+C) или SIGTERM:
server.mjs
pool.end один раз — при завершении процесса, а не после каждого запроса. Метод дожидается, пока все выданные клиенты вернутся в пул, а затем закрывает все соединения.
Проверка
Запустите сервер:alice, когда произошёл сбой, но ROLLBACK отменил это списание. Откройте в браузере http://localhost:3107/accounts, чтобы посмотреть балансы. Ответ будет выглядеть примерно так:
pg_stat_ssl:
DATABASE_CA_CERT любой другой сертификат, установить соединение не удастся: появится ошибка unable to verify the first certificate. Это подтверждает, что сертификат сервера действительно проверяется.
Наконец, остановите сервер, нажав Ctrl+C. Он выведет SIGINT received, shutting down, а затем Pool closed.
Данные также можно просмотреть в консоли. Откройте консоль SQL, разверните базу данных guide_nodejs и откройте таблицу accounts:
Использование PgBouncer
Чтобы подключаться через встроенный PgBouncer, выберите via PgBouncer в модальном окне Connect и укажите порт6432 в DATABASE_URL. Изменять код не нужно, а CA‑сертификат остаётся прежним.
PgBouncer работает в режиме пулинга транзакций (transaction pooling), поэтому каждая транзакция может выполняться в отдельном соединении с Postgres. При использовании pg:
- Параметризованные запросы, именованные подготовленные операторы (
pool.query({ name, text, values })) и транзакции черезpool.connectработают так, как показано в этом руководстве. - SQL-команды
PREPAREиEXECUTE, а также настройки сеанса, заданные с помощьюSET, не сохраняются между транзакциями. Вместо этого используйтеSET LOCALвнутри транзакции. pg_stat_sslпоказывает соединение между PgBouncer и Postgres, поэтому приведённый выше запрос для проверки TLS возвращаетssl: false. При этом соединение вашего приложения с PgBouncer по-прежнему проверяется: с неверным CA‑сертификатом подключение завершится такой же ошибкой.
Дальнейшие шаги
- Подключение: строки подключения, PgBouncer и TLS
- Настройки: изменение параметров, например
max_connections - Реплики для чтения: направление запросов только для чтения на реплику
- Высокая доступность: резервные экземпляры и автоматическое переключение при отказе