← Hyperdrive (Postgres & MySQL) / hyperdrive / concepts

Životní cyklus připojení

Pochopení fungování připojení mezi Workers, Hyperdrive a vaší zdrojovou databází je nezbytné pro vytváření efektivních aplikací s Hyperdrive.

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).

Pokud v Cloudflare Worker používáte databázový klient, životní cyklus připojení funguje jinak než v tradičních serverových prostředích. Následuje popis, co se přitom děje:

Bez Hyperdrive by každé vyvolání Workeru vyžadovalo navázání nového připojení přímo k vaší origin databázi. Tento proces vyžaduje více cest po internetu tam a zpět, než se dokončí TCP handshake, vyjednání TLS a autentizace databáze: to znamená sedminásobný počet cest tam a zpět a další zpoždění ještě předtím, než se váš dotaz vůbec může vykonat.

Hyperdrive to řeší rozdělením navazování připojení na dvě části: rychlé edge připojení a optimalizovanou cestu k vaší databázi.

1. Navázání připojení na edge: Databázový ovladač v kódu vašeho Workeru naváže připojení k instanci Hyperdrive. To probíhá na edge, společně s vaším Workerem, takže vytváření připojení je mimořádně rychlé. Proto používáte speciální připojovací řetězec Hyperdrive.

2. Jedna zpáteční cesta napříč regiony: Jelikož ověření již proběhlo na edge, Hyperdrive potřebuje jen jednu zpáteční cestu mezi regiony k vaší databázi, místo několika zpátečních cest, které by jinak vznikly při navazování připojení.

3. Získání stávajícího připojení z fondu: Hyperdrive použije existující připojení z fondu, které je umístěno blízko vaší databáze, čímž se minimalizuje latence.

4. Pokud nejsou k dispozici žádná připojení, vytvořit nové: V případě potřeby se nová připojení vytvářejí z regionu blízkého vaší databázi, aby se snížila latence při navazování nových připojení.

5. Spustit dotaz: Váš dotaz se provede vůči databázi a výsledky se vrátí vašemu Workeru prostřednictvím Hyperdrive.

6. Ukončení připojení: Když váš Worker dokončí zpracování požadavku, připojení databázového klienta ve vašem Workeru se automaticky uvolní garbage collectorem. Hyperdrive však ponechá připojení ke zdrojové databázi otevřené ve fondu, připravené k opětovnému použití při dalším vyvolání Workeru. To znamená, že následující požadavky sice stále proběhnou přes rychlé navázání edge připojení, ale znovu použijí jedno z existujících připojení z fondu Hyperdrive poblíž vaší databáze.

Jakmile váš Worker dokončí zpracování požadavku, je databázový klient automaticky uvolněn garbage collectorem a edge připojení k Hyperdrive se ukončí. Hyperdrive přitom udržuje podkladové připojení k vaší origin databázi otevřené ve svém poolu pro další opětovné použití.

Nemusíte ne musíte zavolat client.end(), sql.end(), connection.end() (nebo podobnou) k vyčištění databázových klientů. Připojení mezi Workers a Hyperdrive se automaticky ukončí, jakmile skončí požadavek nebo volání, a to i v případě, že Workflow nebo Queue consumer dokončí, nebo když Durable Object přejde do hibernace nebo je při nečinnosti odstraněna.

import { Client } from "pg";

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const client = new Client({
			connectionString: env.HYPERDRIVE.connectionString,
		});
		await client.connect();

		const result = await client.query("SELECT * FROM pg_tables");

		// No need to call client.end() — Hyperdrive automatically cleans
		// up the client connection when the request ends. The underlying
		// pooled connection to your origin database remains open for reuse.
		return Response.json(result.rows);
	},
} satisfies ExportedHandler<Env>;

Nevytvářejte databázové klienty ani fondy připojení v globálním rozsahu. Místo toho vytvořte nového klienta uvnitř každého volání handleru: fond připojení Hyperdrive tím zajišťuje rychlost.

import { Client } from "pg";

// 🔴 Bad: Client created in the global scope persists across requests.
// Workers do not allow I/O across request contexts, so this client
// becomes stale and subsequent queries will throw hard errors.
const globalClient = new Client({
	connectionString: env.HYPERDRIVE.connectionString,
});
await globalClient.connect();

export default {
	async fetch(request, env, ctx) {
		// ✅ Good: Client created inside the handler, scoped to this request.
		// Hyperdrive pools the underlying connection to your origin database,
		// so creating a new client per request is fast and reliable.
		const client = new Client({
			connectionString: env.HYPERDRIVE.connectionString,
		});
		await client.connect();

		const result = await client.query("SELECT * FROM pg_tables");
		return Response.json(result.rows);
	},
};

import { Client } from "pg";

// 🔴 Bad: Client created in the global scope persists across requests.
// Workers do not allow I/O across request contexts, so this client
// becomes stale and subsequent queries will throw hard errors.
const globalClient = new Client({
	connectionString: env.HYPERDRIVE.connectionString,
});
await globalClient.connect();

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// ✅ Good: Client created inside the handler, scoped to this request.
		// Hyperdrive pools the underlying connection to your origin database,
		// so creating a new client per request is fast and reliable.
		const client = new Client({
			connectionString: env.HYPERDRIVE.connectionString,
		});
		await client.connect();

		const result = await client.query("SELECT * FROM pg_tables");
		return Response.json(result.rows);
	},
} satisfies ExportedHandler<Env>;

Na rozdíl od běžných Workers, Durable Objects si mohou uchovávat stav napříč více požadavky. Pokud v Durable Object ponecháte databázového klienta otevřeného, připojení zůstane alokované z poolu připojení Hyperdrive. Dlouho běžící Durable Objects mohou vyčerpat dostupná připojení, pokud mnoho objektů drží připojení otevřená současně.

Hyperdrive funguje v režim transakčního poolingu, kdy je připojení drženo po celou dobu trvání transakce. Dlouho běžící transakce s více dotazy mohou dostupná připojení Hyperdrive vyčerpat rychleji, protože každá transakce drží připojení z fondu, dokud se nedokončí.

Viz Limity a zjistěte, kolik připojení je k dispozici pro vaši konfiguraci Hyperdrive na základě vašeho plánu Workers.

• Jak Hyperdrive funguje
• Sdružování připojení
• Limity
• Durable Objects