Использование Cloudflare Workers с ClickHouse Managed Postgres

Выполнение запросов к ClickHouse Managed Postgres из Cloudflare Worker через Hyperdrive: node-postgres, TLS с проверкой сертификата, локальная разработка и развертывание на workers.dev

Cloudflare Workers выполняют ваш код в сети Cloudflare, а Hyperdrive поддерживает пул соединений из этой сети с вашей базой данных, поэтому при каждом запросе не нужно заново выполнять TCP- и TLS-рукопожатие. В этом руководстве вы создадите конфигурацию Hyperdrive, которая проверяет сертификат вашего инстанса, напишете на TypeScript Worker, который создаёт и читает строки с помощью node-postgres (pg), запустите его локально командой wrangler dev и развернёте на workers.dev.

​

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

• Аккаунт Cloudflare. Hyperdrive доступен на тарифах Workers Free и Paid.
• Node.js версии 20 или выше. Это руководство проверено с Node.js 24.21.0, Wrangler 4.145.0, create-cloudflare 2.73.1, pg 8.23.1 и Postgres 18.
• Аккаунт ClickHouse Cloud.
• psql для создания базы данных и таблицы. SQL-операторы также можно выполнить в консоли SQL.

​

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

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

​

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

Нажмите Connect на левой боковой панели вашего сервиса. Оставьте выбранным вариант Directly и включите Use SSL. URL теперь заканчивается на sslmode=verify-full&sslrootcert=<service-name>-ca-certificate.pem. Нажмите Download CA certificate, чтобы скачать CA‑сертификат для вашего инстанса. Его также можно скачать в разделе Settings → CA Certificate.

В этом руководстве Hyperdrive подключается напрямую через порт 5432, а не через встроенный PgBouncer на порту 6432:

• Hyperdrive сам является пулером соединений и работает в режиме транзакций. Он поддерживает небольшой пул долгоживущих соединений с базой данных и распределяет их между всеми запросами Worker, то есть берёт на себя ту работу, которую иначе выполнял бы PgBouncer. Cloudflare рекомендует указывать для Hyperdrive строку прямого подключения, а не подключения через пул.
• Направить Hyperdrive на порт 6432 тоже можно, но цепочка из двух пулеров в режиме транзакций добавляет лишний сетевой переход и ещё одно место, где нужно настраивать размеры пулов, при этом не увеличивая пропускную способность.
• Hyperdrive открывает не более примерно 20 соединений на одну конфигурацию в тарифе Workers Free и около 100 — в тарифе Paid. Это укладывается в значение max_connections по умолчанию, равное 500. Если на одном инстансе работают несколько конфигураций Hyperdrive или другие клиенты, суммируйте их соединения и при необходимости измените max_connections в разделе Settings или лимит соединений с источником в Hyperdrive.

Если вы используете IP Access List, учтите, что Hyperdrive подключается из диапазонов IP-адресов Cloudflare, поэтому их необходимо разрешить.

​

Создание базы данных

Переименуйте загруженный сертификат в ca-certificate.pem. Затем создайте базу данных и таблицу notes. Замените <PASSWORD> и хост на значения из модального окна Подключение:

psql "postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/postgres?sslmode=verify-full&sslrootcert=ca-certificate.pem" -c "CREATE DATABASE guide_cloudflare;"

psql "postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/guide_cloudflare?sslmode=verify-full&sslrootcert=ca-certificate.pem" -c "CREATE TABLE notes (id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, content text NOT NULL, created_at timestamptz NOT NULL DEFAULT now());"

CREATE TABLE

​

Создание проекта Worker

Создайте Worker на TypeScript из шаблона «Hello World» с помощью create-cloudflare и установите pg:

npm create cloudflare@latest -- hyperdrive-notes --type=hello-world --lang=ts --no-deploy
cd hyperdrive-notes
npm install pg
npm install -D @types/pg

Добавляете в существующее приложение?

Пропустите npm create cloudflare. В проекте Worker выполните npm install pg и npm install -D @types/pg, затем перейдите к разделам Создание конфигурации Hyperdrive, где добавляется привязка Hyperdrive, и Настройка Worker, где включается nodejs_compat.

Переместите ca-certificate.pem в каталог проекта. Если вы ещё не работали с Wrangler, выполните npx wrangler login, чтобы авторизовать его в своём аккаунте Cloudflare.

​

Создание конфигурации Hyperdrive

Hyperdrive всегда шифрует соединение с базой данных, но по умолчанию не проверяет сертификат по CA вашего инстанса. Чтобы добиться поведения, аналогичного sslmode=verify-full, сначала загрузите CA‑сертификат в свой аккаунт Cloudflare:

npx wrangler cert upload certificate-authority --ca-cert ca-certificate.pem --name managed-postgres-ca

Success! Uploaded CA Certificate managed-postgres-ca
ID: <CA_CERTIFICATE_ID>

Создайте конфигурацию Hyperdrive, указав ID из вывода команды. В строке подключения указываются порт 5432 и база данных guide_cloudflare, параметры SSL в ней не задаются: TLS настраивается с помощью флагов --sslmode и --ca-certificate-id:

npx wrangler hyperdrive create managed-postgres \
  --connection-string="postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/guide_cloudflare" \
  --ca-certificate-id <CA_CERTIFICATE_ID> \
  --sslmode verify-full \
  --caching-disabled \
  --binding HYPERDRIVE \
  --update-config

✅ Created new Hyperdrive PostgreSQL config: <HYPERDRIVE_ID>

При создании конфигурации Hyperdrive подключается к вашей базе данных. С параметром --sslmode verify-full он проверяет, что сертификат сервера подписан загруженным вами CA и соответствует имени хоста. Если хотя бы одна из проверок не пройдена, команда завершается ошибкой, например cert verification failed - unable to get local issuer certificate, и конфигурация не создаётся. Пароль хранится в конфигурации Hyperdrive в вашем аккаунте Cloudflare, а не в проекте.

--binding HYPERDRIVE --update-config добавляет конфигурацию в wrangler.jsonc, чтобы ваш Worker мог обращаться к ней через env.HYPERDRIVE. Если в проекте используется wrangler.toml, Wrangler этот файл не изменяет — вставьте в него фрагмент [[hyperdrive]], который выводит команда.

Кэширование запросов

Hyperdrive может кэшировать результаты запросов на чтение — по умолчанию на 60 секунд. В этом руководстве кэширование отключено с помощью --caching-disabled, чтобы чтение сразу после записи возвращало новую строку. Для запросов с интенсивным чтением, для которых допустимы немного устаревшие результаты, можно создать вторую конфигурацию с включённым кэшированием и привязать обе. См. Кэширование запросов.

​

Настройка Worker

Для работы pg требуется слой совместимости с Node.js. Откройте wrangler.jsonc и добавьте флаг nodejs_compat рядом с compatibility_date. Соответствующий фрагмент файла будет выглядеть так:

wrangler.jsonc

{
	"name": "hyperdrive-notes",
	"main": "src/index.ts",
	"compatibility_date": "2026-09-26",
	"compatibility_flags": ["nodejs_compat"],
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<HYPERDRIVE_ID>"
		}
	]
}

Если вы используете файл wrangler.toml, добавьте строку compatibility_flags = ["nodejs_compat"] под compatibility_date. Если в файле уже есть compatibility_flags, добавьте nodejs_compat в этот список.

Заново сгенерируйте типы TypeScript, чтобы для env.HYPERDRIVE был определён тип:

npx wrangler types

Если в вашем проекте по-прежнему используется пакет @cloudflare/workers-types, команда wrangler types выведет инструкции по переходу на сгенерированные типы.

​

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

Замените содержимое src/index.ts кодом Worker, который создаёт заметку при запросе POST /notes и возвращает список всех заметок при запросе GET /notes. Если у вас уже есть Worker, просто добавьте такую же обработку /notes в свой обработчик fetch:

src/index.ts

import { Client } from "pg";

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const url = new URL(request.url);
		if (url.pathname !== "/notes") {
			return new Response("Not found", { status: 404 });
		}

		// Hyperdrive keeps the connections to Postgres, so a new client per request is cheap.
		const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
		await client.connect();

		try {
			if (request.method === "POST") {
				// Create
				const { content } = await request.json<{ content: string }>();
				const { rows } = await client.query(
					"INSERT INTO notes (content) VALUES ($1) RETURNING id, content, created_at",
					[content],
				);
				return Response.json(rows[0], { status: 201 });
			}

			// Read
			const { rows } = await client.query("SELECT id, content, created_at FROM notes ORDER BY id");
			return Response.json(rows);
		} finally {
			// Close the client after the response is sent.
			ctx.waitUntil(client.end());
		}
	},
} satisfies ExportedHandler<Env>;

env.HYPERDRIVE.connectionString указывает на Hyperdrive, а не на ваш инстанс. Связь между Worker и Hyperdrive не выходит за пределы Cloudflare, поэтому параметры SSL для неё не нужны. Проверенное TLS‑соединение с Postgres устанавливает сам Hyperdrive.

Hyperdrive работает в режиме транзакций, как PgBouncer: каждая транзакция может использовать отдельное соединение с Postgres. Параметризованные запросы, транзакции и именованные подготовленные операторы из pg полностью поддерживаются. Не рассчитывайте на сохранение состояния сеанса между запросами (например, SET на уровне сеанса) — вместо этого используйте SET LOCAL внутри транзакции.

​

Локальный запуск

wrangler dev запускает Worker на вашем компьютере. При локальном запуске Hyperdrive не использует пул соединений: привязка подключается напрямую к базе данных, указанной в CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING>. Укажите в этой переменной строку прямого подключения с параметром sslmode=verify-full и путём к CA‑сертификату, после чего запустите Worker:

export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/guide_cloudflare?sslmode=verify-full&sslrootcert=ca-certificate.pem"
npx wrangler dev --port 3108

Found a non-empty CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE variable for binding. Hyperdrive will connect to this database during local development.
...
Ready on http://localhost:3108

Wrangler берёт на себя TLS для локального соединения. Путь sslrootcert задаётся относительно каталога, из которого вы запускаете wrangler dev.

Если не указать sslmode, локальное соединение не шифруется. При sslmode=require соединение шифруется, но сертификат не проверяется. Всегда используйте sslmode=verify-full вместе с sslrootcert. Если сертификат CA отсутствует или указан неверно, запросы завершаются с ошибкой Connection terminated unexpectedly.

Во втором терминале создайте заметку:

curl -X POST http://localhost:3108/notes -H "Content-Type: application/json" -d '{"content": "Hello from wrangler dev"}'

{"id":"1","content":"Hello from wrangler dev","created_at":"2026-09-30T16:58:16.232Z"}

Выведите список заметок:

curl http://localhost:3108/notes

[{"id":"1","content":"Hello from wrangler dev","created_at":"2026-09-30T16:58:16.232Z"}]

pg возвращает столбцы типа bigint в виде строк, поэтому значение id — "1", а не 1.

​

Развертывание

Разверните воркер:

npx wrangler deploy

Your Worker has access to the following bindings:
Binding                                   Resource
env.HYPERDRIVE (<HYPERDRIVE_ID>)          Hyperdrive Config

Uploaded hyperdrive-notes (2.35 sec)
Deployed hyperdrive-notes triggers (0.76 sec)
  https://hyperdrive-notes.<your-subdomain>.workers.dev

Если это ваш первый Worker, Wrangler предложит зарегистрировать поддомен workers.dev. Создайте заметку с помощью развернутого Worker:

curl -X POST https://hyperdrive-notes.<your-subdomain>.workers.dev/notes -H "Content-Type: application/json" -d '{"content": "Hello from Hyperdrive"}'

{"id":"2","content":"Hello from Hyperdrive","created_at":"2026-09-30T16:58:39.733Z"}

Откройте https://hyperdrive-notes.<your-subdomain>.workers.dev/notes в браузере — там должны отобразиться обе заметки. Ответ будет выглядеть так:

[{"id":"1","content":"Hello from wrangler dev","created_at":"2026-09-30T16:58:16.232Z"},{"id":"2","content":"Hello from Hyperdrive","created_at":"2026-09-30T16:58:39.733Z"}]

​

Проверка в консоли

Откройте консоль SQL на левой боковой панели вашего сервиса, разверните guide_cloudflare, затем public и выберите таблицу notes. В ней будут обе заметки:

id	content	created_at
1	Hello from wrangler dev	2026-09-30 16:58:16.232466+00
2	Hello from Hyperdrive	2026-09-30 16:58:39.733203+00

​

Очистка ресурсов

Чтобы удалить всё, что вы создали в аккаунте Cloudflare, удалите Worker, конфигурацию Hyperdrive и CA‑сертификат:

npx wrangler delete
npx wrangler hyperdrive delete <HYPERDRIVE_ID>
npx wrangler cert delete --name managed-postgres-ca

Если wrangler cert delete выдаёт ошибку Certificate cannot be deleted while in use, подождите минуту после удаления конфигурации Hyperdrive и повторите команду.

​

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

• Подключение: строки подключения, PgBouncer и TLS
• Настройки: параметры Postgres, например max_connections
• Реплики для чтения: масштабирование нагрузки на чтение
• Документация Hyperdrive: кэширование запросов, настройка пула соединений и обсервабилити