← Cloudflare Workers / workers / tutorials

Připojte se ke své databázi Turso a dotazujte se na ni pomocí Workers

Tento návod vás provede tím, jak vytvářet globálně distribuované aplikace pomocí Cloudflare Workers a Turso ↗, distribuovanou databázi hostovanou na edgi založenou na libSQL. Díky použití Workers a Turso můžete vytvářet aplikace, které jsou blízko vašim koncovým uživatelům, aniž byste museli spravovat nebo provozovat infrastrukturu v desítkách či stovkách regionů.

Předpoklady

Než budete pokračovat v tomto tutoriálu, měli byste mít:

Úspěšně vytvořili jste svůj první Cloudflare Worker a/nebo jste již někdy nasadili Cloudflare Worker.
Nainstalováno Wrangler, nástroj příkazové řádky pro vytváření Cloudflare Workers.
A Účet GitHub ↗, vyžadované pro ověření vůči Turso.
Základní znalost instalace a používání aplikací s rozhraním příkazové řádky (CLI).

Nainstalujte Turso CLI

Pro vytvoření a naplnění databáze budete potřebovat Turso CLI. Pro instalaci Turso CLI spusťte v terminálu jeden z následujících dvou příkazů:

# On macOS or Linux with Homebrew
brew install chiselstrike/tap/turso

# Manual scripted installation
curl -sSfL <https://get.tur.so/install.sh> | bash

Jakmile nainstalujete Turso CLI, ověřte, že je v cestě vašeho shellu:

turso --version

# This should output your current Turso CLI version (your installed version may be higher):
turso version v0.51.0

Vytvoření a naplnění databáze

Než vytvoříte svou první databázi Turso, musíte se přihlásit do CLI pomocí svého účtu GitHub spuštěním:

turso auth login


Waiting for authentication...
✔  Success! Logged in as <your GitHub username>

turso auth login otevře okno prohlížeče a vyzve vás k přihlášení do účtu GitHub, pokud ještě nejste přihlášeni. Při prvním spuštění budete muset aplikaci Turso udělit oprávnění k použití vašeho účtu. Vyberte Schválit abyste Turso udělili potřebná oprávnění.

Po přihlášení můžete vytvořit databázi spuštěním turso db create <DATABASE_NAME>. Turso automaticky zvolí lokalitu, která je vám nejblíže.

turso db create my-db

# Example:
[===>                ]
Creating database my-db in Los Angeles, California (US) (lax)
# Once succeeded:
Created database my-db in Los Angeles, California (US) (lax) in 34 seconds.

Jakmile máte vytvořenou první databázi, můžete se k ní přímo připojit a spouštět proti ní SQL:

turso db shell my-db

Pro začátek práce s databází vytvořte a definujte schéma pro první tabulku. V tomto příkladu vytvoříte example_users tabulku s jedním sloupcem: email (typu text) a poté ho naplňte jednou e-mailovou adresou.

Do právě otevřeného shellu vložte následující SQL:

create table example_users (email text);
insert into example_users values ('[email protected]');

Pokud se SQL příkazy provedly úspěšně, nezobrazí se žádný výstup. Všimněte si, že koncové středníky (;) jsou nutné k ukončení každého příkazu SQL.

Typ .quit abyste ukončili shell.

Použijte Wrangler k vytvoření projektu Workers

Rozhraní příkazové řádky Workers, Wrangler, umožňuje vytvářet, lokálně vyvíjet a nasazovat vaše projekty Workers.

Chcete-li vytvořit nový projekt Workers (s názvem worker-turso-ts), spusťte následující:

npm create cloudflare@latest -- worker-turso-ts

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

Chcete-li začít vyvíjet svůj Worker, cd do adresáře nového projektu:

cd worker-turso-ts

Ve složce projektu nyní máte následující soubory:

wrangler.json / wrangler.toml: Konfigurační soubor Wrangler
src/index.ts: Minimální Worker Hello World napsaný v TypeScriptu
package.json: Minimální konfigurační soubor závislostí Node.
tsconfig.json: Konfigurace TypeScriptu, která zahrnuje typy Workers. Generuje se pouze v případě, že je to zadáno.

Pro tento tutoriál pouze Konfigurační soubor Wrangler a src/index.ts soubor jsou relevantní. Ostatní soubory upravovat nemusíte, ponechte je beze změny.

Nakonfigurujte svůj Worker pro databázi Turso

Klientská knihovna Turso vyžaduje pro navázání připojení dva údaje:

LIBSQL_DB_URL - Připojovací řetězec pro vaši databázi Turso.
LIBSQL_DB_AUTH_TOKEN - Autentizační token pro vaši databázi Turso. Měl by zůstat tajný a neměl by být zahrnut do zdrojového kódu.

Chcete-li získat URL adresu své databáze, spusťte následující příkaz Turso CLI a zkopírujte výsledek:

turso db show my-db --url

libsql://my-db-<your-github-username>.turso.io

Otevřete Konfigurační soubor Wrangler ve vašem editoru a na konci souboru vytvořte nový [vars] sekci představující proměnné prostředí pro váš projekt:

{
	"vars": {
		"LIBSQL_DB_URL": "paste-your-url-here"
	}
}

[vars]
LIBSQL_DB_URL = "paste-your-url-here"

Uložte změny do Konfigurační soubor Wrangler.

Dále vytvořte dlouhodobě platný autentizační token, který bude váš Worker používat při připojování k databázi. Spusťte následující příkaz Turso CLI a výstup zkopírujte do schránky:

turso db tokens create my-db -e none
# Will output a long text string (an encoded JSON Web Token)

Chcete-li tento token udržet v tajnosti:

Vytvoříte .dev.vars soubor pro lokální vývoj. Tento soubor nedávejte do verzovacího systému. Měli byste přidat .dev.vars to your .gitignore` soubor, pokud používáte Git.

Také vytvoříte secret abyste udrželi svůj autentizační token v tajnosti.

Nejprve vytvořte nový soubor s názvem .dev.vars následující strukturou. Vložte svůj autentizační token do uvozovek:

LIBSQL_DB_AUTH_TOKEN="<YOUR_AUTH_TOKEN>"

Uložte své změny do .dev.vars. Dále uložte autentizační token jako secret, na který bude odkazovat váš produkční Worker. Spusťte následující wrangler secret příkaz pro vytvoření Secret s vaším tokenem:

# Ensure you specify the secret name exactly: your Worker will need to reference it later.
npx wrangler secret put LIBSQL_DB_AUTH_TOKEN

? Enter a secret value: › <paste your token here>

Vyberte <Enter> na klávesnici a uložte token jako secret. Obě LIBSQL_DB_URL a LIBSQL_DB_AUTH_TOKEN bude za běhu dostupný v prostředí vašeho Workeru.

Nainstalujte další knihovny

Nainstalujte klientskou knihovnu Turso a router:

npm i @libsql/client itty-router

@libsql/client knihovna vám umožňuje dotazovat se na databázi Turso. itty-router knihovna je odlehčený router, který použijete k obsluze příchozích požadavků na worker.

Napište svůj Worker

Nyní napíšete Worker, který:

Zpracování HTTP požadavku.
Přesměrujte ho na konkrétní handler, který buď vypíše všechny uživatele v naší databázi, nebo přidá nového uživatele.
Vrátí výsledky a/nebo úspěch.

Otevřete src/index.ts a odstraňte existující šablonu. Zkopírujte níže uvedený kód přesně tak, jak je, a vložte ho do souboru:

import { Client as LibsqlClient, createClient } from "@libsql/client/web";
import { Router, RouterType } from "itty-router";

export interface Env {
	// The environment variable containing your the URL for your Turso database.
	LIBSQL_DB_URL?: string;
	// The Secret that contains the authentication token for your Turso database.
	LIBSQL_DB_AUTH_TOKEN?: string;

	// These objects are created before first use, then stashed here
	// for future use
	router?: RouterType;
}

export default {
	async fetch(request, env): Promise<Response> {
		if (env.router === undefined) {
			env.router = buildRouter(env);
		}

		return env.router.fetch(request);
	},
} satisfies ExportedHandler<Env>;

function buildLibsqlClient(env: Env): LibsqlClient {
	const url = env.LIBSQL_DB_URL?.trim();
	if (url === undefined) {
		throw new Error("LIBSQL_DB_URL env var is not defined");
	}

	const authToken = env.LIBSQL_DB_AUTH_TOKEN?.trim();
	if (authToken === undefined) {
		throw new Error("LIBSQL_DB_AUTH_TOKEN env var is not defined");
	}

	return createClient({ url, authToken });
}

function buildRouter(env: Env): RouterType {
	const router = Router();

	router.get("/users", async () => {
		const client = buildLibsqlClient(env);
		const rs = await client.execute("select * from example_users");
		return Response.json(rs);
	});

	router.get("/add-user", async (request) => {
		const client = buildLibsqlClient(env);
		const email = request.query.email;
		if (email === undefined) {
			return new Response("Missing email", { status: 400 });
		}
		if (typeof email !== "string") {
			return new Response("email must be a single string", { status: 400 });
		}
		if (email.length === 0) {
			return new Response("email length must be > 0", { status: 400 });
		}

		try {
			await client.execute({
				sql: "insert into example_users values (?)",
				args: [email],
			});
		} catch (e) {
			console.error(e);
			return new Response("database insert failed");
		}

		return new Response("Added");
	});

	router.all("*", () => new Response("Not Found.", { status: 404 }));

	return router;
}

Uložte si src/index.ts soubor svými změnami.

Poznámka:

Import klientské knihovny libSQL '@libsql/client/web' musí být při práci s Cloudflare Workers proveden přesně tak, jak je uvedeno. Import bez přípony web nebude v prostředí Workers fungovat.
Env rozhraní obsahuje proměnnou prostředí a secret, které jste dříve definovali.
Env rozhraní také ukládá do mezipaměti objekt klienta libSQL a router, které se vytvoří při prvním požadavku na Worker.
/users trasa načte všechny řádky z example_users tabulku, kterou jste vytvořili v Turso shellu. Jednoduše serializuje ResultSet objekt přímo volajícímu jako JSON.
/add-user trasa vloží nový řádek pomocí hodnoty zadané v řetězci dotazu.

Jakmile máte nastavené prostředí a připravený kód, otestujete teď Worker lokálně před nasazením.

Spusťte Worker lokálně pomocí Wrangler

Chcete-li spustit lokální instanci svého Workeru (zcela na vlastním počítači), spusťte následující příkaz:

npx wrangler dev

Měl by se vám zobrazit výstup podobný tomuto:

Your worker has access to the following bindings:
- Vars:
  - LIBSQL_DB_URL: "your-url"
⎔ Starting a local server...
╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ [b] open a browser, [d] open Devtools, [l] turn off local mode, [c] clear console, [x] to exit                                                                  	│
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Debugger listening on ws://127.0.0.1:61918/1064babd-bc9d-4bed-b171-b35dab3b7680
For help, see: https://nodejs.org/en/docs/inspector
Debugger attached.
[mf:inf] Worker reloaded! (40.25KiB)
[mf:inf] Listening on 0.0.0.0:8787
[mf:inf] - http://127.0.0.1:8787
[mf:inf] - http://192.168.1.136:8787
[mf:inf] Updated `Request.cf` object cache!

Adresa localhost, tedy ta s 127.0.0.1 v něm, je webový server běžící lokálně na vašem počítači.

Připojte se k němu a ověřte, že váš Worker vrací e-mailovou adresu, kterou jste zadali při vytváření example_users tabulku tak, že navštívíte /users trasu ve svém prohlížeči: http://127.0.0.1:8787/users ↗.

Měli byste vidět JSON podobný tomuto, obsahující data z example_users tabulku:

{
	"columns": ["email"],
	"rows": [{ "email": "[email protected]" }],
	"rowsAffected": 0
}

Otestujte /add-users trasu a předejte jí e-mailovou adresu, kterou chcete vložit: http://127.0.0.1:8787/[email protected] ↗

Měli byste vidět text “Added”. Pokud načtete první URL adresu pomocí /users trasu znovu (http://127.0.0.1:8787/users ↗), zobrazí se nově přidaný řádek. Tento postup můžete opakovat, kolikrát chcete. Vzhledem k návrhu aplikace vám nic nezabrání přidat duplicitní e-mailové adresy.

Wrangler ukončíte zadáním q do shellu, ve kterém byl spuštěn.

Deploy to Cloudflare

Jakmile ověříte, že se Worker dokáže připojit k databázi Turso, Worker nasaďte. Následujícím příkazem Wrangler nasadíte Worker do globální sítě Cloudflare:

npx wrangler deploy

Při prvním spuštění tohoto příkazu se otevře prohlížeč, budete vyzváni k přihlášení ke svému účtu Cloudflare a k udělení oprávnění Wrangleru.

deploy příkaz vypíše následující:

Your worker has access to the following bindings:
- Vars:
  - LIBSQL_DB_URL: "your-url"
...
Published worker-turso-ts (0.19 sec)
  https://worker-turso-ts.<your-Workers-subdomain>.workers.dev
Current Deployment ID: f9e6b48f-5aac-40bd-8f44-8a40be2212ff

Nyní máte nasazený Worker, který se dokáže připojit k vaší databázi Turso, dotazovat se v ní a vkládat do ní nová data.

Volitelné: Úklid

Chcete-li vyčistit prostředky vytvořené v rámci tohoto návodu:

Pokud tento Worker nechcete zachovat, spusťte npx wrangler delete worker-turso-ts pro odstranění nasazeného Workeru.
Databázi Turso můžete také odstranit prostřednictvím turso db destroy my-db.

Najděte kompletní zdrojový kód projektu na GitHubu ↗.
Seznamte se s tím, jak ladění Cloudflare Workeru.
Připojte se k Cloudflare Developer Discord ↗.
Připojte se k ChiselStrike (Turso) Discord ↗.