← Hyperdrive (Postgres & MySQL) / hyperdrive / configuration

Připojení k privátní databázi pomocí Tunnel

Hyperdrive se může bezpečně připojit k vašim privátním databázím pomocí Cloudflare Tunnel a Cloudflare Access.

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 tunelového připojení.
• Cloudflare Access slouží k omezení přístupu k vašemu tunelu tak, aby k němu měly přístup jen konkrétní konfigurace Hyperdrive.

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

Cloudflare Tunnel vytvoří odchozí obousměrné připojení z vaší privátní sítě do Cloudflare. Cloudflare Access zabezpečí váš Cloudflare Tunnel tak, aby k němu měla přístup pouze vaše konfigurace Hyperdrive.

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.
• Název hostitele ve vašem účtu Cloudflare, který se používá ke směrování požadavků do vaší databáze.

Nejprve vytvořte Cloudflare Tunnel ve vaší privátní síti a navázat tak zabezpečené spojení mezi vaší sítí a Cloudflare. Vaše síť musí být nakonfigurována tak, aby tunel měl oprávnění odesílat provoz do sítě Cloudflare a přistupovat k databázi ve vaší síti.

1. Přihlaste se do Cloudflare dashboardu a přejděte na Sítě > Tunnels.

   Přejděte na Tunnels ↗

2. Vyberte Vytvořit tunel.

3. Zadejte název tunelu. Doporučujeme zvolit název, který vystihuje typ prostředků, jež chcete přes tento tunel připojit (například enterprise-VPC-01).

4. Vyberte Create Tunnel.

5. Zvolte svůj operační systém, poté zkopírujte instalační příkaz a spusťte jej v terminálu na svém origin serveru.

6. Počkejte, až se tunel připojí. Jakmile bude spojení navázáno, vyberte Pokračovat.

Váš tunel musí být nakonfigurovaný tak, aby používal veřejný hostname na Cloudflare, aby k němu Hyperdrive mohl směrovat požadavky. Pokud na Cloudflare ještě nemáte hostname, budete muset zaregistrujte nový název hostitele nebo přidat zónu Cloudflare, abyste mohli pokračovat.

1. V Publikované trasy aplikace kartě zvolte Doména a zadejte případné informace o subdoméně nebo cestě. Tyto údaje se použijí ve vaší konfiguraci Hyperdrive ke směrování do tohoto tunelu.

2. V Služba sekci zadejte Typ TCP a adresu URL a nakonfigurovaný port vaší databáze, například localhost:5432 nebo my-database-host.database-provider.com:5432. Tuto adresu tunel použije ke směrování požadavků do vaší databáze.

3. Vyberte Uložit tunel.

Chcete-li omezit přístup k Cloudflare Tunnel pro Hyperdrive, je potřeba aplikace Cloudflare Access musí být nakonfigurován s Zásada vyžadující, aby požadavky obsahovaly platný Service Auth token.

Cloudflare dashboard umí automaticky vytvořit a nakonfigurovat podkladový aplikace Cloudflare Access, Service Auth token, a Zásada za vás. Aplikaci Access a Policies můžete také vytvořit a nakonfigurovat ručně.

# 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
  }
}

Chcete-li otestovat konfiguraci Hyperdrive k databázi přes Cloudflare Tunnel a Access, použijte ID konfigurace Hyperdrive ve svém Workeru a nasaďte ho.

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

Ověřte, že se z Workers můžete připojit ke své databázi a provádět dotazy.

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

Pokud při nastavování konfigurace Hyperdrive s tunely k privátní databázi narazíte na potíže, zvažte tato běžná řešení, kromě obecné kroky pro řešení problémů pro Hyperdrive:

• Ujistěte se, že je vaše databáze nakonfigurována pro použití TLS (SSL). Hyperdrive vyžaduje k připojení TLS (SSL).