← Hyperdrive (Postgres & MySQL) / hyperdrive / examples

Připojení k PostgreSQL

Hyperdrive podporuje databáze PostgreSQL a databáze kompatibilní s PostgreSQL, oblíbené ovladače a knihovny Object Relational Mapper (ORM), které tyto ovladače využívají.

Chcete-li vytvořit Hyperdrive, který se připojí k existující databázi PostgreSQL, použijte wrangler CLI nebo Cloudflare dashboard ↗.

Při použití wrangler nahraďte zástupnou hodnotu předanou parametru --connection-string s připojovacím řetězcem pro vaši databázi:

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

Výše uvedený příkaz vypíše ID vašeho Hyperdrive, které budete potřebovat nastavit v Konfigurační soubor Wrangler pro váš projekt 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>"

Díky tomu bude moci Hyperdrive ve vašem Workeru vygenerovat dynamický connection string, který můžete předat stávajícímu databázovému ovladači. Více informací najdete v Příklady ovladače a zjistěte, jak nastavit databázový ovladač s Hyperdrive.

Viz Dokumentace s příklady podrobné návody, jak nastavit Hyperdrive s několika oblíbenými poskytovateli databází.

Hyperdrive využívá Workers Podpora TCP socketů pro podporu TCP připojení k databázím. Následující tabulka uvádí podporované databázové ovladače a minimální verzi, která s Hyperdrive funguje:

^ Označené knihovny používají node-postgres jako závislost.

Podporovány mohou být i další ovladače a ORM, které zde nejsou uvedeny: tento seznam není vyčerpávající.

Kompatibilita s Node.js je vyžadován pro databázové ovladače, včetně Postgres.js, a je nutné ho nakonfigurovat pro váš projekt Workers.

Pro data kompatibility 2026-08-04 nebo novější mají projekty Workers a Pages povolené oba nodejs_compat a nodejs_compat_v2 ve výchozím nastavení. Vestavěná runtime API a polyfilly jsou dostupné bez dalšího nastavení. Tyto příznaky se pro tato data kompatibility nepoužívají. Stávající projekty je při aktualizaci data kompatibility nemusí odebírat.

Pokud je vaše datum kompatibility starší než 2026-08-04, přidejte nodejs_compat příznak kompatibility do vašeho Konfigurační soubor Wrangler abyste se přihlásili:

{
	"compatibility_flags": [
		"nodejs_compat"
	]
}

compatibility_flags = [ "nodejs_compat" ]

Chcete-li vypnout Kompatibilita s Node.js zcela pro datum kompatibility 2026-08-04 nebo novější odeberte pozitivní příznaky, pokud jsou přítomné. Poté přidejte oba no_nodejs_compat a no_nodejs_compat_v2. Příklady konfigurace najdete v Příznak kompatibility s Node.js.

Následující příklady ukazují, jak:

1. Vytvořte databázového klienta pomocí databázového ovladače.
2. Předejte connection string Hyperdrive a připojte se k databázi.
3. Proveďte dotaz na databázi přes Hyperdrive.

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 });
		}
	},
};

Nainstalujte Postgres.js ↗:

npm i postgres@>3.4.5

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 Worker, který se přes Hyperdrive připojuje k vaší databázi PostgreSQL:

// 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>;

Chcete-li zjistit aktivní připojení k serveru databáze Postgres z Hyperdrive:

• Připojení Hyperdrive k vaší databázi se zobrazí s Cloudflare Hyperdrive jako application_name v pg_stat_activity tabulka.
• Spustit SELECT DISTINCT usename, application_name FROM pg_stat_activity WHERE application_name = 'Cloudflare Hyperdrive' k zobrazení toho, zda Hyperdrive aktuálně drží otevřené připojení (nebo připojení) k vaší databázi.

• Přečtěte si seznam podporované databázové integrace a zjistěte další způsoby připojení k existujícím databázím.
• Další informace o tom, jak používat Socket API ve Workeru.
• Seznamte se s protokoly podporované službou Workers.