📘 תיעוד 204

התחברות למסד הנתונים Turso שלכם ושאילתות אליו באמצעות Workers

המדריך הזה מנחה אתכם איך לבנות יישומים מבוזרים גלובלית עם Cloudflare Workers ועם Turso ↗︎, מסד נתונים מבוזר שמתארח בקצה ומבוסס על libSQL. באמצעות Workers ו-Turso אפשר ליצור יישומים שקרובים למשתמשי הקצה, בלי לתחזק או להפעיל תשתית בעשרות או במאות אזורים.

הערה

לחוויה חלקה יותר, פנו אל מדריך השילוב של מסד הנתונים Turso. שילוב מסד הנתונים Turso מנחה אתכם בחיבור ה-Worker למסד נתונים של Turso, באמצעות הגדרה מאובטחת של פרטי הגישה למסד הנתונים כ-secrets ב-Worker.

#דרישות מוקדמות

לפני שממשיכים במדריך הזה, צריך:

• יצרתם בהצלחה את ה-Worker הראשון שלכם ב-Cloudflare ו/או פרסתם בעבר Cloudflare Worker.
• התקנתם את Wrangler, כלי שורת פקודה לבניית Cloudflare Workers.
• יש לכם חשבון GitHub ↗︎, שנדרש לאימות מול Turso.
• היכרות בסיסית עם התקנה ושימוש ביישומי ממשק שורת פקודה (CLI).

#התקנת Turso CLI

צריך את Turso CLI כדי ליצור מסד נתונים ולמלא אותו. הריצו בטרמינל אחת משתי הפקודות הבאות כדי להתקין את Turso CLI:

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

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

אחרי התקנת Turso CLI, ודאו שה-CLI נמצא בנתיב של המעטפת:

turso --version

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

#יצירת מסד נתונים ומילוי שלו

לפני יצירת מסד הנתונים הראשון ב-Turso, צריך להתחבר ל-CLI באמצעות חשבון GitHub, על ידי הרצה של:

turso auth login

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

turso auth login יפתח חלון דפדפן ויבקש מכם להיכנס לחשבון GitHub, אם עדיין לא התחברתם. בפעם הראשונה תצטרכו לתת ליישום Turso הרשאה להשתמש בחשבון. בחרו ב-Approve כדי להעניק ל-Turso את ההרשאות הנדרשות.

אחרי האימות אפשר ליצור מסד נתונים באמצעות הרצה של turso db create <DATABASE_NAME>. Turso יבחר אוטומטית מיקום קרוב אליכם.

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.

אחרי שנוצר מסד הנתונים הראשון, אפשר להתחבר אליו ישירות ולהריץ מולו SQL:

turso db shell my-db

כדי להתחיל עם מסד הנתונים, צרו והגדירו סכמה לטבלה הראשונה. בדוגמה הזו תיצרו טבלת example_users עם עמודה אחת: email (מסוג text), ואז תמלאו אותה בכתובת דוא"ל אחת.

במעטפת שזה עתה נפתחה, הדביקו את ה-SQL הבא:

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

אם פקודות ה-SQL הצליחו, לא יופיע פלט. שימו לב שנקודה-פסיק (;) בסוף כל פקודה נחוצה כדי לסיים כל פקודת SQL.

הקלידו .quit כדי לצאת מהמעטפת.

#שימוש ב-Wrangler ליצירת פרויקט Workers

ממשק שורת הפקודה של Workers, Wrangler, מאפשר ליצור פרויקטי Workers, לפתח אותם מקומית ולפרוס אותם.

כדי ליצור פרויקט Workers חדש (בשם worker-turso-ts), הריצו את הפקודה המתאימה:

npm:

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

yarn:

yarn create cloudflare worker-turso-ts

pnpm:

pnpm create cloudflare@latest worker-turso-ts

בהתקנה, בחרו באפשרויות הבאות:

• עבור What would you like to start with?, בחרו ב-Hello World example.
• עבור Which template would you like to use?, בחרו ב-Worker only.
• עבור Which language do you want to use?, בחרו ב-TypeScript.
• עבור Do you want to use git for version control?, בחרו ב-Yes.
• עבור Do you want to add an AGENTS.md file to help AI coding tools understand Cloudflare APIs?, בחרו ב-Yes.
• עבור Do you want to deploy your application?, בחרו ב-No (נבצע כמה שינויים לפני הפריסה).

כדי להתחיל לפתח את ה-Worker, בצעו cd אל ספריית הפרויקט החדשה:

cd worker-turso-ts

בספריית הפרויקט יש עכשיו את הקבצים הבאים:

• wrangler.json / wrangler.toml: קובץ התצורה של Wrangler
• src/index.ts: Worker מינימלי מסוג Hello World שנכתב ב-TypeScript
• package.json: קובץ תצורה מינימלי של תלויות Node.
• tsconfig.json: תצורת TypeScript שכוללת את הטיפוסים של Workers. נוצר רק אם צוין.

במדריך הזה רלוונטיים רק קובץ התצורה של Wrangler והקובץ src/index.ts. אין צורך לערוך את שאר הקבצים, ויש להשאיר אותם כמו שהם.

#הגדרת ה-Worker עבור מסד הנתונים Turso

ספריית הלקוח של Turso זקוקה לשני פרטי מידע כדי ליצור חיבור:

1. LIBSQL_DB_URL: מחרוזת החיבור למסד הנתונים Turso.
2. LIBSQL_DB_AUTH_TOKEN: אסימון האימות למסד הנתונים Turso. יש לשמור אותו כסוד, ולא להכניס אותו לקוד המקור.

כדי לקבל את כתובת ה-URL של מסד הנתונים, הריצו את פקודת Turso CLI הבאה והעתיקו את התוצאה:

turso db show my-db --url

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

פתחו את קובץ התצורה של Wrangler בעורך, ובתחתית הקובץ צרו מקטע [vars] חדש שמייצג את משתני הסביבה של הפרויקט:

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

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

שמרו את השינויים ב-קובץ התצורה של Wrangler.

בשלב הבא, צרו אסימון אימות ארוך טווח שה-Worker ישתמש בו בחיבור למסד הנתונים. הריצו את פקודת Turso CLI הבאה, והעתיקו את הפלט ללוח:

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

כדי לשמור את האסימון כסוד:

1. תיצרו קובץ .dev.vars לפיתוח מקומי. אל תכניסו את הקובץ הזה לבקרת המקור. יש להוסיף את .dev.vars לקובץ .gitignore אם אתם משתמשים ב-Git.

• תיצרו גם secret כדי לשמור את אסימון האימות חסוי.

קודם צרו קובץ חדש בשם .dev.vars עם המבנה הבא. הדביקו את אסימון האימות בין המרכאות:

LIBSQL_DB_AUTH_TOKEN="<YOUR_AUTH_TOKEN>"

שמרו את השינויים ב-.dev.vars. אחר כך שמרו את אסימון האימות כ-secret שה-Worker בסביבת הייצור יוכל להתייחס אליו. הריצו את פקודת wrangler secret הבאה כדי ליצור Secret עם האסימון:

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

בחרו <Enter> במקלדת כדי לשמור את האסימון כ-secret. גם LIBSQL_DB_URL וגם LIBSQL_DB_AUTH_TOKEN יהיו זמינים בסביבה של ה-Worker בזמן ריצה.

#התקנת ספריות נוספות

התקינו את ספריית הלקוח של Turso ונתב:

npm:

npm i @libsql/client itty-router

yarn:

yarn add @libsql/client itty-router

pnpm:

pnpm add @libsql/client itty-router

bun:

bun add @libsql/client itty-router

הספרייה @libsql/client מאפשרת לשלוח שאילתות למסד נתונים של Turso. הספרייה itty-router היא נתב קל משקל שתשתמשו בו כדי לטפל בבקשות נכנסות אל ה-worker.

#כתיבת ה-Worker

עכשיו תכתבו Worker שיבצע את הפעולות הבאות:

1. טיפול בבקשת HTTP.
2. ניתוב שלה אל מטפל מסוים, כדי להציג את כל המשתמשים במסד הנתונים שלנו או להוסיף משתמש חדש.
3. החזרת התוצאות ו/או הצלחה.

פתחו את src/index.ts ומחקו את התבנית הקיימת. העתיקו את הקוד שלמטה בדיוק כמו שהוא והדביקו אותו בקובץ:

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

שמרו את הקובץ src/index.ts עם השינויים.

הערה:

• ייבוא ספריית הלקוח של libSQL, בדיוק @libsql/client/web, חייב להיות כמו שמוצג כשעובדים עם Cloudflare workers. הייבוא שאינו web לא יעבוד בסביבת Workers.
• ממשק Env מכיל את משתנה הסביבה ואת ה-secret שהגדרתם קודם.
• ממשק Env גם שומר במטמון את אובייקט הלקוח של libSQL ואת הנתב, שנוצרים בבקשה הראשונה אל ה-Worker.
• הנתיב /users שולף את כל השורות מטבלת example_users שיצרתם במעטפת של Turso. הוא פשוט מסדר את אובייקט ResultSet כ-JSON ישירות אל הקורא.
• הנתיב /add-user מוסיף שורה חדשה באמצעות ערך שסופק במחרוזת השאילתה.

אחרי שהסביבה מוגדרת והקוד מוכן, תבדקו עכשיו את ה-Worker מקומית לפני הפריסה.

#הרצת ה-Worker מקומית עם Wrangler

כדי להריץ מופע מקומי של ה-Worker (כולו על המחשב שלכם), הריצו את הפקודה הבאה:

npx wrangler dev

אמור להופיע פלט דומה לזה:

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!

כתובת ה-localhost, זו שיש בה 127.0.0.1, היא שרת אינטרנט שרץ מקומית על המחשב שלכם.

התחברו אליה וודאו שה-Worker מחזיר את כתובת הדוא"ל שהוספתם כשיצרתם את טבלת example_users, באמצעות ביקור בנתיב /users בדפדפן: http://127.0.0.1:8787/users ↗︎.

אמור להופיע JSON דומה לזה, שמכיל את הנתונים מטבלת example_users:

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

זהירות

אם מופיעה שגיאה במקום רשימת משתמשים, בדקו שוב ש:

• הזנתם את הערך הנכון של LIBSQL_DB_URL ב-קובץ התצורה של Wrangler.
• הגדרתם secret בשם LIBSQL_DB_AUTH_TOKEN עם אסימון האימות של מסד הנתונים.

שני אלה צריכים להיות קיימים ולהתאים לשמות המשתנים בקוד של ה-Worker.

בדקו את הנתיב /add-users והעבירו לו כתובת דוא"ל להוספה: http://127.0.0.1:8787/[email protected] ↗︎.

אמור להופיע הטקסט Added. אם תטענו שוב את כתובת ה-URL הראשונה עם הנתיב /users (http://127.0.0.1:8787/users ↗︎), תוצג השורה שנוספה. אפשר לחזור על זה כמה פעמים שרוצים. שימו לב: בגלל העיצוב שלו, היישום לא ימנע מכם להוסיף כתובות דוא"ל כפולות.

צאו מ-Wrangler באמצעות הקלדת q במעטפת שבה הוא הופעל.

#פריסה אל Cloudflare

אחרי שווידאתם שה-Worker יכול להתחבר למסד הנתונים Turso, פרסו את ה-Worker. הריצו את פקודת Wrangler הבאה כדי לפרוס את ה-Worker אל הרשת הגלובלית של Cloudflare:

npx wrangler deploy

בפעם הראשונה שמריצים את הפקודה הזו, היא תפתח דפדפן, תבקש מכם להיכנס עם חשבון Cloudflare, ותעניק הרשאות ל-Wrangler.

פקודת deploy תפיק את הפלט הבא:

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

פרסתם עכשיו Worker שיכול להתחבר למסד הנתונים Turso, לשלוח אליו שאילתות ולהוסיף נתונים חדשים.

#אופציונלי: ניקוי

כדי לנקות את המשאבים שיצרתם כחלק מהמדריך הזה:

• אם אינכם רוצים להשאיר את ה-Worker הזה, הריצו npx wrangler delete worker-turso-ts כדי למחוק את ה-Worker שנפרס.
• אפשר גם למחוק את מסד הנתונים Turso באמצעות turso db destroy my-db.

#משאבים קשורים

• את קוד המקור המלא של הפרויקט אפשר למצוא ב-GitHub ↗︎.
• הסבר איך לנפות באגים ב-Cloudflare Worker.
• הצטרפות אל Cloudflare Developer Discord ↗︎.
• הצטרפות אל ChiselStrike (Turso) Discord ↗︎.