📘 תיעוד 212

התחברות למסד נתונים MySQL עם Cloudflare Workers

במדריך זה תלמדו איך ליצור יישום Cloudflare Workers ולחבר אותו למסד נתונים MySQL באמצעות TCP Sockets ו-Hyperdrive. יישום ה-Workers שתיצרו במדריך זה יקיים אינטראקציה עם מסד נתונים של מוצרים בתוך MySQL.

הערה

אנחנו ממליצים להשתמש ב-Hyperdrive כדי להתחבר למסד הנתונים MySQL שלכם. Hyperdrive מספק ביצועים מיטביים ויוודא קישוריות מאובטחת בין ה-Worker שלכם לבין מסד הנתונים MySQL שלכם.

כשמתחברים ישירות למסד הנתונים MySQL (בלי Hyperdrive), מנהלי ההתקן של MySQL מסתמכים על ממשקי API של Node.js שאינם נתמכים כדי ליצור חיבורים מאובטחים, וזה מונע חיבורים.

#דרישות קדם

כדי להמשיך:

1. הירשמו לחשבון Cloudflare ↗︎ אם עדיין לא נרשמתם.

2. התקינו את npm ↗︎.

3. התקינו את Node.js ↗︎.

   השתמשו ב-Vite+ (vp env) ↗︎ כדי להתקין ולנהל גרסאות של Node.js.

   לגרסאות Node.js נתמכות, עיינו ב-דרישות המערכת של Wrangler.

4. ודאו שיש לכם גישה למסד נתונים MySQL.

#1. יצירת יישום Worker

קודם, השתמשו ב-create-cloudflare CLI ↗︎ כדי ליצור יישום Worker חדש. כדי לעשות זאת, פתחו חלון מסוף והריצו את הפקודה הבאה:

npm:

npm create cloudflare@latest -- mysql-tutorial

yarn:

yarn create cloudflare mysql-tutorial

pnpm:

pnpm create cloudflare@latest mysql-tutorial

זה יבקש מכם להתקין את חבילת create-cloudflare ↗︎ ויוביל אתכם באשף הגדרה.

להגדרה, בחרו באפשרויות הבאות:

• עבור 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 mysql-tutorial

#2. הפעלת תאימות ל-Node.js

תאימות ל-Node.js נדרשת למנהלי התקן של מסדי נתונים, כולל mysql2, וצריך להגדיר אותה לפרויקט Workers שלכם.

עבור תאריכי תאימות של 2026-08-04 או מאוחר יותר, פרויקטי Workers ו-Pages מפעילים כברירת מחדל גם את nodejs_compat וגם את nodejs_compat_v2. ממשקי API מובנים של סביבת הריצה ו-polyfills זמינים בלי הגדרה נוספת. הדגלים האלה אינם בשימוש עבור תאריכי התאימות האלה. פרויקטים קיימים אינם צריכים להסיר אותם כשמעדכנים את תאריך התאימות.

אם תאריך התאימות שלכם מוקדם מ-2026-08-04, הוסיפו את דגל התאימות nodejs_compat לקובץ התצורה של Wrangler כדי להצטרף:

{
	"compatibility_flags": [
		"nodejs_compat"
	]
}

compatibility_flags = [ "nodejs_compat" ]

כדי לכבות את תאימות Node.js לגמרי עבור תאריך תאימות של 2026-08-04 או מאוחר יותר, הסירו את הדגלים החיוביים אם הם קיימים. אחר כך הוסיפו גם את no_nodejs_compat וגם את no_nodejs_compat_v2. לדוגמאות תצורה, עיינו ב-דגל התאימות של Node.js.

#3. יצירת תצורת Hyperdrive

צרו תצורת Hyperdrive באמצעות מחרוזת החיבור של מסד הנתונים MySQL שלכם.

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

הפקודה הזו מפיקה את ה-id של תצורת Hyperdrive שישמש ל-binding של Hyperdrive. הגדירו את ה-binding על ידי ציון ה-id בקובץ Wrangler.

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "hyperdrive-example",
	"main": "src/index.ts",
	"upload_source_maps": true,
	// Set this to today's date
	"compatibility_date": "2026-10-12",
	"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"
upload_source_maps = true
# Set this to today's date
compatibility_date = "2026-10-12"
compatibility_flags = [ "nodejs_compat" ]

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

#4. שאילתה למסד הנתונים מתוך ה-Worker

התקינו את מנהל ההתקן mysql2 ↗︎:

npm:

npm i mysql2@>3.13.0

yarn:

yarn add mysql2@>3.13.0

pnpm:

pnpm add mysql2@>3.13.0

bun:

bun add mysql2@>3.13.0

הערה

נדרשת mysql2 בגרסה v3.13.0 או מאוחרת יותר

הוסיפו את דגלי התאימות הנדרשים של Node.js ואת ה-binding של Hyperdrive לקובץ wrangler.jsonc שלכם:

{
	// required for database drivers to function
	"compatibility_flags": [
		"nodejs_compat"
	],
	// Set this to today's date
	"compatibility_date": "2026-10-12",
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<your-hyperdrive-id-here>"
		}
	]
}

compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-10-12"

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<your-hyperdrive-id-here>"

צרו מופע connection חדש והעבירו את הפרמטרים של Hyperdrive:

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

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,

			// Required to enable mysql2 compatibility for Workers
			disableEval: true,
		});

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

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

הערה

הגרסה המינימלית של mysql2 שנדרשת עבור Hyperdrive היא 3.13.0.

#5. פריסת ה-Worker

הריצו את הפקודה הבאה כדי לפרוס את ה-Worker:

npx wrangler deploy

היישום שלכם פעיל עכשיו ונגיש בכתובת <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev.

#השלבים הבאים

כדי לבנות עוד עם מסדי נתונים ו-Workers, עיינו ב-Tutorials וחקרו את תיעוד Databases.

אם יש לכם שאלות, אתם זקוקים לעזרה, או שתרצו לשתף את הפרויקט שלכם, הצטרפו לקהילת המפתחים של Cloudflare ב-Discord ↗︎ כדי להתחבר למפתחים אחרים ולצוות Cloudflare.