SQLite WASM HTTP VFS Backend

Common errors

• ReferenceError: SharedArrayBuffer is not defined

  cause Attempting to use the shared cache backend in a browser environment without the necessary Cross-Origin Isolation headers (COOP/COEP) or in a Node.js environment that doesn't fully support Web Workers/SharedArrayBuffer.
  fix For browsers, ensure your server sends `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` headers. For Node.js, ensure you are running Node.js 18.x or higher, which provides built-in `web-worker` and `fetch` support. The library will attempt to fallback if these are not available.

• TypeError: require is not a function

  cause Trying to import `sqlite-wasm-http` using CommonJS `require()` syntax in an environment configured for ES modules, or in a project that needs to output ES modules.
  fix Refactor your imports to use ES module syntax (e.g., `import { createSQLiteThread } from 'sqlite-wasm-http';`). If using TypeScript, ensure your `tsconfig.json` `compilerOptions.module` is set to `ESNext` or `Node16`.

• Error: Unknown module: sqlite3-worker1-promiser-node.mjs

  cause This specific file (`sqlite3-worker1-promiser-node.mjs`) was eliminated in `v1.1.1` to reduce bundle size, indicating an outdated setup or caching issue if encountered on newer versions.
  fix Update `sqlite-wasm-http` to at least `v1.1.1`. Clear your `node_modules` and package manager cache (`npm cache clean --force` or `pnpm store prune`). Ensure your bundler is resolving to the latest version.

Warnings

• breaking The library is strictly ES6 module mode only. CommonJS is not supported, including TypeScript transpiled to CommonJS. Projects must be configured to transpile to ES6 modules.
  Fix: Ensure your `tsconfig.json` `compilerOptions.module` is set to `ESNext` or `Node16` and your bundler/runtime environment supports ESM. Do not use `require()` statements.
• gotcha Using the shared cache version with `SharedArrayBuffer` requires specific HTTP headers: `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp`. Without these, shared cache will not function, and the library will fallback to a non-shared version.
  Fix: Configure your web server to send `COOP: same-origin` and `COEP: require-corp` headers for the HTML page and JavaScript assets hosting the application. For local development, this may require specific server configurations or browser flags.
• gotcha For optimal performance, especially with remote databases, it is highly recommended to set your SQLite database `page_size` to 1024 bytes and run `VACUUM` and `PRAGMA JOURNAL_MODE = DELETE;`.
  Fix: Execute `PRAGMA JOURNAL_MODE = DELETE; PRAGMA page_size = 1024; VACUUM;` on your SQLite database file. For FTS tables, also `INSERT INTO ftstable(ftstable) VALUES ('optimize');`.
• breaking Node.js 18.19 introduced breaking changes that impacted integration tests. Users running specific Node.js 18.x versions might encounter unexpected behavior or require specific configurations.
  Fix: Update to Node.js 20+ or newer versions of Node.js 18.x that resolve the specific breaking changes mentioned (e.g., related to `ts-node` or Web Worker/Fetch API in Node.js). Ensure all dependencies are up to date.
• gotcha The project is currently tagged as 'Experimental' in its README, indicating that while functional, its API or internal workings might undergo significant changes in future versions.
  Fix: Be aware that future major versions might introduce breaking changes. Monitor the GitHub repository for updates and release notes. Consider pinning to minor versions for production until it reaches a stable (non-experimental) status.

Install

• npm install sqlite-wasm-http npm
• yarn add sqlite-wasm-http yarn
• pnpm add sqlite-wasm-http pnpm

Imports

• createSQLiteThread
  wrong:

  const { createSQLiteThread } = require('sqlite-wasm-http');

  correct:

  import { createSQLiteThread } from 'sqlite-wasm-http';

  The library is ES6 module mode only; CommonJS imports will fail. Node.js 18+ is required for runtime features.
• createHttpBackend
  wrong:

  const createHttpBackend = require('sqlite-wasm-http').createHttpBackend;

  correct:

  import { createHttpBackend } from 'sqlite-wasm-http';

  This is a named import from the ESM-only package. Attempting to use CommonJS `require()` will result in an error.
• SQLite.SQLValue

  import type { SQLite } from 'sqlite-wasm-http';
  // ... then use SQLite.SQLValue

  Type imports are standard. The `SQLite` namespace exposes types like `SQLValue` and `SQLBindable` since v1.1.0 for improved TypeScript support.

Quickstart

This quickstart demonstrates how to initialize the HTTP VFS backend and connect to a remote MBTiles database. It then executes a simple query to list tables and count entries at a specific zoom level, showcasing basic database interaction and proper resource cleanup.

import { createSQLiteThread, createHttpBackend } from 'sqlite-wasm-http';

async function runRemoteQuery() {
  const remoteURL = 'https://velivole.b-cdn.net/maptiler-osm-2017-07-03-v3.6.1-europe.mbtiles';
  // createHttpBackend will autodetect if you can use SharedArrayBuffer or not
  const httpBackend = createHttpBackend({
    maxPageSize: 4096,    // This is the current default SQLite page size
    timeout: 10000,       // 10s
    cacheSize: 4096       // 4 MB (corresponds to 4096 pages of 1KB each for default 1024 page_size)
  });

  // Multiple DB workers can be created, all sharing the same backend cache
  const db = await createSQLiteThread({ httpBackend });

  try {
    const results = await db.exec({
      sql: 'SELECT name FROM sqlite_master WHERE type=\'table\';'
    });
    console.log('Tables:', results.results[0].row);

    const countResult = await db.exec({
      sql: 'SELECT count(*) FROM tiles WHERE zoom_level = ?;',
      bind: [1]
    });
    console.log('Tiles at zoom 1:', countResult.results[0].row);
  } finally {
    db.close();
  }
}

runRemoteQuery().catch(console.error);