Skip to main content
Kysely أداة لبناء استعلامات SQL بأمان الأنواع (type-safe) في TypeScript. في هذا الدليل، ستربط Kysely بخدمة ClickHouse Managed Postgres عبر المشغّل pg باتصال TLS موثَّق، ثم تنشئ جدولًا باستخدام عمليات الترحيل (migrations) في Kysely، وأخيرًا تشغّل واجهة برمجة تطبيقات صغيرة لإدارة قائمة المهام باستخدام Node.js.

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

  • Node.js بالإصدار 22.18 أو أحدث، إذ يشغّل ملفات TypeScript مباشرةً دون الحاجة إلى خطوة بناء. تستخدم ملفات هذا الدليل الامتداد .mts، لذا يتعامل Node.js معها على أنها وحدات ES في مشاريع CommonJS ومشاريع وحدات ES على حدٍّ سواء.
  • حساب على ClickHouse Cloud.
  • psql لإنشاء قاعدة البيانات. ويمكنك أيضًا تشغيل عبارة CREATE DATABASE في SQL console.
  • curl لاستدعاء واجهة برمجة التطبيقات.
اختُبر هذا الدليل باستخدام Node.js 24.21 وKysely 0.29.6 وpg 8.23.1 وTypeScript 7.0.2 وPostgreSQL 18.

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

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

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

انقر على Connect في الشريط الجانبي الأيسر لخدمتك. أبقِ الخيار Directly محددًا وفعّل Use SSL، وستلاحظ أن سلسلة الاتصال url أصبحت تنتهي بـ sslmode=verify-full&sslrootcert=.... انقر على Download CA certificate لتنزيل شهادة CA الخاصة بخدمتك، والمسماة <service-name>-ca-certificate.pem، ثم انسخ سلسلة الاتصال. يتصل هذا الدليل مباشرةً بـ Postgres على المنفذ 5432، وذلك لسببين:
  • خادم Node.js عملية طويلة الأمد، وPool في pg يُبقي أصلًا مجموعة صغيرة من الاتصالات مفتوحة ويعيد استخدامها، لذا لا يضيف مُجمِّع اتصالات من جهة الخادم فائدة تُذكر.
  • يحتفظ Migrator في Kysely بقفل استشاري على مستوى الـ session (pg_advisory_lock) طوال تشغيل عمليات الترحيل. وبما أن PgBouncer يعمل في وضع تجميع المعاملات، فقد تُنفَّذ كل من خطوات الحصول على القفل وتشغيل عمليات الترحيل وتحرير القفل على اتصال خلفي مختلف. ونتيجةً لذلك، قد يظل القفل محجوزًا على أحد الاتصالات المُجمَّعة عند المرور عبر PgBouncer، فتتعطل عمليات الترحيل اللاحقة بانتظار تحريره.
إذا شغّلت لاحقًا عددًا كبيرًا من مثيلات التطبيق أو الدوال بلا خادم، فيمكنك توجيه سلسلة اتصال التطبيق إلى PgBouncer (المنفذ 6432، على المضيف نفسه). يعمل Kysely مع pg في وضع تجميع المعاملات لأن pg يستخدم افتراضيًا عبارات مُعدّة مسبقًا غير مسمّاة. أما عمليات الترحيل، فواصل تشغيلها على المنفذ 5432. راجع تجميع الاتصالات عبر PgBouncer.

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

أنشئ مشروعًا، ثم ثبّت Kysely ومشغّل pg وTypeScript:
هل تُضيف إلى تطبيق قائم؟تخطَّ الأمرين mkdir kysely-todo && cd kysely-todo وnpm init -y. وبدلًا من ذلك، شغّل الأوامر التالية داخل مشروعك، إذ تُضيف النصين البرمجيين migrate وtypecheck دون المساس بالنص البرمجي start، ثم تابع إلى قسم تهيئة الاتصال.

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

انقل شهادة CA التي نزّلتها إلى دليل مشروعك، وغيّر اسمها إلى ca-certificate.pem. بعد ذلك، أنشئ قاعدة بيانات للتطبيق:
أضف سلسلة الاتصال التي نسختها إلى ملف .env جديد، أو إلى ملف .env الموجود لديك. استبدل <PASSWORD> بكلمة المرور الخاصة بك، واسم قاعدة البيانات بـ guide_kysely، واضبط sslrootcert على القيمة ca-certificate.pem:
.env
تقرأ pg المعاملين sslmode وsslrootcert من سلسلة الاتصال: إذ يجعلها verify-full تتحقق من أن شهادة الخادم موقّعة من الـ CA الخاصة بخدمتك وأنها تطابق اسم المضيف. ويُحَلّ مسار sslrootcert نسبةً إلى دليل العمل، وهو الدليل الجذر للمشروع عند استخدام npm run.
أبقِ sslmode=verify-full في عنوان URL، إذ إنه في غياب sslmode لا تستخدم pg بروتوكول TLS ولا تتحقق من هوية الخادم. ولا تمرّر كذلك كائن ssl إلى Pool: فعندما يحتوي عنوان URL على sslmode، تحلّ إعدادات عنوان URL محلّ كائن ssl الخاص بك. وإذا احتجت إلى تحميل الـ CA من مصدر آخر غير ملف، فاحذف sslmode وsslrootcert من عنوان URL ومرّر ssl: { ca } إلى Pool بدلًا من ذلك.
أضِف ملف tsconfig.json حتى يتحقق tsc من الأنواع في الملفات نفسها التي يشغّلها Node.js. وإذا كان تطبيقك يحتوي أصلًا على ملف tsconfig.json، فادمج فيه خيارات compilerOptions هذه والمجلد migrations:
tsconfig.json

تعريف واجهة قاعدة البيانات

يستنتج Kysely أنواع كل استعلام من واجهة تصف جداولك. أنشئ الملف src/db.mts بحيث يتضمّن الواجهة ومثيل Kysely يستخدم PostgresDialect مع Pool من pg:
src/db.mts
يُشير Generated إلى الأعمدة التي تملؤها قاعدة البيانات تلقائيًا، ولذلك يكون تحديد قيمها اختياريًا عند الإدراج.

إنشاء ترحيل وتشغيله

يستخدم هذا الدليل أداة Migrator المدمجة في Kysely مع FileMigrationProvider، وكلتاهما جزء من الحزمة الأساسية kysely. أما واجهة سطر الأوامر المستقلة kysely-ctl فاستخدامها اختياري، وهي مجرد غلاف لأداة Migrator نفسها. أنشئ ملف ترحيل. تنفّذ Kysely عمليات الترحيل وفق الترتيب الأبجدي الرقمي لأسماء ملفاتها، لذا ابدأ اسم كل ملف بتاريخ:
migrations/2026-09-30_create_todo.mts
أنشئ الملف src/migrate.mts لتطبيق جميع عمليات الترحيل المعلّقة. في الإصدار Kysely 0.29، استورد Migrator وFileMigrationProvider من kysely/migration:
src/migrate.mts
شغّل عملية الترحيل:
يسجّل Kysely عمليات الترحيل المُطبَّقة في الجدول kysely_migration، ولذلك لن يكون لتشغيل الأمر مرة أخرى أي أثر.
للتأكد من أن pg يتحقق فعلًا من الشهادة، شغّل عملية الترحيل بدون sslrootcert. لا يثق Node.js افتراضيًا بجهة إصدار الشهادات (CA) الخاصة بخدمتك، ولذلك سيفشل الاتصال:

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

أنشئ الملف src/server.mts، وهو خادم HTTP صغير يُنشئ قائمة المهام (to-dos) ويقرؤها ويحدّثها ويحذفها باستخدام Kysely. وإذا كان لديك تطبيق قائم، فيمكنك استخدام الاستعلامات نفسها ضمن معالجات المسارات الخاصة بك:
src/server.mts
لأن كل استعلام يُتحقَّق منه وفقًا للواجهة Database، فإن أي خطأ إملائي في اسم جدول أو عمود، أو أي عملية إدراج تخلو من الحقل المطلوب title، سيؤدي إلى فشل التحقق من الأنواع. تحقَّق من المشروع:

التحقق

شغّل الخادم:
أما في تطبيق قائم يُشغِّل فيه الأمر npm start تطبيقك الخاص، فشغِّل خادم المثال بدلًا من ذلك باستخدام node --env-file=.env src/server.mts. في طرفية أخرى، أنشئ بعض المهام ثم حدِّثها واحذفها:
افتح http://localhost:3000/todos في متصفحك لعرض قائمة المهام المتبقية. ستظهر الاستجابة على النحو التالي:
لعرض البيانات نفسها في وحدة التحكم، افتح SQL console من الشريط الجانبي الأيسر لخدمتك، ثم وسّع guide_kysely والمخطط public، وانقر على الجدول todo. ستجد بجانبه الجدولين kysely_migration وkysely_migration_lock اللذين أنشأهما Kysely:

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