Kysely مع TypeScript: الدليل الشامل لبناء استعلامات SQL آمنة من حيث الأنواع

1. ما هو Kysely ولماذا تحتاجه؟

Kysely (تُنطق "كي-سي-لي") هو أداة بناء استعلامات SQL حديثة وآمنة من حيث الأنواع (type-safe) مخصصة لـ TypeScript و Node.js. يتيح لك كتابة استعلامات SQL مع دعم كامل للأنواع في جميع المراحل: من بناء الاستعلام إلى الحصول على النتيجة. على عكس أدوات ORM التقليدية مثل TypeORM أو Prisma، لا يقوم Kysely بتجريد SQL، بل يوفر واجهة برمجة تطبيقات (API) سهلة لكتابتها مع الاحتفاظ بالتحكم الكامل في الاستعلامات المُنشأة. هذا يعني أنه يمكنك استخدام كامل قوة SQL (JOIN، الاستعلامات الفرعية، دوال النوافذ، CTE) دون الحاجة لمواجهة قيود ORM.

المشكلة الأساسية التي يحلها Kysely هي أمان الأنواع في استعلامات SQL. في كود JavaScript/TypeScript العادي، غالبًا ما تُكتب استعلامات SQL كنصوص (strings)، مما يؤدي إلى أخطاء في وقت التشغيل (runtime errors): أخطاء إملائية في أسماء الأعمدة، عدم تطابق أنواع البيانات، JOINs غير صحيحة. يحل Kysely هذه المشكلة على مستوى الترجمة (compilation): إذا حاولت الوصول إلى عمود غير موجود أو تمرير نوع بيانات خاطئ، سيعرض TypeScript خطأً قبل تشغيل التطبيق. هذا يقلل بشكل كبير من وقت التصحيح ويزيد من موثوقية الكود.

يعتبر Kysely مثاليًا للمشاريع التي تتطلب أقصى أداء وتحكم في SQL، مع الرغبة في الاستفادة من مزايا الكتابة الثابتة (static typing). يدعم PostgreSQL، MySQL، SQLite، و MSSQL، ويحتوي على حماية مدمجة ضد حقن SQL (SQL injection) عبر الاستعلامات المُعلمة (parameterized queries)، ودعم للترحيلات (migrations) وتوليد الأنواع من مخطط قاعدة البيانات الحالي. المكتبة في تطور نشط، ولديها توثيق جيد ومجتمع نشط.

2. التثبيت

يتم تثبيت Kysely عبر npm (أو yarn/pnpm). ستحتاج إلى تثبيت المكتبة نفسها ومشغل (driver) قاعدة البيانات الخاصة بك.

# الحزمة الأساسية
npm install kysely

# لـ PostgreSQL
npm install pg

# لـ MySQL
npm install mysql2

# لـ SQLite
npm install better-sqlite3

# لـ MSSQL
npm install tedious

إذا كنت تستخدم TypeScript، تأكد من تثبيت أنواع المشغل (عادةً ما تأتي مرفقة). للحصول على تجربة تطوير أفضل، يُنصح أيضًا بتثبيت ts-node لتشغيل ملفات TypeScript:

npm install -D ts-node typescript @types/node

للعمل مع الترحيلات (migrations)، قم بتثبيت حزمة إضافية:

npm install -D @kysely/cli

3. البداية السريعة — مثال عملي بسيط

لنقم بإنشاء تطبيق بسيط يتصل بقاعدة بيانات SQLite، وينشئ جدول المستخدمين، وينفذ بعض الاستعلامات.

أولاً، نحدد الأنواع (types) لقاعدة البيانات الخاصة بنا:

// types.ts
export interface User {
  id: number;
  name: string;
  email: string;
  age: number | null;
  created_at: Date;
}

export interface Database {
  users: User;
  // يمكن إضافة جداول أخرى هنا
}

الآن، لننشئ التطبيق الرئيسي:

// index.ts
import { Kysely, SqliteDialect } from 'kysely';
import Database from 'better-sqlite3';
import type { Database as MyDatabase } from './types';

// إنشاء نسخة من Kysely
const db = new Kysely<MyDatabase>({
  dialect: new SqliteDialect({
    database: new Database('my_database.db'),
  }),
});

async function main() {
  // إنشاء الجدول (إذا لم يكن موجودًا)
  await db.schema
    .createTable('users')
    .ifNotExists()
    .addColumn('id', 'integer', (col) => col.primaryKey().autoIncrement())
    .addColumn('name', 'varchar(255)', (col) => col.notNull())
    .addColumn('email', 'varchar(255)', (col) => col.notNull().unique())
    .addColumn('age', 'integer')
    .addColumn('created_at', 'datetime', (col) => col.defaultTo('now()'))
    .execute();

  // إدخال البيانات