SQLite Wasm в браузере, поддерживаемый частной файловой системой Origin.

Используйте SQLite для эффективного удовлетворения всех ваших потребностей в хранении данных в Интернете.

Thomas Steiner

SQLite — популярная, легкая, встроенная система управления реляционными базами данных с открытым исходным кодом . Многие разработчики используют его для хранения данных в структурированном и простом в использовании виде. Из-за небольшого размера и низких требований к памяти SQLite часто используется в качестве ядра базы данных в мобильных устройствах, настольных приложениях и веб-браузерах.

Одной из ключевых особенностей SQLite является то, что это бессерверная база данных, а это означает, что для ее работы не требуется отдельный серверный процесс. Вместо этого база данных хранится в одном файле на устройстве пользователя, что упрощает интеграцию с приложениями.

SQLite на основе веб-сборки

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

Использование SQLite Wasm с серверной частью сохранения частной файловой системы Origin

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

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

npm install @sqlite.org/sqlite-wasm

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

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

Как вы можете себе представить, последний пункт целей проекта — Поддержка постоянного хранилища на стороне клиента с использованием доступных API-интерфейсов JavaScript — предполагает строгие требования к производительности в отношении сохранения данных в файле базы данных. Именно здесь в игру вступает исходная частная файловая система, а точнее, метод createSyncAccessHandle() объектов FileSystemFileHandle . Этот метод возвращает Promise, который разрешается в объект FileSystemSyncAccessHandle , который можно использовать для синхронного чтения и записи в файл. Синхронный характер этого метода дает преимущества в производительности, но поэтому его можно использовать только внутри выделенных веб-воркеров для файлов в частной файловой системе Origin, поэтому основной поток нельзя заблокировать.

Установка необходимых заголовков

Помимо других файлов, загруженный архив 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 с серверной частью персистентности исходной частной файловой системы должен запускаться из контекста 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 используйте расширение Chrome OPFS Explorer .

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

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

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

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