← Hyperdrive (Postgres & MySQL) / hyperdrive / examples

Подключение к PostgreSQL

Hyperdrive поддерживает PostgreSQL и совместимые с PostgreSQL базы данных, популярные драйверы и библиотеки Object Relational Mapper (ORM), использующие эти драйверы.

Чтобы создать Hyperdrive для подключения к существующей базе данных PostgreSQL, используйте wrangler CLI или Панель управления Cloudflare ↗.

При использовании wrangler замените значение-заполнитель, переданное в --connection-string строкой подключения к вашей базе данных:

# wrangler v3.11 and above required
npx wrangler hyperdrive create my-first-hyperdrive --connection-string="postgres://user:[email protected]:5432/databasenamehere"

Приведённая выше команда выведет ID вашего Hyperdrive, который потребуется указать в конфигурационный файл Wrangler для вашего проекта Workers:

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

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

См. Документация с примерами с пошаговыми инструкциями по настройке Hyperdrive для нескольких популярных провайдеров баз данных.

Hyperdrive использует Workers Поддержка TCP-сокетов для поддержки TCP подключений к базам данных. В следующей таблице перечислены поддерживаемые драйверы баз данных и минимальные версии, совместимые с Hyperdrive:

^ Отмеченные библиотеки используют node-postgres как зависимость.

Могут поддерживаться и другие драйверы и ORM, не указанные здесь: этот список не является исчерпывающим.

Совместимость с Node.js требуется для драйверов баз данных, включая Postgres.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.

Следующие примеры показывают, как:

1. Создайте клиент базы данных с помощью драйвера базы данных.
2. Передайте строку подключения Hyperdrive и подключитесь к базе данных.
3. Запросите данные из вашей базы данных через Hyperdrive.

Установите 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 });
		}
	},
};

Установка Postgres.js ↗:

npm i postgres@>3.4.5

Добавьте необходимые флаги совместимости 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>"

Создайте Worker, который подключается к вашей базе данных PostgreSQL через Hyperdrive:

// filepath: src/index.ts
import postgres from "postgres";

export default {
	async fetch(
		request: Request,
		env: Env,
		ctx: ExecutionContext,
	): Promise<Response> {
		// Create a database client that connects to your database via Hyperdrive.
		// Hyperdrive maintains the underlying database connection pool,
		// so creating a new client on each request is fast and recommended.
		const sql = postgres(env.HYPERDRIVE.connectionString, {
			// Limit the connections for the Worker request to 5 due to Workers' limits on concurrent external connections
			max: 5,
			// If you are not using array types in your Postgres schema, disable `fetch_types` to avoid an additional round-trip (unnecessary latency)
			fetch_types: false,

			// This is set to true by default, but certain query generators such as Kysely or queries using sql.unsafe() will set this to false. Hyperdrive will not cache prepared statements when this option is set to false and will require additional round-trips.  
			prepare: true,
		});

		try {
			// A very simple test query
			const result = await sql`select * from pg_tables`;

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

			return Response.error();
		}
	},
} satisfies ExportedHandler<Env>;

Чтобы определить активные подключения к серверу базы данных Postgres со стороны Hyperdrive:

• Подключения Hyperdrive к вашей базе данных будут отображаться с Cloudflare Hyperdrive в качестве application_name в pg_stat_activity в таблице.
• Запустите SELECT DISTINCT usename, application_name FROM pg_stat_activity WHERE application_name = 'Cloudflare Hyperdrive' чтобы показать, удерживает ли Hyperdrive в данный момент открытое соединение (или соединения) с вашей базой данных.

• Ознакомьтесь со списком поддерживаемые интеграции с базами данных чтобы узнать о других способах подключения к существующим базам данных.
• Подробнее об использовании Socket API в Worker.
• Изучите протоколы, поддерживаемые Workers.