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 پشتیبانی شده را ایجاد می کند. اهداف ملموس این پروژه عبارتند از:

• اتصال یک API سطح پایین sqlite3 که از نظر استفاده تا حد امکان به C نزدیک است.
• یک API شی گرا سطح بالاتر، بیشتر شبیه به پیاده سازی های سبک sql.js و Node.js ، که مستقیماً با API سطح پایین صحبت می کند. این API باید از همان رشته ای استفاده شود که API سطح پایین است.
• یک API مبتنی بر Worker که از طریق پیام‌های Worker با APIهای قبلی صحبت می‌کند. این یکی برای استفاده در رشته اصلی، با API های سطح پایین تر در یک رشته Worker نصب شده و صحبت با آنها از طریق پیام های Worker در نظر گرفته شده است.
• یک نوع مبتنی بر Promise از Worker API که به طور کامل جنبه های ارتباطی بین رشته ای را از کاربر پنهان می کند.
• پشتیبانی از ذخیره سازی دائمی سمت مشتری با استفاده از API های جاوا اسکریپت موجود، از جمله سیستم فایل خصوصی Origin (OPFS).

استفاده از SQLite Wasm با سیستم فایل خصوصی Origin Persistence

نصب کتابخانه از npm

بسته @sqlite.org/sqlite-wasm را از npm با دستور زیر نصب کنید:

npm install @sqlite.org/sqlite-wasm

سیستم فایل خصوصی Origin

Origin Private File System (OPFS، بخشی از File System Access API ) با سطح ویژه ای افزوده شده است که دسترسی بسیار کارآمد به داده ها را به ارمغان می آورد. این سطح جدید با ارائه دسترسی نوشتن در محل و انحصاری به محتوای فایل با سطوح موجود متفاوت است. این تغییر، همراه با توانایی خواندن مداوم اصلاحات بدون شستشو و در دسترس بودن یک نوع همزمان در کارگران اختصاصی، به طور قابل توجهی عملکرد را بهبود می بخشد و موارد استفاده جدید را رفع می کند.

همانطور که می توانید تصور کنید، آخرین نقطه از اهداف پروژه، پشتیبانی از ذخیره سازی دائمی سمت کلاینت با استفاده از API های جاوا اسکریپت موجود، با الزامات عملکرد سختگیرانه در رابطه با ماندگاری داده ها در فایل پایگاه داده همراه است. اینجاست که Origin Private File System، و به طور خاص، متد createSyncAccessHandle() در اشیاء FileSystemFileHandle وارد عمل می شود. این روش یک Promise را برمی گرداند که به یک شی FileSystemSyncAccessHandle که می تواند برای خواندن و نوشتن همزمان از یک فایل استفاده شود، حل می شود. ماهیت همزمان این روش مزایای عملکردی را به همراه دارد، اما بنابراین فقط در داخل Web Workers اختصاصی برای فایل‌های داخل Origin Private File System قابل استفاده است، بنابراین رشته اصلی نمی‌تواند مسدود شود.

تنظیم سرصفحه های مورد نیاز

در میان فایل‌های دیگر، بایگانی دانلود شده SQLite Wasm حاوی فایل‌های sqlite3.js و sqlite3.wasm است که بیلد sqlite3 WASM/JS را تشکیل می‌دهند. دایرکتوری jswasm شامل موارد تحویلی هسته sqlite3 و دایرکتوری سطح بالا شامل برنامه های نمایشی و آزمایشی است. مرورگرها فایل‌های Wasm را از نشانی‌های اینترنتی file:// ارائه نمی‌کنند، بنابراین هر برنامه‌ای که با آن می‌سازید به وب سرور نیاز دارد و آن سرور باید هنگام ارائه فایل‌ها، سرصفحه‌های زیر را در پاسخ خود داشته باشد:

• Cross-Origin-Opener-Policy روی دستورالعمل same-origin تنظیم شده است، که زمینه مرور را منحصراً به اسناد با مبدا مشابه جدا می کند. اسناد متقاطع در یک زمینه مرور بارگیری نمی شوند.
• Cross-Origin-Embedder-Policy روی دستورالعمل require-corp تنظیم شده است، بنابراین یک سند فقط می تواند منابع را از همان مبدأ بارگیری کند، یا منابعی را که صریحاً به عنوان قابل بارگیری از مبدا دیگری علامت گذاری شده اند، بارگیری کند.

دلیل این هدرها این است که SQLite Wasm به SharedArrayBuffer وابسته است و تنظیم این هدرها بخشی از الزامات امنیتی آن است.

اگر ترافیک را با DevTools بررسی می کنید، باید اطلاعات زیر را بیابید:

سرعت تست

تیم SQLite برخی از معیارها را در اجرای WebAssembly خود در مقایسه با Web SQL منسوخ شده اجرا کرده است. این معیارها نشان می‌دهند که SQLite Wasm معمولاً به سرعت Web SQL است. گاهی اوقات کمی کندتر است، گاهی اوقات کمی سریعتر. تمام جزئیات را در صفحه نتایج مشاهده کنید.

شروع نمونه کد

همانطور که قبلاً ذکر شد، SQLite Wasm با سیستم فایل خصوصی Origin باید از یک زمینه 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);
  }
})();

نسخه ی نمایشی

کد بالا را در عمل در دمو مشاهده کنید. حتماً کد منبع را در Glitch بررسی کنید. توجه داشته باشید که چگونه نسخه تعبیه‌شده زیر از باطن OPFS استفاده نمی‌کند، اما وقتی نسخه نمایشی را در یک برگه جداگانه باز می‌کنید، از آن استفاده می‌کند.

سیستم فایل خصوصی Origin را اشکال زدایی کنید

برای اشکال زدایی خروجی سیستم فایل خصوصی Origin SQLite Wasm، از افزونه OPFS Explorer Chrome استفاده کنید.

پس از نصب افزونه، Chrome DevTools را باز کنید، برگه OPFS Explorer را انتخاب کنید و سپس آماده بررسی آنچه SQLite Wasm در Origin Private File System می‌نویسد، هستید.

اگر هر یک از فایل‌ها را در پنجره OPFS Explorer در DevTools انتخاب کنید، می‌توانید آن را در دیسک محلی ذخیره کنید. سپس می‌توانید از برنامه‌ای مانند SQLite Viewer برای بازرسی پایگاه داده استفاده کنید، بنابراین می‌توانید به خودتان اطمینان دهید که SQLite Wasm در واقع همان‌طور که وعده داده بود کار می‌کند.

کمک بگیرید و بازخورد ارائه دهید

SQLite Wasm توسط انجمن SQLite توسعه و نگهداری می شود. با جستجو و ارسال در انجمن پشتیبانی، کمک دریافت کنید و بازخورد ارائه دهید. مستندات کامل در سایت SQLite موجود است.