← Cloudflare Workers VPC / workers-vpc / examples

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

Tento příklad ukazuje, jak z Workeru dotazovat privátní databázi PostgreSQL pomocí Workers VPC a Hyperdrive. Worker se připojuje k databázi, která není vystavena veřejnému internetu, přičemž Hyperdrive zajišťuje sdružování připojení a zrychlení dotazů.

• Databáze PostgreSQL běžící ve vaší privátní síti (například na portu 5432)
• A Cloudflare Tunnel připojený k soukromé síti, ve které běží vaše databáze
• Účet Cloudflare s přístupem k Workers VPC

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

Tunel musí mít z privátní sítě přístup k hostiteli a portu vaší databáze. Úplnou dokumentaci k tunelům najdete v Cloudflare Tunnel pro Workers VPC.

Vytvořte VPC Service typu tcp která odkazuje na vaši databázi:

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>

Nahraďte <YOUR_TUNNEL_ID> s ID tunelu z kroku 1 a <YOUR_DATABASE_IP> se soukromou IP adresou vaší databáze (například 10.0.0.5).

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

Použijte --service-id příznak, aby Hyperdrive směřoval na vytvořenou VPC Service:

npx wrangler hyperdrive create my-vpc-database \
  --service-id <YOUR_VPC_SERVICE_ID> \
  --database <DATABASE_NAME> \
  --user <DATABASE_USER> \
  --password <DATABASE_PASSWORD> \
  --scheme postgresql

Nahraďte <YOUR_VPC_SERVICE_ID> s ID služby z kroku 2 a zadejte název databáze, uživatele a heslo.

Příkaz vypíše ID konfigurace Hyperdrive. Zkopírujte si ho 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>"

Nainstalujte node-postgres ovladač:

npm i pg@>8.16.3

Pokud používáte TypeScript, nainstalujte balíček typů:

npm i -D @types/pg

Přidejte potřebné příznaky kompatibility s Node.js a vazbu Hyperdrive do svého wrangler.jsonc soubor:

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

Vytvořte nový Client instance a předejte 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 });
		}
	},
};

Nasaďte svůj Worker:

npx wrangler deploy

Odešlete požadavek a ověřte připojení:

curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev

Úspěšná odpověď vrací pole JSON s řádky z vaší databáze.

• 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
• Prozkoumejte další příklady