← Hyperdrive (Postgres & MySQL) / hyperdrive

Начало работы

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

Поддерживая пул подключений к вашей базе данных внутри сети Cloudflare, Hyperdrive сокращает семь обращений к базе данных, которые иначе потребовались бы ещё до отправки запроса: TCP-рукопожатие (1 раз), согласование TLS (3 раза) и аутентификацию в базе данных (3 раза).

Hyperdrive различает запросы на чтение и запись к базе данных и кеширует наиболее частые запросы на чтение, повышая производительность и снижая нагрузку на исходную базу данных.

Это руководство проведёт вас через следующие шаги:

• Создание первой конфигурации Hyperdrive.
• Создание Cloudflare Worker и привяжите её к конфигурации Hyperdrive.
• Установление подключения к базе данных из Worker к публичной базе данных.

Прежде чем начать, убедитесь, что вы выполнили следующее:

1. Зарегистрируйтесь для получения Аккаунт Cloudflare ↗ если вы ещё этого не сделали.
2. Установка Node.js ↗. Используйте менеджер версий Node, например nvm ↗ или Volta ↗ чтобы избежать проблем с правами доступа и переключать версии Node.js. Wrangler требует версии Node 16.17.0 или более поздней версии.
3. Общедоступная база данных PostgreSQL или MySQL (либо совместимая с ними). Если ваша база данных находится в приватной сети, см. Подключение к частной базе данных через Workers VPC.

Прежде чем создавать привязку Hyperdrive, войдите в свой аккаунт Cloudflare, выполнив команду:

npx wrangler login

Вы будете перенаправлены на страницу с предложением войти в панель управления Cloudflare. После входа вас спросят, может ли Wrangler вносить изменения в вашу учётную запись Cloudflare. Прокрутите вниз и выберите Allow чтобы продолжить.

Создайте новый проект с именем hyperdrive-tutorial выполнив:

npm create cloudflare@latest -- hyperdrive-tutorial

Для настройки выберите следующие параметры:

• Для С чего вы хотите начать?, выберите Hello World example.
• Для Какой шаблон вы хотите использовать?, выберите Worker only.
• Для Какой язык вы хотите использовать?, выберите TypeScript.
• Для Хотите использовать git для контроля версий?, выберите Yes.
• Для Хотите развернуть приложение?, выберите No (мы внесём некоторые изменения перед развёртыванием).

Это создаст новый hyperdrive-tutorial каталог. Ваш новый hyperdrive-tutorial каталог будет включать:

• A "Hello World" Worker по адресу src/index.ts.
• A wrangler.jsonc файл конфигурации. wrangler.jsonc показывает, как выглядит ваш hyperdrive-tutorial Worker будет подключаться к Hyperdrive.

Совместимость с Node.js требуется для драйверов баз данных и должен быть настроен для вашего проекта Workers.

Для дат совместимости 2026-08-04 или более поздней версии проекты Workers и Pages включают оба nodejs_compat и nodejs_compat_v2 по умолчанию. Встроенные API среды выполнения и полифиллы доступны без дополнительной настройки. Для этих дат совместимости данные флаги не используются. Существующим проектам не нужно удалять их при обновлении даты совместимости.

Если ваша дата совместимости раньше 2026-08-04, добавьте nodejs_compat флаг совместимости в ваш конфигурационный файл Wrangler чтобы включить:

{
	"compatibility_flags": [
		"nodejs_compat"
	]
}

compatibility_flags = [ "nodejs_compat" ]

Чтобы отключить Совместимость с Node.js полностью при дате совместимости 2026-08-04 или более поздней версии удалите положительные флаги, если они есть. Затем добавьте оба no_nodejs_compat и no_nodejs_compat_v2. Примеры настройки см. в Флаг совместимости с Node.js.

Hyperdrive работает, подключаясь к вашей базе данных, объединяя подключения к ней в глобальный пул и ускоряя доступ к базе данных через сеть Cloudflare.

Это предоставит защищенную строку подключения, доступную только из вашего Worker, которую можно использовать для подключения к базе данных через Hyperdrive. Это значит, что строку подключения Hyperdrive можно использовать с уже имеющимися драйверами или ORM-библиотеками без значительных изменений в коде.

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

cd hyperdrive-tutorial

Чтобы создать первый Hyperdrive, вам потребуется:

• IP-адрес (или имя хоста) и порт вашей базы данных.
• Имя пользователя базы данных (например, hyperdrive-demo).
• Пароль, связанный с этим именем пользователя.
• Имя базы данных, к которой должен подключиться Hyperdrive. Например, postgres или mysql.

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

postgres://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name

npx wrangler hyperdrive create <YOUR_CONFIG_NAME> --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name"

mysql://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name

npx wrangler hyperdrive create <YOUR_CONFIG_NAME> --connection-string="mysql://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name"

В случае успеха команда выведет вашу новую конфигурацию Hyperdrive:

{
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<example id: 57b7076f58be42419276f058a8968187>"
		}
	]
}

Скопируйте id поле: оно понадобится на следующем шаге, чтобы сделать 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>"

После создания конфигурации Hyperdrive и её привязки к Worker вы можете выполнять запросы к своей базе данных.

# This should install v8.13.0 or later
npm i pg

# This should install v8.13.0 or later
npm i -D @types/pg

# This should install v3.13.0 or later
npm i mysql2

// pg 8.13.0 or later is recommended
import { Client } from "pg";

export interface Env {
	// If you set another name in the Wrangler config file as the value for 'binding',
	// replace "HYPERDRIVE" with the variable name you defined.
	HYPERDRIVE: Hyperdrive;
}

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

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

			// Sample query
			const results = await sql.query(`SELECT * FROM pg_tables`);

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

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

export interface Env {
	// If you set another name in the Wrangler config file as the value for 'binding',
	// replace "HYPERDRIVE" with the variable name you defined.
	HYPERDRIVE: Hyperdrive;
}

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,

			// The following line is needed for mysql2 compatibility with Workers
			// mysql2 uses eval() to optimize result parsing for rows with > 100 columns
			// Configure mysql2 to use static parsing instead of eval() parsing with disableEval
			disableEval: true,
		});

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

			// Return result rows as JSON
			return new Response(JSON.stringify({ results, fields }), {
				headers: {
					"Content-Type": "application/json",
					"Access-Control-Allow-Origin": "*",
				},
			});
		} catch (e) {
			console.error(e);
			return Response.json(
				{ error: e instanceof Error ? e.message : e },
				{ status: 500 },
			);
		}
	},
} satisfies ExportedHandler<Env>;

Перед развертыванием Worker можно протестировать локально, выполнив wrangler dev. При этом код Worker выполняется на вашем компьютере с подключением к базе данных.

localConnectionString поле работает как с локальными, так и с удаленными базами данных и позволяет подключаться напрямую к базе данных из Worker проекта, запущенного локально. При необходимости укажите режим SSL/TLS (sslmode=require для Postgres, sslMode=REQUIRED для MySQL).

Чтобы подключаться к базе данных при локальной разработке, настройте localConnectionString в вашем wrangler.jsonc:

{
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "your-hyperdrive-id",
			"localConnectionString": "postgres://user:password@your-database-host:5432/database",
		},
	],
}

Либо задайте переменную окружения:

export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:password@your-database-host:5432/database"

Затем запустите локальную разработку:

npx wrangler dev

Теперь можно развернуть Worker, чтобы сделать проект доступным в интернете. Чтобы развернуть Worker, выполните:

npx wrangler deploy
# Outputs: https://hyperdrive-tutorial.<YOUR_SUBDOMAIN>.workers.dev

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

Например, если URL вашего нового Worker равен hyperdrive-tutorial.<YOUR_SUBDOMAIN>.workers.dev, обращаясь к https://hyperdrive-tutorial.<YOUR_SUBDOMAIN>.workers.dev/ отправит запрос вашему Worker, который обращается напрямую к вашей базе данных.

Завершив это руководство, вы создали конфигурацию Hyperdrive, Worker для доступа к этой базе данных и развернули проект по всему миру.

• Подробнее о как работает Hyperdrive.
• Как настроить кеширование запросов.
• Устранение распространённых проблем при подключении базы данных к Hyperdrive.

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