← Hyperdrive (Postgres & MySQL) / hyperdrive / configuration

Připojení k privátní databázi pomocí Workers VPC (doporučeno)

Workers VPC poskytuje způsob, jak připojit Hyperdrive k privátní databázi bez konfigurace aplikací Cloudflare Access nebo servisních tokenů. Místo toho vytvoříte TCP VPC Service směřující k vaší databázi a jeho ID služby předejte Hyperdrive.

Postup využívající Tunnel a Access najdete v Připojení k privátní databázi pomocí Tunnel.

Pokud je vaše databáze izolována v privátní síti (například virtuální privátní cloud ↗ nebo lokální síti), musíte povolit zabezpečené připojení z vaší sítě do Cloudflare.

• Cloudflare Tunnel slouží k navázání zabezpečeného odchozího připojení z vaší privátní sítě do Cloudflare.
• A VPC Service slouží ke směrování provozu z vašeho Workeru přes tunel do vaší databáze, aniž byste potřebovali aplikace Cloudflare Access nebo servisní tokeny.

Požadavek z Cloudflare Worker do zdrojové databáze prochází přes Hyperdrive, službu VPC Service a Cloudflare Tunnel vytvořený pomocí cloudflared. cloudflared musí běžet v privátní síti, v níž je vaše databáze dostupná.

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

Všechny návody předpokládají, že jste již dokončili Úvodní návod, který vás provede nastavením účtu Cloudflare Workers, C3 ↗, a Wrangler.

• Databáze ve vaší privátní síti, nakonfigurovaná pro TLS/SSL.
• A Cloudflare Tunnel spuštěný v síti, ze které je dostupná vaše databáze.
• Connectivity Directory Admin roli ve vašem účtu Cloudflare pro vytváření VPC Services.

Pokud ve stejné síti jako vaše databáze ještě nemáte spuštěný tunel, vytvořte si ho.

Tunel musí být schopný z privátní sítě dosáhnout na hostitele a port vaší databáze.

Úplnou dokumentaci k tunelu najdete v Cloudflare Tunnel pro Workers VPC.

Vytvořte VPC Service typu tcp směřující k vaší databázi. Nastavte --app-protocol příznak pro postgresql nebo mysql aby Hyperdrive mohl optimalizovat připojení.

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>

Nahraďte:

• <YOUR_TUNNEL_ID> s ID tunelu z kroku 1.
• <YOUR_DATABASE_IP> se soukromou IP adresou vaší databáze (například 10.0.0.5). Můžete také použít --hostname s názvem DNS místo --ipv4.

Příkaz vrátí ID služby. Tuto hodnotu si uložte pro další krok.

TCP VPC Service můžete také vytvořit z Dashboard Workers VPC ↗. Viz VPC služby všechny možnosti konfigurace.

Na rozdíl od Hyperdrive, který ve výchozím nastavení neověřuje certifikát zdrojového serveru, Workers VPC ve výchozím nastavení verify_full : ověřuje jak řetězec certifikátů, tak název hostitele. Pokud vaše databáze používá certifikát podepsaný sama sebou nebo certifikát od soukromé certifikační autority (CA), navázání TLS spojení selže, pokud režim ověřování neupravíte.

U databází se samopodepsanými certifikáty přidejte --cert-verification-mode při vytváření VPC Service:

• verify_ca : Ověří řetězec certifikátů, ale přeskočí ověření názvu hostitele. Použijte, pokud má vaše databáze certifikát podepsaný certifikační autoritou (CA), kterou spravujete, ale název hostitele certifikátu neodpovídá.
• disabled : Zcela přeskočí ověření certifikátu. Použijte pouze pro vývoj nebo testování.

Chcete-li například vytvořit VPC Service pro databázi PostgreSQL se samopodepsaným certifikátem:

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

Chcete-li aktualizovat existující VPC Service, použijte wrangler vpc service update se stejným příznakem.

Úplný seznam režimů ověřování najdete v Režim ověřování certifikátu TLS.

Použijte --service-id parametr, kterým nasměrujete Hyperdrive na vytvořenou VPC Service. Když použijete --service-id, pokud neuvedete --origin-host, --origin-port, nebo --connection-string. Hyperdrive místo toho směruje provoz přes 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

Nahraďte:

• <YOUR_VPC_SERVICE_ID> s ID služby z kroku 2.
• <DATABASE_NAME> s názvem vaší databáze.
• <DATABASE_USER> a <DATABASE_PASSWORD> s přihlašovacími údaji k vaší databázi.

V případě úspěchu příkaz vypíše konfiguraci Hyperdrive s id pole. Toto ID si zkopírujte pro další krok.

Vazbu musíte vytvořit v Konfigurační soubor Wrangler pro připojení vašeho Workeru ke konfiguraci Hyperdrive. Bindings umožňují vašim Workers přistupovat ke zdrojům, jako je Hyperdrive, na vývojářské platformě Cloudflare.

Chcete-li konfiguraci Hyperdrive svázat s Workerem, přidejte na konec souboru Wrangler následující:

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

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

Konkrétně:

• Hodnota (řetězec), kterou jste nastavili pro binding (název bindingu) se použije k odkazu na tuto databázi ve vašem Workeru. V tomto tutoriálu pojmenujte binding HYPERDRIVE.
• Binding musí být platný název proměnné v JavaScriptu ↗. Například binding = "hyperdrive" nebo binding = "productionDB" by byly oba platné názvy pro binding.
• Váš binding je ve Workeru dostupný na env.<BINDING_NAME>.

Pokud chcete během vývoje používat lokální databázi, můžete přidat localConnectionString do konfigurace Hyperdrive připojovacím řetězcem vaší databáze:

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

• Další informace o jak funguje Hyperdrive.
• Nakonfigurujte ukládání dotazů do mezipaměti pro Hyperdrive.
• Zkontrolujte Možnosti konfigurace VPC Service včetně ověřování certifikátu TLS.
• Nastavení tunely s vysokou dostupností pro produkční zátěž.
• Řešení běžných problémů při připojování databáze k Hyperdrive.