← Hyperdrive (Postgres & MySQL) / hyperdrive / configuration

Подключение к частной базе данных через Workers VPC (рекомендуется)

Workers VPC предоставляет способ подключения Hyperdrive к приватной базе данных без настройки приложений Cloudflare Access или сервисных токенов. Вместо этого вы создаёте TCP VPC Service который указывает на вашу базу данных, и передайте его идентификатор службы в Hyperdrive.

Об использовании Tunnel и Access см. Подключение к частной базе данных через Tunnel.

Если ваша база данных изолирована в частной сети (например, виртуальное частное облако ↗ или локальной сети), необходимо включить защищённое соединение от вашей сети к Cloudflare.

• Cloudflare Tunnel используется для установления безопасного исходящего соединения из вашей приватной сети к Cloudflare.
• A VPC Service используется для маршрутизации трафика от вашего Worker через туннель к базе данных без необходимости использования приложений Cloudflare Access или сервисных токенов.

Запрос от Cloudflare Worker к исходной базе данных проходит через Hyperdrive, VPC Service и Cloudflare Tunnel, установленный cloudflared. cloudflared должен быть запущен в приватной сети, в которой доступна ваша база данных.

flowchart LR
    A[Cloudflare Worker] --> B[Hyperdrive] --> C[VPC Service] --> D[Cloudflare Tunnel] --> E[Private Database]

Во всех руководствах предполагается, что вы уже выполнили Руководство по началу работы, который поможет вам настроить аккаунт Cloudflare Workers, C3 ↗, а также Wrangler.

• База данных в вашей частной сети, настроен на использование TLS/SSL.
• A Cloudflare Tunnel который работает в сети с доступом к вашей базе данных.
• Connectivity Directory Admin роль в вашем аккаунте Cloudflare для создания VPC Services.

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

Туннель должен иметь доступ к хосту и порту базы данных из частной сети.

Полную документацию по туннелям см. в Cloudflare Tunnel для Workers VPC.

Создайте VPC Service типа tcp который указывает на вашу базу данных. Укажите --app-protocol флаг для postgresql или mysql чтобы Hyperdrive мог оптимизировать соединения.

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>

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

Замените:

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

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

Вы также можете создать TCP VPC Service из Панель управления Workers VPC ↗. См. Службы VPC со всеми параметрами конфигурации.

В отличие от Hyperdrive, который по умолчанию не проверяет сертификат исходного сервера, Workers VPC по умолчанию verify_full проверяет и цепочку сертификатов, и имя хоста. Если ваша база данных использует самоподписанный сертификат или сертификат от частного центра сертификации (ЦС), согласование TLS завершится ошибкой, если вы не измените режим проверки.

Для баз данных с самоподписанными сертификатами добавьте --cert-verification-mode при создании VPC Service:

• verify_ca проверяет цепочку сертификатов, но пропускает проверку имени хоста. Используйте этот режим, если сертификат вашей базы данных подписан подконтрольным вам ЦС, но имя хоста не совпадает с сертификатом.
• disabled полностью пропускает проверку сертификата. Используйте этот режим только для разработки или тестирования.

Например, чтобы создать VPC-сервис для базы данных PostgreSQL с самоподписанным сертификатом:

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> \
  --cert-verification-mode verify_ca

Чтобы обновить существующий VPC Service, используйте wrangler vpc service update тем же флагом.

Полный список режимов проверки см. в Режим проверки сертификата TLS.

Используйте --service-id флаг, чтобы указать Hyperdrive на созданный вами VPC Service. При использовании --service-id, вы не указываете --origin-host, --origin-port, или --connection-string. Вместо этого Hyperdrive направляет трафик через VPC Service.

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

npx wrangler hyperdrive create <YOUR_CONFIG_NAME> \
  --service-id <YOUR_VPC_SERVICE_ID> \
  --database <DATABASE_NAME> \
  --user <DATABASE_USER> \
  --password <DATABASE_PASSWORD> \
  --scheme mysql

Замените:

• <YOUR_VPC_SERVICE_ID> идентификатором службы (service ID) из шага 2.
• <DATABASE_NAME> именем вашей базы данных.
• <DATABASE_USER> и <DATABASE_PASSWORD> учетными данными вашей базы данных.

В случае успеха команда выведет конфигурацию Hyperdrive с id поле. Скопируйте этот ID, он понадобится на следующем шаге.

Необходимо создать привязку в конфигурационный файл 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>"

npm i pg@>8.16.3

npm i -D @types/pg

{
	// 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>"

// 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 });
		}
	},
};

npx wrangler deploy

npm i mysql2@>3.13.0

{
	// 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>"

// mysql2 v3.13.0 or later is required
import { createConnection } from "mysql2/promise";

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Create a new connection on each request. Hyperdrive maintains the underlying
		// database connection pool, so creating a new connection is fast.
		const connection = await createConnection({
			host: env.HYPERDRIVE.host,
			user: env.HYPERDRIVE.user,
			password: env.HYPERDRIVE.password,
			database: env.HYPERDRIVE.database,
			port: env.HYPERDRIVE.port,

			// Required to enable mysql2 compatibility for Workers
			disableEval: true,
		});

		try {
			// Sample query
			const [results, fields] = await connection.query("SHOW tables;");

			// Return result rows as JSON
			return Response.json({ results, fields });
		} catch (e) {
			console.error(e);
			return Response.json(
				{ error: e instanceof Error ? e.message : e },
				{ status: 500 },
			);
		}
	},
} satisfies ExportedHandler<Env>;

npx wrangler deploy

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