استخدام Cloudflare Workers مع ClickHouse Managed Postgres

الاستعلام عن ClickHouse Managed Postgres من Cloudflare Worker عبر Hyperdrive باستخدام node-postgres، مع اتصال TLS موثَّق، وبيئة تطوير محلية، ونشر التطبيق على workers.dev

تُشغّل Cloudflare Workers شيفرتك على شبكة Cloudflare، في حين يحتفظ Hyperdrive بمجمّع اتصالات من تلك الشبكة إلى قاعدة بياناتك، فلا يضطر كل طلب إلى تحمّل تكلفة مصافحة TCP وTLS جديدة. في هذا الدليل، ستُنشئ تهيئة Hyperdrive تتحقق من شهادة المثيل الخاص بك، ثم تبني Worker بلغة TypeScript يُنشئ الصفوف ويقرؤها باستخدام node-postgres (pg)، وتُشغّله محليًا باستخدام wrangler dev، وأخيرًا تنشره على workers.dev.

​

المتطلبات الأساسية

• حساب Cloudflare. تتوفر خدمة Hyperdrive ضمن خطتَي Workers المجانية والمدفوعة.
• Node.js الإصدار 20 أو أحدث. اختُبر هذا الدليل باستخدام Node.js 24.21.0 وWrangler 4.145.0 وcreate-cloudflare 2.73.1 وpg 8.23.1 وPostgres 18.
• حساب ClickHouse Cloud.
• psql، لإنشاء قاعدة البيانات والجدول. ويمكنك أيضًا تنفيذ عبارات SQL من خلال SQL console.

​

إنشاء خدمة ClickHouse Managed Postgres

في وحدة تحكم ClickHouse Cloud، انقر على New service ثم اختر Postgres. سيكون المثيل جاهزًا في غضون دقائق قليلة. للاطلاع على شرح مفصّل للخطوات، راجع دليل البدء السريع.

​

الحصول على بيانات الاتصال

انقر على Connect في الشريط الجانبي الأيسر لخدمتك. أبقِ الخيار Directly محددًا وفعّل Use SSL. سينتهي عنوان URL عندئذٍ بـ sslmode=verify-full&sslrootcert=<service-name>-ca-certificate.pem. انقر على Download CA certificate لتنزيل شهادة CA الخاصة بالمثيل. ويمكنك أيضًا تنزيلها من Settings → CA Certificate.

يوجّه هذا الدليل Hyperdrive إلى الاتصال المباشر على المنفذ 5432، لا إلى PgBouncer المدمج على المنفذ 6432، وذلك للأسباب التالية:

• Hyperdrive هو في حد ذاته أداة لتجميع الاتصالات تعمل في وضع المعاملات؛ إذ يحتفظ بمجمّع صغير من الاتصالات طويلة الأمد بقاعدة البيانات ويتشاركها بين جميع طلبات Worker، وهي المهمة التي كان PgBouncer سيتولاها في غير هذه الحالة. وتوصي Cloudflare بتزويد Hyperdrive بسلسلة اتصال مباشرة بدلًا من سلسلة اتصال عبر مجمّع.
• يمكن أيضًا توجيه Hyperdrive إلى المنفذ 6432، غير أن ربط أداتَي تجميع تعملان في وضع المعاملات على التوالي يضيف قفزة شبكية وموضعًا ثانيًا لضبط أحجام المجمّعات، دون أن يزيد السعة.
• يفتح Hyperdrive ما يصل إلى نحو 20 اتصالًا لكل تهيئة في خطة Workers Free، ونحو 100 اتصال في الخطة المدفوعة، وهو ما يقع ضمن القيمة الافتراضية لـ max_connections البالغة 500. وإذا كانت لديك عدة تهيئات لـ Hyperdrive أو عملاء آخرون على المثيل نفسه، فاجمع عدد اتصالاتهم، واضبط max_connections في الإعدادات أو حد اتصالات المصدر في Hyperdrive عند الحاجة.

إذا كنت تستخدم قائمة الوصول حسب عناوين IP، فاحرص على السماح بـ نطاقات عناوين IP الخاصة بـ Cloudflare، لأن Hyperdrive يتصل منها.

​

إنشاء قاعدة البيانات

أعد تسمية الشهادة التي نزّلتها إلى ca-certificate.pem، ثم أنشئ قاعدة بيانات وجدولًا باسم notes. استبدل <PASSWORD> والمضيف بالقيم المعروضة في نافذة Connect:

psql "postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/postgres?sslmode=verify-full&sslrootcert=ca-certificate.pem" -c "CREATE DATABASE guide_cloudflare;"

psql "postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/guide_cloudflare?sslmode=verify-full&sslrootcert=ca-certificate.pem" -c "CREATE TABLE notes (id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, content text NOT NULL, created_at timestamptz NOT NULL DEFAULT now());"

CREATE TABLE

​

إنشاء مشروع Worker

أنشئ Worker بلغة TypeScript من القالب “Hello World” باستخدام create-cloudflare، ثم ثبّت pg:

npm create cloudflare@latest -- hyperdrive-notes --type=hello-world --lang=ts --no-deploy
cd hyperdrive-notes
npm install pg
npm install -D @types/pg

هل تُضيف ذلك إلى تطبيق قائم؟

تخطَّ npm create cloudflare. في مشروع Worker الخاص بك، شغّل npm install pg وnpm install -D @types/pg، ثم انتقل إلى إنشاء تهيئة Hyperdrive، التي تُضيف ربط Hyperdrive، وإلى تهيئة Worker، التي تُفعّل nodejs_compat.

انقل ca-certificate.pem إلى دليل مشروعك. وإذا لم يسبق لك استخدام Wrangler، فشغّل npx wrangler login لمنحه صلاحية الوصول إلى حسابك في Cloudflare.

​

إنشاء تهيئة Hyperdrive

يشفّر Hyperdrive الاتصال بقاعدة بياناتك دائمًا، لكنه افتراضيًا لا يتحقق من الشهادة مقابل الـ CA الخاص بالمثيل. وللحصول على سلوك مكافئ لـ sslmode=verify-full، حمّل أولًا شهادة الـ CA إلى حسابك على Cloudflare:

npx wrangler cert upload certificate-authority --ca-cert ca-certificate.pem --name managed-postgres-ca

Success! Uploaded CA Certificate managed-postgres-ca
ID: <CA_CERTIFICATE_ID>

استخدم قيمة ID الواردة في الإخراج لإنشاء تهيئة Hyperdrive. تستخدم سلسلة الاتصال المنفذ 5432 وقاعدة البيانات guide_cloudflare، دون أي معلمات SSL؛ إذ يتولى الخياران --sslmode و--ca-certificate-id تهيئة TLS عوضاً عنها:

npx wrangler hyperdrive create managed-postgres \
  --connection-string="postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/guide_cloudflare" \
  --ca-certificate-id <CA_CERTIFICATE_ID> \
  --sslmode verify-full \
  --caching-disabled \
  --binding HYPERDRIVE \
  --update-config

✅ Created new Hyperdrive PostgreSQL config: <HYPERDRIVE_ID>

يتصل Hyperdrive بقاعدة بياناتك أثناء إنشاء التهيئة. عند استخدام --sslmode verify-full، يتحقق من أن شهادة الخادم موقّعة من قِبل الـ CA الذي رفعته، ومن أنها تطابق اسم المضيف. وإذا فشل أيٌّ من هذين الفحصين، يفشل الأمر ويعرض خطأً مثل cert verification failed - unable to get local issuer certificate، ولا تُنشأ أي تهيئة. تُخزَّن كلمة المرور في تهيئة Hyperdrive ضمن حسابك على Cloudflare، لا في مشروعك.

يضيف الخياران --binding HYPERDRIVE --update-config التهيئة إلى wrangler.jsonc، ليتمكن الـ Worker الخاص بك من الوصول إليها عبر env.HYPERDRIVE. أما إذا كان مشروعك يستخدم wrangler.toml، فلن يعدّل Wrangler الملف؛ وعليك بدلاً من ذلك لصق مقتطف [[hyperdrive]] الذي يطبعه الأمر فيه يدوياً.

التخزين المؤقت للاستعلامات

يستطيع Hyperdrive تخزين نتائج استعلامات القراءة مؤقتاً، لمدة 60 ثانية افتراضياً. يعطّل هذا الدليل التخزين المؤقت باستخدام --caching-disabled، كي تُعيد أي قراءة تلي الكتابة مباشرةً الصفَّ الجديد. وبالنسبة إلى الاستعلامات كثيفة القراءة التي تتحمّل نتائج غير محدّثة قليلاً، يمكنك إنشاء تهيئة ثانية مع تفعيل التخزين المؤقت وربط كلتيهما. راجع التخزين المؤقت للاستعلامات.

​

تهيئة الـ Worker

تحتاج مكتبة pg إلى طبقة التوافق مع Node.js. افتح الملف wrangler.jsonc وأضف العلامة nodejs_compat إلى جانب compatibility_date، ليصبح الجزء المعني من الملف على النحو التالي:

wrangler.jsonc

{
	"name": "hyperdrive-notes",
	"main": "src/index.ts",
	"compatibility_date": "2026-09-26",
	"compatibility_flags": ["nodejs_compat"],
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<HYPERDRIVE_ID>"
		}
	]
}

أما في ملف wrangler.toml، فأضف compatibility_flags = ["nodejs_compat"] أسفل compatibility_date. وإذا كان الملف يحتوي أصلاً على compatibility_flags، فأضف nodejs_compat إلى القائمة.

أعد توليد أنواع TypeScript ليصبح نوع env.HYPERDRIVE معرَّفاً صراحةً:

npx wrangler types

إذا كان مشروعك لا يزال يستخدم الحزمة @cloudflare/workers-types، فسيعرض الأمر wrangler types كيفية الانتقال إلى الأنواع المُولَّدة.

​

الاستعلام عن قاعدة البيانات

استبدل محتوى src/index.ts بـ Worker يُنشئ ملاحظة عند استقبال POST /notes ويستعرض جميع الملاحظات عند استقبال GET /notes. أما إذا كان لديك Worker قائم، فأضف بدلًا من ذلك المعالجة نفسها للمسار /notes إلى معالج fetch الخاص بك:

src/index.ts

import { Client } from "pg";

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const url = new URL(request.url);
		if (url.pathname !== "/notes") {
			return new Response("Not found", { status: 404 });
		}

		// Hyperdrive keeps the connections to Postgres, so a new client per request is cheap.
		const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
		await client.connect();

		try {
			if (request.method === "POST") {
				// Create
				const { content } = await request.json<{ content: string }>();
				const { rows } = await client.query(
					"INSERT INTO notes (content) VALUES ($1) RETURNING id, content, created_at",
					[content],
				);
				return Response.json(rows[0], { status: 201 });
			}

			// Read
			const { rows } = await client.query("SELECT id, content, created_at FROM notes ORDER BY id");
			return Response.json(rows);
		} finally {
			// Close the client after the response is sent.
			ctx.waitUntil(client.end());
		}
	},
} satisfies ExportedHandler<Env>;

يشير env.HYPERDRIVE.connectionString إلى Hyperdrive، لا إلى المثيل الخاص بك. يظل الاتصال بين Worker وHyperdrive داخل شبكة Cloudflare، ولذلك لا يحتاج إلى معلمات SSL. أما اتصال TLS الموثَّق مع Postgres فيتولاه Hyperdrive.

يعمل Hyperdrive في وضع المعاملات (transaction mode)، على غرار PgBouncer، أي أن كل معاملة قد تستخدم اتصالًا مختلفًا مع Postgres. وتعمل جميع الاستعلامات ذات المعلمات والمعاملات والعبارات المُعدّة مسبقًا المُسمّاة من pg دون مشكلات. لا تعتمد على حالة الجلسة، مثل SET على مستوى الجلسة، بين استعلام وآخر، بل استخدم SET LOCAL داخل معاملة.

​

التشغيل محليًا

يشغّل الأمر wrangler dev الـ Worker على جهازك. أما في البيئة المحلية، فلا يستخدم Hyperdrive مجمّع اتصالات، بل يتصل الربط (binding) مباشرةً بقاعدة البيانات المحددة في CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING>. اضبط هذا المتغير على سلسلة الاتصال المباشر مع sslmode=verify-full ومسار شهادة CA، ثم شغّل الـ Worker:

export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/guide_cloudflare?sslmode=verify-full&sslrootcert=ca-certificate.pem"
npx wrangler dev --port 3108

Found a non-empty CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE variable for binding. Hyperdrive will connect to this database during local development.
...
Ready on http://localhost:3108

يتولى Wrangler معالجة TLS للاتصال المحلي. ويُحدَّد مسار sslrootcert نسبةً إلى الدليل الذي تشغّل منه الأمر wrangler dev.

إذا لم تحدد sslmode، فلن يكون الاتصال المحلي مشفّرًا. أما مع sslmode=require، فيكون الاتصال مشفّرًا لكن دون التحقق من الشهادة. لذا استخدم دائمًا sslmode=verify-full مع sslrootcert. وإذا كانت شهادة الجهة المُصدِرة (CA) مفقودة أو غير صحيحة، فستفشل الطلبات مع ظهور الخطأ Connection terminated unexpectedly.

في نافذة طرفية ثانية، أنشئ ملاحظة:

curl -X POST http://localhost:3108/notes -H "Content-Type: application/json" -d '{"content": "Hello from wrangler dev"}'

{"id":"1","content":"Hello from wrangler dev","created_at":"2026-09-30T16:58:16.232Z"}

اعرض الملاحظات:

curl http://localhost:3108/notes

[{"id":"1","content":"Hello from wrangler dev","created_at":"2026-09-30T16:58:16.232Z"}]

تُعيد مكتبة pg الأعمدة من النوع bigint في صورة سلاسل نصية، لذا تكون قيمة id هي "1" وليست 1.

​

النشر

انشر العامل:

npx wrangler deploy

Your Worker has access to the following bindings:
Binding                                   Resource
env.HYPERDRIVE (<HYPERDRIVE_ID>)          Hyperdrive Config

Uploaded hyperdrive-notes (2.35 sec)
Deployed hyperdrive-notes triggers (0.76 sec)
  https://hyperdrive-notes.<your-subdomain>.workers.dev

إذا كان هذا أول Worker تنشئه، فسيطلب منك Wrangler تسجيل نطاق فرعي على workers.dev. أنشئ ملاحظة باستخدام الـ Worker الذي نشرته:

curl -X POST https://hyperdrive-notes.<your-subdomain>.workers.dev/notes -H "Content-Type: application/json" -d '{"content": "Hello from Hyperdrive"}'

{"id":"2","content":"Hello from Hyperdrive","created_at":"2026-09-30T16:58:39.733Z"}

افتح https://hyperdrive-notes.<your-subdomain>.workers.dev/notes في متصفحك لعرض الملاحظتين. ستظهر الاستجابة على النحو التالي:

[{"id":"1","content":"Hello from wrangler dev","created_at":"2026-09-30T16:58:16.232Z"},{"id":"2","content":"Hello from Hyperdrive","created_at":"2026-09-30T16:58:39.733Z"}]

​

التحقق في وحدة التحكم

افتح SQL console من الشريط الجانبي الأيسر لخدمتك، ووسّع guide_cloudflare ثم public، ثم انقر على جدول notes. ستظهر الملاحظتان كلتاهما:

id	content	created_at
1	Hello from wrangler dev	2026-09-30 16:58:16.232466+00
2	Hello from Hyperdrive	2026-09-30 16:58:39.733203+00

​

التنظيف

لإزالة ما أنشأته في حسابك على Cloudflare، احذف الـ Worker وتهيئة Hyperdrive وشهادة CA:

npx wrangler delete
npx wrangler hyperdrive delete <HYPERDRIVE_ID>
npx wrangler cert delete --name managed-postgres-ca

إذا أعاد الأمر wrangler cert delete رسالة الخطأ Certificate cannot be deleted while in use، فانتظر دقيقة بعد حذف تهيئة Hyperdrive، ثم أعِد تشغيله.

​

الخطوات التالية

• الاتصال: سلاسل الاتصال، وPgBouncer، وTLS
• الإعدادات: معلمات Postgres مثل max_connections
• النسخ المتماثلة للقراءة: توسيع نطاق حركة مرور القراءة
• وثائق Hyperdrive: التخزين المؤقت للاستعلامات، وضبط مجمّع الاتصالات، وإمكانية المراقبة