← Hyperdrive (Postgres & MySQL) / hyperdrive / configuration

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

Hyperdrive может безопасно подключаться к вашим приватным базам данных с помощью Cloudflare Tunnel и Cloudflare Access.

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

• Cloudflare Tunnel используется для установления безопасного туннельного соединения.
• Cloudflare Access используется для ограничения доступа к вашему туннелю так, чтобы к нему могли обращаться только определённые конфигурации Hyperdrive.

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

Cloudflare Tunnel устанавливает исходящее двунаправленное соединение из вашей частной сети с Cloudflare. Cloudflare Access защищает Cloudflare Tunnel, ограничивая доступ к нему только конфигурацией Hyperdrive.

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

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

Сначала создайте Cloudflare Tunnel в вашей приватной сети, чтобы установить безопасное соединение между вашей сетью и Cloudflare. Ваша сеть должна быть настроена так, чтобы туннель имел разрешения на исходящий трафик к сети Cloudflare и доступ к базе данных внутри вашей сети.

1. Войдите в панель управления Cloudflare и перейдите в Сеть > Tunnels.

   Перейдите в Tunnels ↗

2. Выберите Создать туннель.

3. Введите имя туннеля. Рекомендуем выбрать имя, отражающее тип ресурсов, которые вы хотите подключить через этот туннель (например, enterprise-VPC-01).

4. Выберите Create Tunnel.

5. Выберите операционную систему, затем скопируйте команду установки и выполните её в терминале на вашем исходном сервере.

6. Дождитесь подключения туннеля. После установления соединения выберите Продолжение.

Туннель должен быть настроен на использование публичного hostname в Cloudflare, чтобы Hyperdrive мог направлять на него запросы. Если у вас ещё нет hostname в Cloudflare, вам нужно будет зарегистрируйте новое имя хоста или добавить зону в Cloudflare, чтобы продолжить.

1. В Опубликованные маршруты приложения вкладке выберите Домен и укажите поддомен или путь, если это необходимо. Эта информация будет использована в конфигурации Hyperdrive для маршрутизации к этому туннелю.

2. В Сервис раздел и укажите Тип TCP а также URL и настроенный порт вашей базы данных, например, localhost:5432 или my-database-host.database-provider.com:5432. Этот адрес будет использоваться туннелем для маршрутизации запросов к вашей базе данных.

3. Выберите Сохранить туннель.

Чтобы ограничить для Hyperdrive доступ к Cloudflare Tunnel, потребуется Приложение Cloudflare Access должен быть настроен с Политика который требует, чтобы запросы содержали действительный Токен Service Auth.

Панель управления Cloudflare может автоматически создать и настроить базовый Приложение Cloudflare Access, Токен Service Auth, а также Политика от вашего имени. Либо вы можете вручную создать приложение Access и настроить Policies.

# wrangler v3.65 and above required
npx wrangler hyperdrive create <NAME-OF-HYPERDRIVE-CONFIGURATION-FOR-DB-VIA-TUNNEL> --host=<HOSTNAME-FOR-THE-TUNNEL> --user=<USERNAME-FOR-YOUR-DATABASE> --password=<PASSWORD-FOR-YOUR-DATABASE> --database=<DATABASE-TO-CONNECT-TO> --access-client-id=<YOUR-ACCESS-CLIENT-ID> --access-client-secret=<YOUR-SERVICE-TOKEN-CLIENT-SECRET>

resource "cloudflare_hyperdrive_config"  "<TERRAFORM_VARIABLE_NAME_FOR_CONFIGURATION>" {
  account_id = "<YOUR_ACCOUNT_ID>"
  name       = "<NAME_OF_HYPERDRIVE_CONFIGURATION>"
  origin     = {
    host     = "<HOSTNAME_OF_TUNNEL>"
    database = "<NAME_OF_DATABASE>"
    user     = "<NAME_OF_DATABASE_USER>"
    password = "<DATABASE_PASSWORD>"
    scheme   = "postgres"
    access_client_id     = "<ACCESS_CLIENT_ID>"
    access_client_secret = "<ACCESS_CLIENT_SECRET>"
  }
  caching = {
    disabled = false
  }
}

Чтобы протестировать подключение конфигурации Hyperdrive к базе данных через Cloudflare Tunnel и Access, укажите идентификатор этой конфигурации Hyperdrive в своём Worker и разверните его.

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

Убедитесь, что можете подключиться к базе данных из Workers и выполнять запросы.

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:

• Убедитесь, что база данных настроена на использование TLS (SSL). Для подключения Hyperdrive требуется TLS (SSL).