INTEGRITY Dokumentace

← Hyperdrive (Postgres & MySQL) / hyperdrive

Začínáme

Hyperdrive zrychluje přístup k vašim stávajícím databázím z Cloudflare Workers, díky čemuž i databáze v jediném regionu působí jako globálně distribuované.

Hyperdrive udržuje fond připojení k vaší databázi v síti Cloudflare, čímž ještě před samotným odesláním dotazu eliminuje sedm zpátečních cest k databázi: navázání TCP spojení (1x), vyjednávání TLS (3x) a ověření v databázi (3x).

Hyperdrive rozlišuje mezi čtecími a zápisovými dotazy do vaší databáze a nejčastější čtecí dotazy ukládá do mezipaměti, čímž zlepšuje výkon a snižuje zátěž vaší zdrojové databáze.

Tento návod vás provede:

Předpoklady

Než začnete, ujistěte se, že jste splnili následující:

  1. Zaregistrujte si účet Cloudflare ↗ pokud jste to ještě neudělali.
  2. Nainstalujte Node.js ↗. Použijte správce verzí Node, například nvm ↗ nebo Volta ↗ abyste se vyhnuli problémům s oprávněními a mohli měnit verze Node.js. Wrangler vyžaduje verzi Node 16.17.0 nebo novější.
  3. Mějte veřejně přístupnou databázi PostgreSQL nebo MySQL (nebo kompatibilní). Pokud je vaše databáze v privátní síti, přečtěte si Připojení k privátní databázi pomocí Workers VPC.

1. Přihlaste se

Než vytvoříte binding Hyperdrive, přihlaste se ke svému účtu Cloudflare spuštěním:

npx wrangler login

Budete přesměrováni na webovou stránku s výzvou k přihlášení do dashboardu Cloudflare. Po přihlášení se zobrazí dotaz, zda Wrangler smí provádět změny ve vašem účtu Cloudflare. Přejděte dolů a vyberte Allow pokračovat.

2. Vytvořte Worker

Vytvořte nový projekt s názvem hyperdrive-tutorial spuštěním:

npm create cloudflare@latest -- hyperdrive-tutorial

Při nastavení vyberte následující možnosti:

Tímto vytvoříte nový hyperdrive-tutorial adresáři. Váš nový hyperdrive-tutorial adresář bude obsahovat:

Povolení kompatibility s Node.js

Kompatibilita s Node.js je vyžadován pro ovladače databáze a je nutné jej 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.

3. Připojte Hyperdrive k databázi

Hyperdrive funguje tak, že se připojí k vaší databázi, globálně sdružuje databázová připojení do poolu a zrychluje přístup k databázi prostřednictvím sítě Cloudflare.

Poskytne zabezpečený connection string, který je dostupný pouze z vašeho Workeru a který můžete použít k připojení k databázi prostřednictvím Hyperdrive. Znamená to, že connection string Hyperdrive můžete použít se svými stávajícími ovladači nebo ORM knihovnami, aniž byste museli výrazně měnit svůj kód.

Chcete-li vytvořit svou první konfiguraci databáze Hyperdrive, přejděte do adresáře, který jste právě vytvořili pro svůj projekt Workers:

cd hyperdrive-tutorial

Pro vytvoření prvního Hyperdrive budete potřebovat:

Hyperdrive přijímá kombinaci těchto parametrů ve standardním formátu connection string používaném databázovými ovladači:


postgres://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name

Většina poskytovatelů databází nabízí connection string, který můžete přímo zkopírovat a vložit do Hyperdrive.

Chcete-li vytvořit připojení Hyperdrive, spusťte wrangler příkaz a nahraďte zástupné hodnoty předané parametru --connection-string parametru hodnotami vaší existující databáze:

npx wrangler hyperdrive create <YOUR_CONFIG_NAME> --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name"

mysql://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name

Většina poskytovatelů databází nabízí connection string, který můžete přímo zkopírovat a vložit do Hyperdrive.

Chcete-li vytvořit připojení Hyperdrive, spusťte wrangler příkaz a nahraďte zástupné hodnoty předané parametru --connection-string parametru hodnotami vaší existující databáze:

npx wrangler hyperdrive create <YOUR_CONFIG_NAME> --connection-string="mysql://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name"

V případě úspěchu příkaz vypíše vaši novou konfiguraci Hyperdrive:

{
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<example id: 57b7076f58be42419276f058a8968187>"
		}
	]
}

Zkopírujte id pole: tuto hodnotu použijete v dalším kroku, abyste zpřístupnili Hyperdrive ve svém Worker skriptu.

4. Přiřaďte svůj Worker k Hyperdrive

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ě:

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

5. Spusťte dotaz vůči své databázi

Jakmile vytvoříte konfiguraci Hyperdrive a přiřadíte ji ke svému Workeru, můžete proti databázi spustit dotaz.

Instalace databázového ovladače

Pro připojení k databázi budete potřebovat databázový ovladač, který umožňuje ověření a dotazování databáze. V tomto návodu použijete node-postgres (pg) ↗, jeden z nejpoužívanějších ovladačů PostgreSQL.

Chcete-li nainstalovat pg, ujistěte se, že se nacházíte v hyperdrive-tutorial adresáři. Otevřete terminál a spusťte následující příkaz:

# This should install v8.13.0 or later
npm i pg

Pokud používáte TypeScript, měli byste si nainstalovat také definice typů pro pg:

# This should install v8.13.0 or later
npm i -D @types/pg

Po instalaci ovladače můžete vytvořit skript Workeru, který se dotazuje vaší databáze.

Pro připojení k databázi budete potřebovat databázový ovladač, který umožňuje ověření a dotazování databáze. V tomto návodu použijete mysql2 ↗, jeden z nejpoužívanějších ovladačů MySQL.

Chcete-li nainstalovat mysql2, ujistěte se, že se nacházíte v hyperdrive-tutorial adresáři. Otevřete terminál a spusťte následující příkaz:

# This should install v3.13.0 or later
npm i mysql2

Po instalaci ovladače můžete vytvořit skript Workeru, který se dotazuje vaší databáze.

Napište Worker

Po nastavení databáze spustíte SQL dotaz přímo ve svém Worker.

Přejděte na hyperdrive-tutorial Worker a otevřete index.ts .

index.ts soubor slouží ke konfiguraci interakcí vašeho Workeru s Hyperdrive.

Naplňte svůj index.ts soubor následujícím kódem:

// pg 8.13.0 or later is recommended
import { Client } from "pg";

export interface Env {
	// If you set another name in the Wrangler config file as the value for 'binding',
	// replace "HYPERDRIVE" with the variable name you defined.
	HYPERDRIVE: Hyperdrive;
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Create a new client on each request. Hyperdrive maintains the underlying
		// database connection pool, so creating a new client is fast.
		const sql = new Client({
			connectionString: env.HYPERDRIVE.connectionString,
		});

		try {
			// Connect to the database
			await sql.connect();

			// Sample query
			const results = await sql.query(`SELECT * FROM pg_tables`);

			// Return result rows as JSON
			return Response.json(results.rows);
		} catch (e) {
			console.error(e);
			return Response.json(
				{ error: e instanceof Error ? e.message : e },
				{ status: 500 },
			);
		}
	},
} satisfies ExportedHandler<Env>;

Po přijetí požadavku provede výše uvedený kód následující:

  1. Vytvoří nového databázového klienta nastaveného tak, aby se k vaší databázi připojoval přes Hyperdrive pomocí connection stringu Hyperdrive.
  2. Zahájí dotaz prostřednictvím await sql.query() vypisující všechny tabulky v databázi (vytvořené uživatelem i systémem) jako příklad dotazu.
  3. Vrátí odpověď klientovi ve formátu JSON. Hyperdrive po skončení požadavku automaticky ukončí připojení klienta a podkladové připojení k databázi ponechá otevřené ve svém fondu pro další použití.

Po nastavení databáze spustíte SQL dotaz přímo ve svém Worker.

Přejděte na hyperdrive-tutorial Worker a otevřete index.ts .

index.ts soubor slouží ke konfiguraci interakcí vašeho Workeru s Hyperdrive.

Naplňte svůj index.ts soubor následujícím kódem:

// mysql2 v3.13.0 or later is required
import { createConnection } from "mysql2/promise";

export interface Env {
	// If you set another name in the Wrangler config file as the value for 'binding',
	// replace "HYPERDRIVE" with the variable name you defined.
	HYPERDRIVE: Hyperdrive;
}

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,

			// The following line is needed for mysql2 compatibility with Workers
			// mysql2 uses eval() to optimize result parsing for rows with > 100 columns
			// Configure mysql2 to use static parsing instead of eval() parsing with disableEval
			disableEval: true,
		});

		try {
			// Sample query
			const [results, fields] = await connection.query("SHOW tables;");

			// Return result rows as JSON
			return new Response(JSON.stringify({ results, fields }), {
				headers: {
					"Content-Type": "application/json",
					"Access-Control-Allow-Origin": "*",
				},
			});
		} catch (e) {
			console.error(e);
			return Response.json(
				{ error: e instanceof Error ? e.message : e },
				{ status: 500 },
			);
		}
	},
} satisfies ExportedHandler<Env>;

Po přijetí požadavku provede výše uvedený kód následující:

  1. Vytvoří nového databázového klienta nastaveného tak, aby se k vaší databázi připojoval přes Hyperdrive pomocí connection stringu Hyperdrive.
  2. Zahájí dotaz prostřednictvím await connection.query vypisující všechny tabulky v databázi (vytvořené uživatelem i systémem) jako příklad dotazu.
  3. Vrátí odpověď klientovi ve formátu JSON. Hyperdrive po skončení požadavku automaticky ukončí připojení klienta a podkladové připojení k databázi ponechá otevřené ve svém fondu pro další použití.

Spuštění ve vývojovém režimu (volitelné)

Svůj Worker můžete otestovat lokálně ještě před nasazením spuštěním wrangler dev. Tím se kód vašeho Workeru spustí na vašem počítači a zároveň se připojí k vaší databázi.

localConnectionString pole funguje jak s lokálními, tak se vzdálenými databázemi a umožňuje vám připojit se přímo k databázi z projektu Worker spuštěného lokálně. Pokud je to vyžadováno, musíte zadat režim SSL/TLS (sslmode=require pro Postgres, sslMode=REQUIRED pro MySQL).

Pro připojení k databázi během lokálního vývoje nakonfigurujte localConnectionString ve vašem wrangler.jsonc:

{
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "your-hyperdrive-id",
			"localConnectionString": "postgres://user:password@your-database-host:5432/database",
		},
	],
}

Nebo nastavte proměnnou prostředí:

export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:password@your-database-host:5432/database"

Poté spusťte lokální vývoj:

npx wrangler dev

6. Nasaďte svůj Worker

Nyní můžete nasadit svůj Worker a zpřístupnit tak svůj projekt na internetu. Worker nasadíte spuštěním:

npx wrangler deploy
# Outputs: https://hyperdrive-tutorial.<YOUR_SUBDOMAIN>.workers.dev

Nyní můžete navštívit URL adresu nově vytvořeného projektu a spustit dotaz do vaší ostré databáze.

Pokud je například URL vašeho nového Workeru hyperdrive-tutorial.<YOUR_SUBDOMAIN>.workers.dev, přístupem k https://hyperdrive-tutorial.<YOUR_SUBDOMAIN>.workers.dev/ odešle požadavek na váš Worker, který dotazuje přímo vaši databázi.

Dokončením tohoto tutoriálu jste vytvořili konfiguraci Hyperdrive i Worker pro přístup k dané databázi a svůj projekt jste nasadili globálně.

Další kroky

Pokud máte požadavky na nové funkce nebo jste narazili na chyby, sdílejte zpětnou vazbu přímo s týmem Cloudflare, a to prostřednictvím Komunita vývojářů Cloudflare na Discordu ↗.