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, максимально приближенного по использованию к API C.
• Объектно-ориентированный API более высокого уровня, более похожий на реализации в стиле sql.js и Node.js, который напрямую взаимодействует с API низкого уровня. Этот API должен использоваться из того же потока, что и API низкого уровня.
• API на базе Worker, взаимодействующее с предыдущими API посредством сообщений Worker. Этот API предназначен для использования в основном потоке, при этом API нижнего уровня устанавливаются в потоке Worker и взаимодействуют с ними посредством сообщений Worker.
• Вариант API Worker на базе Promise, который полностью скрывает от пользователя аспекты межпотокового взаимодействия.
• Поддержка постоянного хранения на стороне клиента с использованием доступных API JavaScript, включая Origin Private File System (OPFS).

Использование SQLite Wasm с бэкэндом персистентности Origin Private File System

Установка библиотеки из npm

Установите пакет @sqlite.org/sqlite-wasm из npm с помощью следующей команды:

npm install @sqlite.org/sqlite-wasm

Частная файловая система Origin

Файловая система Origin Private File System (OPFS, часть API доступа к файловой системе ) дополнена специальной поверхностью, обеспечивающей высокопроизводительный доступ к данным. Эта новая поверхность отличается от существующих тем, что предлагает эксклюзивный доступ к записи содержимого файла на месте. Это изменение, наряду с возможностью последовательного чтения несброшенных изменений и наличием синхронного варианта на выделенных рабочих процессах, значительно повышает производительность и открывает новые возможности использования.

Как вы можете себе представить, последний пункт целей проекта, поддержка постоянного хранилища на стороне клиента с использованием доступных API JavaScript, предъявляет строгие требования к производительности при сохранении данных в файле базы данных. Именно здесь в игру вступает Origin Private File System, а точнее, метод createSyncAccessHandle() объекта FileSystemFileHandle . Этот метод возвращает Promise, который преобразуется в объект FileSystemSyncAccessHandle , который можно использовать для синхронного чтения и записи данных из файла. Синхронная природа этого метода обеспечивает повышение производительности, но поэтому он применим только внутри выделенных веб-воркеров для файлов в 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 , и установка этих заголовков является частью его требований безопасности .

Если вы проверите трафик с помощью DevTools, вы должны найти следующую информацию:

Тест скорости

Команда SQLite провела несколько сравнительных тестов своей реализации WebAssembly с устаревшим Web SQL. Результаты тестов показывают, что SQLite Wasm в целом примерно так же быстр, как и Web SQL. Иногда он немного медленнее, иногда немного быстрее. Подробности смотрите на странице результатов .

Пример кода для начала работы

Как уже упоминалось, SQLite Wasm с бэкендом персистентности Origin Private File System должен запускаться из контекста 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

Для отладки выходных данных SQLite Wasm Origin Private File System используйте расширение OPFS Explorer для Chrome.

После установки расширения откройте Chrome DevTools, выберите вкладку OPFS Explorer , и теперь вы готовы проверить, что SQLite Wasm записывает в частную файловую систему Origin.

Выбрав любой из файлов в окне OPFS Explorer в DevTools, вы можете сохранить его на локальный диск. Затем можно использовать приложение, например SQLite Viewer , для проверки базы данных и убедиться, что SQLite Wasm действительно работает так, как и заявлено.

Получите помощь и оставьте отзыв

SQLite Wasm разрабатывается и поддерживается сообществом SQLite. Чтобы получить помощь и оставить отзыв, выполните поиск и оставьте сообщение на форуме поддержки . Полная документация доступна на сайте SQLite.