SQLite Wasm في المتصفّح المتوافق مع Origin Private File System

استخدِم SQLite للتعامل مع جميع احتياجاتك المتعلقة بالتخزين بكفاءة على الويب.

Thomas Steiner

‫SQLite هي نظام إدارة قواعد بيانات ارتباطية مضمّن وخفيف الوزن ومفتوح المصدر وشائع الاستخدام. يستخدم العديد من المطوّرين هذه اللغة لتخزين البيانات بطريقة منظَّمة وسهلة الاستخدام. نظرًا لصغر حجمها ومتطلبات الذاكرة المنخفضة، يتم غالبًا استخدام SQLite كمحرك قاعدة بيانات في الأجهزة الجوّالة وتطبيقات الكمبيوتر المكتبي ومتصفحات الويب.

من الميزات الرئيسية في SQLite أنّها قاعدة بيانات بدون خادم، ما يعني أنّها لا تتطلّب عملية خادم منفصلة لتشغيلها. بدلاً من ذلك، يتم تخزين قاعدة البيانات في ملف واحد على جهاز المستخدم، ما يسهّل دمجها في التطبيقات.

‫SQLite استنادًا إلى Web Assembly

تتوفّر عدة إصدارات غير رسمية من SQLite تستند إلى Web Assembly (Wasm)، ما يتيح استخدامها في متصفحات الويب، مثل sql.js. يُعد المشروع الفرعي sqlite3 WASM/JS أول مشروع مرتبط رسميًا بمشروع SQLite، ما يجعل إصدارات Wasm من المكتبة من بين العناصر التي يقدّمها مشروع SQLite. تشمل الأهداف المحددة لهذا المشروع ما يلي:

• ربط واجهة برمجة تطبيقات sqlite3 منخفضة المستوى تكون قريبة قدر الإمكان من واجهة C من حيث الاستخدام
• واجهة برمجة تطبيقات موجّهة للكائنات ذات مستوى أعلى، تشبه إلى حد كبير sql.js و عمليات التنفيذ بأسلوب Node.js، وتتواصل مباشرةً مع واجهة برمجة التطبيقات ذات المستوى المنخفض. يجب استخدام واجهة برمجة التطبيقات هذه من سلسلة المحادثات نفسها التي يتم منها استخدام واجهة برمجة التطبيقات ذات المستوى المنخفض.
• واجهة برمجة تطبيقات مستندة إلى Worker تتواصل مع واجهات برمجة التطبيقات السابقة من خلال رسائل Worker تم تصميم هذا الإجراء ليتم استخدامه في سلسلة التعليمات البرمجية الرئيسية، مع تثبيت واجهات برمجة التطبيقات ذات المستوى الأدنى في سلسلة تعليمات برمجية Worker، والتواصل معها من خلال رسائل Worker.
• إصدار مستند إلى Promise من Worker API يخفي تمامًا جوانب التواصل بين سلاسل التنفيذ عن المستخدم.
• إتاحة مساحة تخزين دائمة من جهة العميل باستخدام واجهات برمجة تطبيقات JavaScript المتاحة، بما في ذلك نظام الملفات الخاص بالمصدر (OPFS)

استخدام SQLite Wasm مع الخلفية الدائمة لنظام الملفات الخاص بالمصدر

تثبيت المكتبة من npm

ثبِّت حزمة @sqlite.org/sqlite-wasm من npm باستخدام الأمر التالي:

npm install @sqlite.org/sqlite-wasm

نظام الملفات الخاص في Origin

تمت إضافة سطح خاص إلى نظام الملفات الخاص بالمصدر (OPFS، وهو جزء من File System Access API) يتيح الوصول إلى البيانات بأداء عالٍ جدًا. يختلف هذا السطح الجديد عن الأسطح الحالية من خلال توفير إذن وصول حصري للكتابة في محتوى ملف. يؤدي هذا التغيير، إلى جانب إمكانية قراءة التعديلات التي لم تتم مزامنتها بشكل متّسق وتوفُّر صيغة متزامنة على العاملين المخصّصين، إلى تحسين الأداء بشكل كبير وإتاحة حالات استخدام جديدة.

كما تتوقّع، يتضمّن آخر هدف من أهداف المشروع، وهو توفير مساحة تخزين دائمة من جهة العميل باستخدام واجهات برمجة تطبيقات JavaScript المتاحة، متطلبات أداء صارمة بشأن تخزين البيانات في ملف قاعدة البيانات. هنا يأتي دور نظام الملفات الخاص بالمصدر، وتحديدًا طريقة createSyncAccessHandle() لكائنات FileSystemFileHandle. تعرض هذه الطريقة Promise يتم تنفيذه إلى كائن FileSystemSyncAccessHandle يمكن استخدامه لقراءة ملف وكتابة بيانات فيه بشكل متزامن. توفّر الطبيعة المتزامنة لهذه الطريقة مزايا متعلقة بالأداء، ولكن لا يمكن استخدامها إلا داخل Web Workers المخصّصة للملفات ضمن نظام Origin Private File System، وذلك لكي لا يتم حظر سلسلة التعليمات الرئيسية.

ضبط العناوين المطلوبة

من بين الملفات الأخرى، يحتوي أرشيف SQLite Wasm الذي تم تنزيله على الملفَين sqlite3.js وsqlite3.wasm، اللذين يشكّلان إصدار sqlite3 WASM/JS. يحتوي الدليل jswasm على منتجات sqlite3 الأساسية، ويحتوي الدليل ذو المستوى الأعلى على تطبيقات تجريبية واختبارية. لن تعرض المتصفحات ملفات Wasm من عناوين URL التي تبدأ بـ file://، لذا فإنّ أي تطبيقات تنشئها باستخدام هذا البروتوكول تتطلّب خادم ويب، ويجب أن يتضمّن هذا الخادم العناوين التالية في استجابته عند عرض الملفات:

• يجب ضبط قيمة Cross-Origin-Opener-Policy على التوجيه same-origin، ما يؤدي إلى عزل سياق التصفّح بشكل حصري للمستندات من المصدر نفسه. لا يتم تحميل المستندات من مصادر متعددة في سياق التصفّح نفسه.
• Cross-Origin-Embedder-Policy تم ضبطها على التوجيه require-corp، وبالتالي لا يمكن للمستند تحميل الموارد إلا من المصدر نفسه، أو الموارد التي تم وضع علامة عليها بشكل صريح بأنّها قابلة للتحميل من مصدر آخر.

سبب الحاجة إلى هذه العناوين هو أنّ SQLite Wasm يعتمد على SharedArrayBuffer، ويشكّل ضبط هذه العناوين جزءًا من متطلبات الأمان.

إذا فحصت عدد الزيارات باستخدام "أدوات مطوّري البرامج في Chrome"، من المفترض أن تجد المعلومات التالية:

Speedtest

أجرى فريق SQLite بعض المقارنات المعيارية على تنفيذ WebAssembly مقارنةً بلغة Web SQL التي تم إيقافها نهائيًا. توضّح مقاييس الأداء هذه أنّ SQLite Wasm تتسم عمومًا بالسرعة نفسها التي تتسم بها Web SQL. في بعض الأحيان تكون السرعة أبطأ قليلاً، وفي أحيان أخرى تكون أسرع قليلاً. يمكنك الاطّلاع على كل التفاصيل في صفحة النتائج.

عيّنة التعليمات البرمجية لبدء الاستخدام

كما ذكرنا سابقًا، يجب تشغيل SQLite Wasm مع الخلفية الدائمة لنظام الملفات الخاص بالمصدر من سياق Worker. والخبر السار هو أنّ المكتبة تتولّى كل ذلك تلقائيًا، ويمكنك استخدامها مباشرةً من سلسلة التعليمات الرئيسية.

import { sqlite3Worker1Promiser } from '@sqlite.org/sqlite-wasm';

(async () => {
  try {
    console.log('Loading and initializing SQLite3 module...');

    const promiser = await new Promise((resolve) => {
      const _promiser = sqlite3Worker1Promiser({
        onready: () => {
          resolve(_promiser);
        },
      });
    });

    console.log('Done initializing. Running demo...');

    let response;

    response = await promiser('config-get', {});
    console.log('Running SQLite3 version', response.result.version.libVersion);

    response = await promiser('open', {
      filename: 'file:worker-promiser.sqlite3?vfs=opfs',
    });
    const { dbId } = response;
    console.log(
      'OPFS is available, created persisted database at',
      response.result.filename.replace(/^file:(.*?)\?vfs=opfs$/, '$1'),
    );

    await promiser('exec', { dbId, sql: 'CREATE TABLE IF NOT EXISTS t(a,b)' });
    console.log('Creating a table...');

    console.log('Insert some data using exec()...');
    for (let i = 20; i <= 25; ++i) {
      await promiser('exec', {
        dbId,
        sql: 'INSERT INTO t(a,b) VALUES (?,?)',
        bind: [i, i * 2],
      });
    }

    console.log('Query data with exec()');
    await promiser('exec', {
      dbId,
      sql: 'SELECT a FROM t ORDER BY a LIMIT 3',
      callback: (result) => {
        if (!result.row) {
          return;
        }
        console.log(result.row);
      },
    });

    await promiser('close', { dbId });
  } catch (err) {
    if (!(err instanceof Error)) {
      err = new Error(err.result.message);
    }
    console.error(err.name, err.message);
  }
})();

عرض توضيحي

يمكنك الاطّلاع على الرمز أعلاه في العرض التوضيحي. ننصحك بالاطّلاع على رمز المصدر على GitHub. لاحظ أنّ الإصدار المضمّن أدناه لا يستخدم الخلفية البرمجية لنظام OPFS، ولكن عند فتح العرض التوضيحي في علامة تبويب منفصلة، يتم استخدامها.

تصحيح أخطاء Origin Private File System

لتصحيح أخطاء إخراج نظام الملفات الخاص بالمصدر في SQLite Wasm، استخدِم إضافة Chrome OPFS Explorer.

بعد تثبيت الإضافة، افتح "أدوات مطوّري البرامج في Chrome"، واختَر علامة التبويب OPFS Explorer، وستكون جاهزًا بعد ذلك لفحص ما يكتبه SQLite Wasm في نظام الملفات الخاص بالمصدر.

إذا اخترت أيًا من الملفات في نافذة OPFS Explorer في "أدوات مطوّلي البرامج"، يمكنك حفظها على القرص المحلي. يمكنك بعد ذلك استخدام تطبيق مثل SQLite Viewer لفحص قاعدة البيانات، ما يتيح لك التأكّد من أنّ SQLite Wasm يعمل على النحو المطلوب.

الحصول على المساعدة وتقديم الملاحظات

تم تطوير SQLite Wasm وصيانتها من قِبل منتدى SQLite. يمكنك الحصول على المساعدة وتقديم الملاحظات من خلال البحث في منتدى الدعم ونشر مشاركات فيه. تتوفّر المستندات الكاملة على موقع SQLite الإلكتروني.