← Cloudflare Workers / workers / tutorials

Připojte se k databázi PostgreSQL pomocí Cloudflare Workers

V tomto tutoriálu se naučíte vytvořit aplikaci Cloudflare Workers a připojit ji k databázi PostgreSQL pomocí TCP sockety a Hyperdrive. Aplikace Workers, kterou v tomto návodu vytvoříte, bude pracovat s databází produktů v PostgreSQL.

Chcete-li pokračovat:

1. Zaregistrujte si účet Cloudflare ↗ pokud jste to ještě neudělali.
2. Nainstalujte npm ↗.
3. Nainstalujte Node.js ↗. Použijte správce verzí Node, například Volta ↗ nebo nvm ↗ 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ší.
4. Ujistěte se, že máte přístup k databázi PostgreSQL.

Nejprve použijte create-cloudflare CLI ↗ pro vytvoření nové aplikace Worker. Otevřete okno terminálu a spusťte následující příkaz:

npm create cloudflare@latest -- postgres-tutorial

Tímto budete vyzváni k instalaci create-cloudflare ↗ balíček a provede vás průvodcem nastavením.

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

• Pro S čím byste chtěli začít?, vyberte Hello World example.
• Pro Jakou šablonu chcete použít?, vyberte Worker only.
• Pro Jaký jazyk chcete použít?, vyberte TypeScript.
• Pro Chcete používat git pro správu verzí?, vyberte Yes.
• Pro Chcete nasadit svou aplikaci?, vyberte No (před nasazením provedeme ještě několik změn).

Pokud se rozhodnete nasadit, budete vyzváni k ověření (pokud ještě nejste přihlášeni) a projekt se nasadí. Po nasazení můžete kód Workeru dále upravovat a na konci tohoto návodu jej nasadit znovu.

Nyní přejděte do nově vytvořeného adresáře:

cd postgres-tutorial

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.

Chcete-li se připojit k databázi PostgreSQL, budete potřebovat pg knihovna. V adresáři aplikace Worker spusťte pro instalaci knihovny následující příkaz:

npm i pg

Dále nainstalujte typy TypeScript pro pg knihovnu, čímž ve svém kódu TypeScript zapnete kontrolu typů a automatické doplňování:

npm i -D @types/pg

Zvolte jeden ze dvou způsobů připojení k databázi PostgreSQL:

1. Použijte připojovací řetězec.
2. Nastavit explicitní parametry.

Connection string obsahuje všechny informace potřebné k připojení k databázi. Jde o URL, které obsahuje následující informace:

postgresql://username:password@host:port/database

Nahraďte username, password, host, port, a database odpovídajícími hodnotami pro vaši databázi PostgreSQL.

Nastavte svůj connection string jako secret aby se neukládal jako prostý text. Použijte wrangler secret put příkladovým názvem proměnné DB_URL:

npx wrangler secret put DB_URL

➜  wrangler secret put DB_URL
-------------------------------------------------------
? Enter a secret value: › ********************
✨ Success! Uploaded secret DB_URL

Nastavte své DB_URL secret lokálně v .dev.vars soubor, jak je popsáno v Lokální vývoj s tajnými klíči.

DB_URL="<ENTER YOUR POSTGRESQL CONNECTION STRING>"

Nakonfigurujte každý parametr databáze jako proměnná prostředí prostřednictvím Cloudflare dashboard nebo ve vašem souboru Wrangler. Podívejte se na příklad konfigurace souboru Wrangler:

{
	"vars": {
		"DB_USERNAME": "postgres",
		// Set your password by creating a secret so it is not stored as plain text
		"DB_HOST": "ep-aged-sound-175961.us-east-2.aws.neon.tech",
		"DB_PORT": 5432,
		"DB_NAME": "productsdb"
	}
}

[vars]
DB_USERNAME = "postgres"
DB_HOST = "ep-aged-sound-175961.us-east-2.aws.neon.tech"
DB_PORT = 5_432
DB_NAME = "productsdb"

Chcete-li nastavit heslo jako secret aby se neukládal jako prostý text, použijte wrangler secret put. DB_PASSWORD je příklad názvu proměnné, pod kterým bude tento secret přístupný ve vašem Workeru:

npx wrangler secret put DB_PASSWORD

-------------------------------------------------------
? Enter a secret value: › ********************
✨ Success! Uploaded secret DB_PASSWORD

Otevřete hlavní soubor svého Workeru (například worker.ts) a importujte Client třída z pg knihovna:

import { Client } from "pg";

V fetch obslužné rutině události se připojte k databázi PostgreSQL zvolenou metodou, buď pomocí řetězce připojení, nebo explicitních parametrů.

// create a new Client instance using the connection string
const sql = new Client({ connectionString: env.DB_URL });
// connect to the PostgreSQL database
await sql.connect();

// create a new Client instance using explicit parameters
const sql = new Client({
	username: env.DB_USERNAME,
	password: env.DB_PASSWORD,
	host: env.DB_HOST,
	port: env.DB_PORT,
	database: env.DB_NAME,
	ssl: true, // Enable SSL for secure connections
});
// connect to the PostgreSQL database
await sql.connect();

Pro ukázku, jak pracovat s databází produktů, načtete data z products tabulky tak, že ji při přijetí požadavku dotážete.

Nahraďte stávající kód ve svém worker.ts soubor následujícím kódem:

import { Client } from "pg";

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Create a new Client instance using the connection string
		// or explicit parameters as shown in the previous steps.
		// Here, we are using the connection string method.
		const sql = new Client({
			connectionString: env.DB_URL,
		});
        // Connect to the PostgreSQL database
        await sql.connect();

        // Query the products table
        const result = await sql.query("SELECT * FROM products");

        // Return the result as JSON
        return new Response(JSON.stringify(result.rows), {
            headers: {
                "Content-Type": "application/json",
            },
        });
	},
} satisfies ExportedHandler<Env>;

Tento kód naváže spojení s databází PostgreSQL uvnitř vaší aplikace Worker a dotazuje se na products tabulky a vrátí výsledky jako odpověď ve formátu JSON.

Následujícím příkazem nasaďte svůj Worker:

npx wrangler deploy

Vaše aplikace je nyní spuštěná a dostupná na adrese <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev.

Po nasazení můžete s databází produktů PostgreSQL pracovat prostřednictvím Cloudflare Worker. Kdykoli přijde požadavek na adresu URL vašeho Workeru, načte data z products tabulky a vrátí ji jako odpověď ve formátu JSON. Dotaz můžete podle potřeby upravit tak, aby z databáze produktů získal požadovaná data.

Chcete-li vložit nový řádek do products tabulky vytvořte ve svém Workeru nový API endpoint, který zpracovává POST požadavek. Když POST požadavek s JSON payloadem, Worker vloží nový řádek do products tabulku poskytnutými daty.

Předpokládejme products tabulka obsahuje následující sloupce: id, name, description, a price.

Přidejte následující úryvek kódu do fetch obslužná rutina události ve vašem worker.ts soubor před stávající kód dotazu:

import { Client } from "pg";

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Create a new Client instance using the connection string
		// or explicit parameters as shown in the previous steps.
		// Here, we are using the connection string method.
		const sql = new Client({
			connectionString: env.DB_URL,
		});
        // Connect to the PostgreSQL database
        await sql.connect();

        const url = new URL(request.url);
        if (request.method === "POST" && url.pathname === "/products") {
            // Parse the request's JSON payload
            const productData = (await request.json()) as {
                name: string;
                description: string;
                price: number;
            };

            const name = productData.name,
                description = productData.description,
                price = productData.price;

            // Insert the new product into the products table
            const insertResult = await sql.query(
                `INSERT INTO products(name, description, price) VALUES($1, $2, $3)
    RETURNING *`,
                [name, description, price],
            );

            // Return the inserted row as JSON
            return new Response(JSON.stringify(insertResult.rows), {
                headers: { "Content-Type": "application/json" },
            });
        }

        // Query the products table
        const result = await sql.query("SELECT * FROM products");

        // Return the result as JSON
        return new Response(JSON.stringify(result.rows), {
            headers: {
                "Content-Type": "application/json",
            },
        });
	},
} satisfies ExportedHandler<Env>;

Tento úryvek kódu provádí následující:

1. Kontroluje, zda se jedná o požadavek typu POST požadavek a cesta URL je /products.
2. Parsuje JSON payload z požadavku.
3. Vytvoří INSERT SQL dotaz s využitím poskytnutých dat o produktu.
4. Spustí dotaz a vloží nový řádek do products tabulka.
5. Vrátí vložený řádek jako odpověď ve formátu JSON.

Nyní, když odešlete POST požadavek na URL adresu vašeho Workeru s /products cestu a JSON payload, Worker vloží nový řádek do products tabulku poskytnutými daty. Když požadavek na / je proveden, Worker vrátí všechny produkty z databáze.

Po provedení těchto změn Worker znovu nasaďte spuštěním:

npx wrangler deploy

Svůj Cloudflare Worker nyní můžete použít k vkládání nových řádků do products tabulky. Chcete-li tuto funkci otestovat, odešlete POST požadavek na URL adresu vašeho Workeru s /products cestu spolu s JSON payloadem obsahujícím data nového produktu:

{
	"name": "Sample Product",
	"description": "This is a sample product",
	"price": 19.99
}

Úspěšně jste vytvořili Cloudflare Worker, který se připojuje k databázi PostgreSQL a stará se o načítání dat i vkládání nových řádků do tabulky products.

Vytvořte konfiguraci Hyperdrive pomocí connection stringu pro vaši databázi PostgreSQL.

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

Tento příkaz vypíše konfiguraci Hyperdrive id která bude použita pro váš Hyperdrive binding. Nastavte binding zadáním id v souboru Wrangler.

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "hyperdrive-example",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"compatibility_flags": [
		"nodejs_compat"
	],
	// Pasted from the output of `wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string=[...]` above.
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<ID OF THE CREATED HYPERDRIVE CONFIGURATION>"
		}
	]
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "hyperdrive-example"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-28"
compatibility_flags = [ "nodejs_compat" ]

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<ID OF THE CREATED HYPERDRIVE CONFIGURATION>"

Vytvořte typy pro svůj Hyperdrive binding pomocí následujícího příkazu:

npx wrangler types

V kódu Workeru nahraďte stávající připojovací řetězec připojovacím řetězcem Hyperdrive.

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

		const url = new URL(request.url);

		//rest of the routes and database queries
	},
} satisfies ExportedHandler<Env>;

Následujícím příkazem nasaďte svůj Worker:

npx wrangler deploy

Vaše aplikace Worker je nyní spuštěná a dostupná na adrese <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev, pomocí služby Hyperdrive. Hyperdrive urychluje dotazy do databáze sdružováním vašich připojení a ukládáním vašich požadavků do mezipaměti po celém světě.

Chcete-li se dozvědět více o tom, co lze vytvářet s databázemi a Workers, přečtěte si Návody a prozkoumejte Dokumentace k databázím.

Pokud máte jakékoli dotazy, potřebujete pomoc nebo se chcete podělit o svůj projekt, připojte se ke komunitě Cloudflare Developer na Discord ↗ pro spojení s ostatními vývojáři a týmem Cloudflare.