← Cloudflare Workers VPC / workers-vpc / examples

Подключение к приватной базе данных

В этом примере показано, как выполнять запросы к приватной базе данных PostgreSQL из Worker с использованием Workers VPC и Hyperdrive. Worker подключается к базе данных, не имеющей доступа из публичного интернета, а Hyperdrive обеспечивает пул соединений и ускорение выполнения запросов.

• База данных PostgreSQL, запущенная в вашей частной сети (например, на порту 5432)
• A Cloudflare Tunnel подключенный к приватной сети, в которой работает ваша база данных
• Аккаунт Cloudflare с доступом к Workers VPC

Если у вас еще нет туннеля, работающего в той же сети, что и ваша база данных, создайте его.

Туннель должен иметь возможность обращаться к хосту и порту вашей базы данных внутри частной сети. Полную документацию по туннелям смотрите в Cloudflare Tunnel для Workers VPC.

Создайте VPC Service типа tcp который указывает на вашу базу данных:

npx wrangler vpc service create my-postgres-db \
  --type tcp \
  --tcp-port 5432 \
  --app-protocol postgresql \
  --tunnel-id <YOUR_TUNNEL_ID> \
  --ipv4 <YOUR_DATABASE_IP>

Замените <YOUR_TUNNEL_ID> с идентификатором туннеля из шага 1 и <YOUR_DATABASE_IP> приватным IP-адресом вашей базы данных (например, 10.0.0.5).

Команда возвращает ID сервиса. Сохраните это значение для следующего шага.

Используйте --service-id флаг, чтобы направить Hyperdrive на созданный вами VPC Service:

npx wrangler hyperdrive create my-vpc-database \
  --service-id <YOUR_VPC_SERVICE_ID> \
  --database <DATABASE_NAME> \
  --user <DATABASE_USER> \
  --password <DATABASE_PASSWORD> \
  --scheme postgresql

Замените <YOUR_VPC_SERVICE_ID> с идентификатором службы из шага 2 и укажите имя базы данных, пользователя и пароль.

Команда выводит ID конфигурации Hyperdrive. Скопируйте его для следующего шага.

Необходимо создать привязку в конфигурационный файл Wrangler чтобы ваш Worker мог подключиться к конфигурации Hyperdrive. Bindings позволяют вашим Workers обращаться к ресурсам платформы разработчика Cloudflare, таким как Hyperdrive.

Чтобы привязать конфигурацию Hyperdrive к своему Worker, добавьте следующее в конец файла Wrangler:

{
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<YOUR_DATABASE_ID>" // the ID associated with the Hyperdrive you just created
		}
	]
}

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<YOUR_DATABASE_ID>"

А именно:

• Значение (строка), которое вы задали для binding (имя привязки) будет использоваться для обращения к этой базе данных в вашем Worker. В этом руководстве назовите привязку HYPERDRIVE.
• Привязка должна быть допустимое имя переменной JavaScript ↗. Например, binding = "hyperdrive" или binding = "productionDB" оба варианта были бы допустимыми именами для привязки.
• Привязка доступна в Worker по адресу env.<BINDING_NAME>.

Если вы хотите использовать локальную базу данных при разработке, вы можете добавить localConnectionString в вашу конфигурацию Hyperdrive со строкой подключения к вашей базе данных:

{
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<YOUR_DATABASE_ID>", // the ID associated with the Hyperdrive you just created
			"localConnectionString": "<LOCAL_DATABASE_CONNECTION_URI>"
		}
	]
}

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<YOUR_DATABASE_ID>"
localConnectionString = "<LOCAL_DATABASE_CONNECTION_URI>"

Установите node-postgres драйвер:

npm i pg@>8.16.3

При использовании TypeScript установите пакет типов:

npm i -D @types/pg

Добавьте необходимые флаги совместимости Node.js и привязку Hyperdrive в свой wrangler.jsonc файле:

{
	// required for database drivers to function
	"compatibility_flags": [
		"nodejs_compat"
	],
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<your-hyperdrive-id-here>"
		}
	]
}

compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-08-28"

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<your-hyperdrive-id-here>"

Создайте новый Client экземпляр и передайте Hyperdrive connectionString:

// filepath: src/index.ts
import { Client } from "pg";

export default {
	async fetch(
		request: Request,
		env: Env,
		ctx: ExecutionContext,
	): Promise<Response> {
		// Create a new client instance for each request. Hyperdrive maintains the
		// underlying database connection pool, so creating a new client is fast.
		const client = new Client({
			connectionString: env.HYPERDRIVE.connectionString,
		});

		try {
			// Connect to the database
			await client.connect();

			// Perform a simple query
			const result = await client.query("SELECT * FROM pg_tables");

			return Response.json({
				success: true,
				result: result.rows,
			});
		} catch (error: any) {
			console.error("Database error:", error.message);

			return new Response("Internal error occurred", { status: 500 });
		}
	},
};

Разверните ваш Worker:

npx wrangler deploy

Отправьте запрос, чтобы проверить соединение:

curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev

Успешный ответ возвращает массив JSON со строками из вашей базы данных.

• Подробнее о как работает Hyperdrive
• Настройте кеширование запросов для Hyperdrive
• Проверьте Параметры конфигурации VPC Service включая проверку TLS-сертификата
• Изучите другие примеры