استخدام Drizzle ORM مع ClickHouse Managed Postgres

Drizzle ORM هي أداة ربط الكائنات بقواعد البيانات مكتوبة بلغة TypeScript، وتوفّر أداة لبناء الاستعلامات بصيغة قريبة من SQL، في حين أن drizzle-kit هي واجهة سطر الأوامر المصاحبة لها، وتُستخدم لتوليد عمليات الترحيل وتنفيذها. في هذا الدليل، ستُعرّف جدول todos بلغة TypeScript، ثم تنشئه عبر عملية ترحيل باستخدام drizzle-kit، وبعد ذلك تعالج استعلامات الإنشاء والقراءة والتحديث والحذف من خلال خادم HTTP صغير مبني على Node.js. ويعتمد كل اتصال على بروتوكول TLS مع التحقق الكامل من الشهادة.

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

Node.js الإصدار 20 أو أحدث
حساب ClickHouse Cloud
psql لإنشاء قاعدة البيانات. ويمكنك أيضًا تنفيذ عبارة CREATE DATABASE في SQL console.

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

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

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

انقر على Connect في الشريط الجانبي الأيسر لخدمتك. تعرض النافذة المنبثقة اسم المستخدم وكلمة المرور والخادم والمنفذ، وتتضمّن مفتاح تبديل Directly / via PgBouncer. يستخدم هذا الدليل سلسلتي اتصال:

الاتصال المباشر (المنفذ 5432) لأداة drizzle-kit. تنفّذ عمليات الترحيل أوامر DDL، وقد يطول تنفيذها، وقد تعتمد على حالة الجلسة مثل SET lock_timeout، لذا ينبغي أن تتصل بـ Postgres مباشرةً.
PgBouncer (المنفذ 6432) للتطبيق. يعمل PgBouncer المضمَّن في وضع تجميع المعاملات، ويتيح لعدد كبير من مثيلات التطبيق، بما فيها الدوال بلا خادم، أن تتشارك عددًا محدودًا من اتصالات Postgres.

إذا كنت تشغّل خادم Node.js واحدًا يعمل لفترات طويلة، فإن node-postgres يدير مجمّع اتصالات خاصًا به، لذا يمكنك أيضًا توجيه التطبيق إلى الاتصال المباشر. استخدم اتصال PgBouncer عند التوسّع أفقيًا إلى عدد كبير من العمليات أو عند التشغيل على منصات بلا خادم.

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

إعداد المشروع

أنشئ مشروعًا، ثم ثبّت Drizzle ORM ومشغّل node-postgres ‏(pg) وdrizzle-kit:

mkdir drizzle-managed-postgres && cd drizzle-managed-postgres
npm init -y
npm pkg set type=module
npm install drizzle-orm pg dotenv
npm install -D drizzle-kit tsx @types/pg

هل تُضيف ذلك إلى تطبيق قائم؟تخطَّ الأوامر mkdir وnpm init وnpm pkg set type=module. بدلاً من ذلك، شغّل في مشروعك الأمرين npm install drizzle-orm pg dotenv وnpm install -D drizzle-kit tsx @types/pg، ثم انتقل إلى قسم تهيئة الاتصال.

تهيئة الاتصال

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

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

CREATE DATABASE

أضف سلسلتَي الاتصال كلتيهما إلى ملف .env في المجلد الجذر للمشروع، أو إلى ملف .env الموجود لديك مسبقًا. ولا تختلف السلسلتان إلا في رقم المنفذ، وكلتاهما تشيران إلى قاعدة البيانات guide_drizzle:

.env

# Runtime queries go through PgBouncer (port 6432)
DATABASE_URL="postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:6432/guide_drizzle?sslmode=verify-full&sslrootcert=ca-certificate.pem"
# drizzle-kit migrations connect directly to Postgres (port 5432)
DIRECT_DATABASE_URL="postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/guide_drizzle?sslmode=verify-full&sslrootcert=ca-certificate.pem"

تقرأ مكتبة node-postgres القيمتين sslmode=verify-full وsslrootcert من عنوان URL، ثم تحمّل ملف CA وتتحقق من سلسلة الشهادات ومن اسم المضيف معًا، فلا حاجة إلى كتابة أي شيفرة TLS إضافية. يُحدَّد مسار sslrootcert نسبةً إلى الدليل الذي تشغّل الأوامر منه. واحرص على إبقاء الملف .env خارج نظام التحكم في الإصدارات.

إذا كان ملف CA مفقودًا أو غير صحيح، يفشل الاتصال ويظهر الخطأ unable to verify the first certificate. وإذا لم يطابق اسم المضيف الشهادة، يفشل الاتصال ويظهر الخطأ ERR_TLS_CERT_ALTNAME_INVALID. وإذا احتوت كلمة المرور على محارف خاصة مثل @ أو / أو #، فرمّزها بترميز URL.

تعريف المخطط

أنشئ الملف src/db/schema.ts:

src/db/schema.ts

import { boolean, integer, pgTable, text, timestamp } from "drizzle-orm/pg-core";

export const todos = pgTable("todos", {
  id: integer().primaryKey().generatedAlwaysAsIdentity(),
  title: text().notNull(),
  done: boolean().notNull().default(false),
  createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
});

أنشئ الملف drizzle.config.ts في المجلد الجذر للمشروع. يوجّه هذا الملف أداة drizzle-kit إلى المخطط وإلى الاتصال المباشر:

drizzle.config.ts

import "dotenv/config";
import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: "postgresql",
  schema: "./src/db/schema.ts",
  out: "./drizzle",
  dbCredentials: {
    // Migrations use the direct connection (port 5432)
    url: process.env.DIRECT_DATABASE_URL!,
  },
});

تشغيل عمليات الترحيل

أنشئ ترحيل SQL انطلاقًا من المخطط:

npx drizzle-kit generate --name init

1 tables
todos 4 columns 0 indexes 0 fks

[✓] Your SQL migration file ➜ drizzle/0000_init.sql 🚀

يحتوي الملف المُنشأ drizzle/0000_init.sql على عبارة CREATE TABLE. راجِعه، ثم ثبّت (commit) المجلد drizzle مع شيفرتك. بعد ذلك، طبّقه:

npx drizzle-kit migrate

Using 'pg' driver for database querying
[✓] migrations applied successfully!

يسجّل drizzle-kit migrate عمليات الترحيل المُطبَّقة في جدول drizzle.__drizzle_migrations، ولا ينفّذ في الاستدعاءات اللاحقة سوى عمليات الترحيل الجديدة. وكلما غيّرت schema.ts، شغّل generate ثم migrate من جديد.

ينتهي drizzle-kit migrate برمز الحالة 1 ومن دون أي رسالة error عندما يتعذّر عليه الاتصال، كأن يكون مسار sslrootcert أو كلمة المرور غير صحيحين. في هذه الحالة، اختبر DIRECT_DATABASE_URL أولًا باستخدام psql.

يطبّق drizzle-kit push تغييرات المخطط من دون ملفات ترحيل. وهو مفيد عند إعداد النماذج الأولية، أما في بيئة الإنتاج فيوفّر لك generate وmigrate ملفات SQL قابلة للمراجعة وسجلًا بالتغييرات.

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

أنشئ الملف src/db/index.ts، الذي يُنشئ عميل Drizzle عبر مجمّع اتصالات node-postgres باستخدام اتصال PgBouncer:

src/db/index.ts

import "dotenv/config";
import { drizzle } from "drizzle-orm/node-postgres";

// The app uses the PgBouncer connection (port 6432)
export const db = drizzle(process.env.DATABASE_URL!);

أنشئ الملف src/server.ts، وهو خادم HTTP صغير يُنفّذ استعلام Drizzle واحدًا لكل مسار. أما إن كان لديك تطبيق قائم، فيمكنك بدلًا من ذلك استدعاء استعلامات db نفسها من معالجات المسارات في تطبيقك:

src/server.ts

import { createServer } from "node:http";
import { desc, eq, not } from "drizzle-orm";
import { db } from "./db";
import { todos } from "./db/schema";

const server = createServer(async (req, res) => {
  const url = new URL(req.url ?? "/", "http://localhost");
  const id = Number(url.pathname.split("/")[2]);
  let body: unknown;

  try {
    if (req.method === "GET" && url.pathname === "/todos") {
      // Read
      body = await db.select().from(todos).orderBy(desc(todos.id));
    } else if (req.method === "POST" && url.pathname === "/todos") {
      // Create
      const title = url.searchParams.get("title") ?? "Untitled";
      [body] = await db.insert(todos).values({ title }).returning();
    } else if (req.method === "PATCH" && id) {
      // Update: toggle the done flag
      [body] = await db
        .update(todos)
        .set({ done: not(todos.done) })
        .where(eq(todos.id, id))
        .returning();
    } else if (req.method === "DELETE" && id) {
      // Delete
      [body] = await db.delete(todos).where(eq(todos.id, id)).returning();
    } else {
      res.writeHead(404).end();
      return;
    }
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify(body, null, 2) + "\n");
  } catch (err) {
    console.error(err);
    res.writeHead(500).end("Database error\n");
  }
});

server.listen(3101, () => console.log("Listening on http://localhost:3101/todos"));

لا حاجة إلى أي إعدادات للمشغّل عند استخدام PgBouncer. تستخدم استعلامات Drizzle عبارات غير مسمّاة افتراضيًا، كما يدعم PgBouncer المضمَّن العبارات المُعدّة مسبقًا المسمّاة أيضًا، مثل تلك التي تُنشأ باستخدام .prepare في Drizzle، وذلك في وضع تجميع المعاملات. أما الميزات المرتبطة بمستوى الـ session، مثل LISTEN والأقفال الاستشارية على مستوى الـ session، فلا تعمل عبر PgBouncer. راجع الأسئلة الشائعة.

التشغيل والتحقق

شغّل الخادم:

npx tsx src/server.ts

Listening on http://localhost:3101/todos

في طرفية ثانية، أنشئ مهمتين، ثم حدِّد الأولى على أنها مكتملة، واحذف الثانية:

curl -X POST "http://localhost:3101/todos?title=Try%20Drizzle%20ORM"
curl -X POST "http://localhost:3101/todos?title=Write%20a%20migration"
curl -X PATCH http://localhost:3101/todos/1
curl -X DELETE http://localhost:3101/todos/2

يُرجِع طلب PATCH الصفَّ المُحدَّث:

{
  "id": 1,
  "title": "Try Drizzle ORM",
  "done": true,
  "createdAt": "2026-09-30T16:45:14.610Z"
}

افتح http://localhost:3101/todos في متصفحك لعرض المهام المتبقية. ستظهر الاستجابة على النحو التالي:

[
  {
    "id": 1,
    "title": "Try Drizzle ORM",
    "done": true,
    "createdAt": "2026-09-30T16:45:14.610Z"
  }
]

لعرض البيانات في وحدة التحكم، افتح SQL console من الشريط الجانبي الأيسر لخدمتك، ثم وسّع guide_drizzle ثم public، وانقر على جدول todos. يحتوي المخطط drizzle على جدول سجل عمليات الترحيل. ويضم الجدول الصف المتبقي:

id	title	done	created_at
1	Try Drizzle ORM	true	2026-09-30 16:45:14.610099+00

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

الاتصال: سلاسل الاتصال وPgBouncer وTLS
الإعدادات: معلمات Postgres وPgBouncer، مثل max_connections
النسخ المتماثلة للقراءة: توسيع نطاق عمليات القراءة باستخدام الدالة withReplicas في Drizzle
الأمان: قوائم التحكم في الوصول حسب عناوين IP والشبكات الخاصة

بدء الاستخدام

الميزات

أدلة إرشادية

الأسعار

تكامل ClickHouse

عمليات الترحيل

المراقبة

الأسئلة الشائعة

استخدام Drizzle ORM مع ClickHouse Managed Postgres

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

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

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

إعداد المشروع

تهيئة الاتصال

تعريف المخطط

تشغيل عمليات الترحيل

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

التشغيل والتحقق

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

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

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

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

​إعداد المشروع

​تهيئة الاتصال

​تعريف المخطط

​تشغيل عمليات الترحيل

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

​التشغيل والتحقق

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

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

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

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

إعداد المشروع

تهيئة الاتصال

تعريف المخطط

تشغيل عمليات الترحيل

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

التشغيل والتحقق

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