> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <span>Beta</span>
            </a>;
  }
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#beta-features" className="betaBadge">
            <span>ميزة Beta</span>
        </a>;
};

<BetaBadge link="https://clickhouse.com/cloud/postgres" galaxyTrack={true} galaxyEvent="docs.managed-postgres.guides-cloudflare-workers-beta" />

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

<h2 id="prerequisites">
  المتطلبات الأساسية
</h2>

* [حساب Cloudflare](https://dash.cloudflare.com/sign-up). تتوفر خدمة Hyperdrive ضمن خطتَي Workers المجانية والمدفوعة.
* [Node.js](https://nodejs.org/) الإصدار 20 أو أحدث. اختُبر هذا الدليل باستخدام Node.js 24.21.0 وWrangler 4.145.0 و`create-cloudflare` 2.73.1 و`pg` 8.23.1 وPostgres 18.
* حساب ClickHouse Cloud.
* [`psql`](https://www.postgresql.org/download/)، لإنشاء قاعدة البيانات والجدول. ويمكنك أيضًا تنفيذ عبارات SQL من خلال [SQL console](/ar/integrations/connectors/sql-clients/sql-console).

<h2 id="create-service">
  إنشاء خدمة ClickHouse Managed Postgres
</h2>

في وحدة تحكم ClickHouse Cloud، انقر على **New service** ثم اختر **Postgres**. سيكون المثيل جاهزًا في غضون دقائق قليلة. للاطلاع على شرح مفصّل للخطوات، راجع [دليل البدء السريع](/ar/products/managed-postgres/quickstart).

<h2 id="connection-details">
  الحصول على بيانات الاتصال
</h2>

انقر على **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` في [الإعدادات](/ar/products/managed-postgres/settings) أو حد اتصالات المصدر في Hyperdrive عند الحاجة.

<Note>
  إذا كنت تستخدم [قائمة الوصول حسب عناوين IP](/ar/products/managed-postgres/security)، فاحرص على السماح بـ [نطاقات عناوين IP الخاصة بـ Cloudflare](https://www.cloudflare.com/ips/)، لأن Hyperdrive يتصل منها.
</Note>

<h2 id="create-database">
  إنشاء قاعدة البيانات
</h2>

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

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

```bash theme={null}
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());"
```

```text theme={null}
CREATE TABLE
```

<h2 id="create-project">
  إنشاء مشروع Worker
</h2>

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

```bash theme={null}
npm create cloudflare@latest -- hyperdrive-notes --type=hello-world --lang=ts --no-deploy
cd hyperdrive-notes
npm install pg
npm install -D @types/pg
```

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

  تخطَّ `npm create cloudflare`. في مشروع Worker الخاص بك، شغّل `npm install pg` و`npm install -D @types/pg`، ثم انتقل إلى [إنشاء تهيئة Hyperdrive](#create-hyperdrive)، التي تُضيف ربط Hyperdrive، وإلى [تهيئة Worker](#configure-worker)، التي تُفعّل `nodejs_compat`.
</Tip>

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

<h2 id="create-hyperdrive">
  إنشاء تهيئة Hyperdrive
</h2>

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

```bash theme={null}
npx wrangler cert upload certificate-authority --ca-cert ca-certificate.pem --name managed-postgres-ca
```

```text theme={null}
Success! Uploaded CA Certificate managed-postgres-ca
ID: <CA_CERTIFICATE_ID>
```

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

```bash theme={null}
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
```

```text theme={null}
✅ 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]]` الذي يطبعه الأمر فيه يدوياً.

<Tip>
  **التخزين المؤقت للاستعلامات**

  يستطيع Hyperdrive تخزين نتائج استعلامات القراءة مؤقتاً، لمدة 60 ثانية افتراضياً. يعطّل هذا الدليل التخزين المؤقت باستخدام `--caching-disabled`، كي تُعيد أي قراءة تلي الكتابة مباشرةً الصفَّ الجديد. وبالنسبة إلى الاستعلامات كثيفة القراءة التي تتحمّل نتائج غير محدّثة قليلاً، يمكنك إنشاء تهيئة ثانية مع تفعيل التخزين المؤقت وربط كلتيهما. راجع [التخزين المؤقت للاستعلامات](https://developers.cloudflare.com/hyperdrive/concepts/query-caching/).
</Tip>

<h2 id="configure-worker">
  تهيئة الـ Worker
</h2>

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

```jsonc title="wrangler.jsonc" theme={null}
{
	"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` معرَّفاً صراحةً:

```bash theme={null}
npx wrangler types
```

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

<h2 id="query">
  الاستعلام عن قاعدة البيانات
</h2>

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

```ts title="src/index.ts" theme={null}
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.

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

<h2 id="local-development">
  التشغيل محليًا
</h2>

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

```bash theme={null}
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
```

```text theme={null}
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`.

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

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

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

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

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

```bash theme={null}
curl http://localhost:3108/notes
```

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

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

<h2 id="deploy">
  النشر
</h2>

انشر العامل:

```bash theme={null}
npx wrangler deploy
```

```text theme={null}
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 الذي نشرته:

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

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

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

```json theme={null}
[{"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"}]
```

<h2 id="verify">
  التحقق في وحدة التحكم
</h2>

افتح **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 |

<h2 id="clean-up">
  التنظيف
</h2>

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

```bash theme={null}
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، ثم أعِد تشغيله.

<h2 id="next-steps">
  الخطوات التالية
</h2>

* [الاتصال](/ar/products/managed-postgres/connection): سلاسل الاتصال، وPgBouncer، وTLS
* [الإعدادات](/ar/products/managed-postgres/settings): معلمات Postgres مثل `max_connections`
* [النسخ المتماثلة للقراءة](/ar/products/managed-postgres/read-replicas): توسيع نطاق حركة مرور القراءة
* [وثائق Hyperdrive](https://developers.cloudflare.com/hyperdrive/): التخزين المؤقت للاستعلامات، وضبط مجمّع الاتصالات، وإمكانية المراقبة