מדריך קלאודפלייר בעברית
לאתר הראשי כל המדריכים קלוד קוד קלוד דסקטופ גרוק CLI גרוק בוט MCP קרסור וואטסאפ OpenClaw n8n בענן n8n בהתקנה עצמית

תיעוד 214

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

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

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

כדי להמשיך:

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

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

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

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

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

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

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

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

npm:

npm create cloudflare@latest -- postgres-tutorial

yarn:

yarn create cloudflare postgres-tutorial

pnpm:

pnpm create cloudflare@latest postgres-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 postgres-tutorial

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

תאימות Node.js נדרשת עבור מנהלי מסדי נתונים, כולל Postgres.js, ויש להגדיר אותה עבור פרויקט ה-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.

#2. הוספת ספריית החיבור ל-PostgreSQL

כדי להתחבר למסד נתונים PostgreSQL, תצטרכו את ספריית pg. בתיקיית יישום ה-Worker, הריצו את הפקודה הבאה כדי להתקין את הספרייה:

npm:

npm i pg

yarn:

yarn add pg

pnpm:

pnpm add pg

bun:

bun add pg

לאחר מכן, התקינו את טיפוסי TypeScript עבור ספריית pg כדי לאפשר בדיקת טיפוסים והשלמה אוטומטית בקוד TypeScript שלכם:

npm:

npm i -D @types/pg

yarn:

yarn add -D @types/pg

pnpm:

pnpm add -D @types/pg

bun:

bun add -d @types/pg

הערה

ודאו שאתם משתמשים ב-pg (node-postgres) בגרסה 8.16.3 או גבוהה יותר.

#3. הגדרת החיבור למסד הנתונים PostgreSQL

בחרו באחת משתי השיטות להתחברות למסד הנתונים PostgreSQL שלכם:

  1. שימוש במחרוזת חיבור.
  2. הגדרת פרמטרים מפורשים.

#Use a connection string

מחרוזת חיבור מכילה את כל המידע הדרוש להתחברות למסד נתונים. זוהי כתובת URL שמכילה את המידע הבא:

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

החליפו את username, password, host, port ו-database בערכים המתאימים למסד הנתונים PostgreSQL שלכם.

הגדירו את מחרוזת החיבור כ-סוד כדי שהיא לא תישמר כטקסט גלוי. השתמשו ב-wrangler secret put עם שם המשתנה לדוגמה DB_URL:

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

הגדירו את הסוד DB_URL באופן מקומי בקובץ .dev.vars כפי שמתועד ב-Local Development with Secrets.

.dev.varstoml

DB_URL="<ENTER YOUR POSTGRESQL CONNECTION STRING>"

#Set explicit parameters

הגדירו כל פרמטר של מסד הנתונים כ-משתנה סביבה דרך לוח הבקרה של Cloudflare או בקובץ Wrangler. עיינו בדוגמה לתצורת קובץ 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"

כדי להגדיר את הסיסמה כ-סוד כך שהיא לא תישמר כטקסט גלוי, השתמשו ב-wrangler secret put. DB_PASSWORD הוא שם משתנה לדוגמה עבור הסוד הזה, כדי שיהיה נגיש ב-Worker שלכם:

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

#4. התחברות למסד הנתונים PostgreSQL בתוך ה-Worker

פתחו את הקובץ הראשי של ה-Worker (לדוגמה, worker.ts) וייבאו את המחלקה Client מספריית pg:

import { Client } from "pg";

במטפל האירוע fetch, התחברו למסד הנתונים PostgreSQL באמצעות השיטה שבחרתם, מחרוזת החיבור או הפרמטרים המפורשים.

#Use a connection string

// 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();

#Set explicit parameters

// 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();

#5. אינטראקציה עם מסד נתוני המוצרים

כדי להדגים איך לקיים אינטראקציה עם מסד נתוני המוצרים, תביאו נתונים מטבלת products על ידי שאילתה לטבלה כאשר מתקבלת בקשה.

הערה

אם אתם עוקבים במופע PostgreSQL משלכם, הגדירו את products באמצעות משפט SQL CREATE TABLE הבא. משפט זה מגדיר את העמודות ואת טיפוסי הנתונים שלהן עבור טבלת products:

CREATE TABLE products (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  description TEXT,
  price DECIMAL(10, 2) NOT NULL
);

החליפו את הקוד הקיים בקובץ worker.ts בקוד הבא:

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

קוד זה יוצר חיבור למסד הנתונים PostgreSQL בתוך יישום ה-Worker שלכם ומבצע שאילתה לטבלת products, ומחזיר את התוצאות כתגובת JSON.

#6. פריסת ה-Worker

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

npx wrangler deploy

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

לאחר הפריסה, תוכלו לקיים אינטראקציה עם מסד נתוני המוצרים PostgreSQL באמצעות ה-Cloudflare Worker שלכם. בכל פעם שנשלחת בקשה לכתובת ה-URL של ה-Worker, הוא יביא נתונים מטבלת products ויחזיר אותם כתגובת JSON. תוכלו לשנות את השאילתה לפי הצורך כדי לאחזר את הנתונים הרצויים ממסד נתוני המוצרים.

#7. הוספת שורה חדשה למסד נתוני המוצרים

כדי להוסיף שורה חדשה לטבלת products, צרו נקודת קצה חדשה של API ב-Worker שמטפלת בבקשת POST. כאשר מתקבלת בקשת POST עם מטען JSON, ה-Worker יוסיף שורה חדשה לטבלת products עם הנתונים שסופקו.

הניחו שלטבלת products יש את העמודות הבאות: id, name, description ו-price.

הוסיפו את קטע הקוד הבא בתוך מטפל האירוע fetch בקובץ worker.ts, לפני קוד השאילתה הקיים:

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

קטע קוד זה עושה את הפעולות הבאות:

  1. בודק אם הבקשה היא בקשת POST ונתיב ה-URL הוא /products.
  2. מפענח את מטען ה-JSON מהבקשה.
  3. בונה שאילתת SQL INSERT באמצעות נתוני המוצר שסופקו.
  4. מריץ את השאילתה, ומוסיף את השורה החדשה לטבלת products.
  5. מחזיר את השורה שהוכנסה כתגובת JSON.

עכשיו, כאשר תשלחו בקשת POST לכתובת ה-URL של ה-Worker עם הנתיב /products ומטען JSON, ה-Worker יוסיף שורה חדשה לטבלת products עם הנתונים שסופקו. כאשר נשלחת בקשה אל /, ה-Worker יחזיר את כל המוצרים במסד הנתונים.

לאחר ביצוע השינויים האלה, פרסו שוב את ה-Worker על ידי הרצה של:

npx wrangler deploy

עכשיו תוכלו להשתמש ב-Cloudflare Worker כדי להוסיף שורות חדשות לטבלת products. כדי לבדוק את הפונקציונליות הזו, שלחו בקשת POST לכתובת ה-URL של ה-Worker עם הנתיב /products, יחד עם מטען JSON שמכיל את נתוני המוצר החדש:

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

יצרתם בהצלחה Cloudflare Worker שמתחבר למסד נתונים PostgreSQL ומטפל באחזור נתונים ובהוספת שורות חדשות לטבלת מוצרים.

#8. שימוש ב-Hyperdrive כדי להאיץ שאילתות

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

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

פקודה זו מפיקה את 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>"

צרו את הטיפוסים עבור binding של Hyperdrive באמצעות הפקודה הבאה:

npx wrangler types

החליפו את מחרוזת החיבור הקיימת בקוד ה-Worker במחרוזת החיבור של 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>;

#9. פריסה מחדש של ה-Worker

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

npx wrangler deploy

יישום ה-Worker שלכם פעיל כעת ונגיש בכתובת <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev, באמצעות Hyperdrive. Hyperdrive מאיץ שאילתות למסד הנתונים על ידי איגום החיבורים ושמירת הבקשות במטמון ברחבי העולם.

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

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

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