{"id":17367,"library":"sqlite-wasm-http","title":"SQLite WASM HTTP VFS Backend","description":"sqlite-wasm-http provides an HTTP Virtual File System (VFS) backend for the official SQLite WASM distribution, enabling direct querying of remote SQLite databases over HTTP. It is designed to be a robust solution for browser and Node.js environments (Node.js 18+ required for full functionality) and supports features like multiple concurrent connections with shared caching (requiring `SharedArrayBuffer` and COOP/COEP headers) or a simplified fall-back without it. The library is currently at v1.2.0 and appears to have a semi-regular release cadence, with updates often tied to new official SQLite WASM builds or bug fixes. A key differentiator is its focus on the official SQLite WASM distribution, aiming to be an industry reference, and its support for shared cache across workers, offering performance benefits over similar solutions.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/mmomtchev/sqlite-wasm-http","tags":["javascript","sqlite","http","vfs","typescript"],"install":[{"cmd":"npm install sqlite-wasm-http","lang":"bash","label":"npm"},{"cmd":"yarn add sqlite-wasm-http","lang":"bash","label":"yarn"},{"cmd":"pnpm add sqlite-wasm-http","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library is ES6 module mode only; CommonJS imports will fail. Node.js 18+ is required for runtime features.","wrong":"const { createSQLiteThread } = require('sqlite-wasm-http');","symbol":"createSQLiteThread","correct":"import { createSQLiteThread } from 'sqlite-wasm-http';"},{"note":"This is a named import from the ESM-only package. Attempting to use CommonJS `require()` will result in an error.","wrong":"const createHttpBackend = require('sqlite-wasm-http').createHttpBackend;","symbol":"createHttpBackend","correct":"import { createHttpBackend } from 'sqlite-wasm-http';"},{"note":"Type imports are standard. The `SQLite` namespace exposes types like `SQLValue` and `SQLBindable` since v1.1.0 for improved TypeScript support.","symbol":"SQLite.SQLValue","correct":"import type { SQLite } from 'sqlite-wasm-http';\n// ... then use SQLite.SQLValue"}],"quickstart":{"code":"import { createSQLiteThread, createHttpBackend } from 'sqlite-wasm-http';\n\nasync function runRemoteQuery() {\n  const remoteURL = 'https://velivole.b-cdn.net/maptiler-osm-2017-07-03-v3.6.1-europe.mbtiles';\n  // createHttpBackend will autodetect if you can use SharedArrayBuffer or not\n  const httpBackend = createHttpBackend({\n    maxPageSize: 4096,    // This is the current default SQLite page size\n    timeout: 10000,       // 10s\n    cacheSize: 4096       // 4 MB (corresponds to 4096 pages of 1KB each for default 1024 page_size)\n  });\n\n  // Multiple DB workers can be created, all sharing the same backend cache\n  const db = await createSQLiteThread({ httpBackend });\n\n  try {\n    const results = await db.exec({\n      sql: 'SELECT name FROM sqlite_master WHERE type=\\'table\\';'\n    });\n    console.log('Tables:', results.results[0].row);\n\n    const countResult = await db.exec({\n      sql: 'SELECT count(*) FROM tiles WHERE zoom_level = ?;',\n      bind: [1]\n    });\n    console.log('Tiles at zoom 1:', countResult.results[0].row);\n  } finally {\n    db.close();\n  }\n}\n\nrunRemoteQuery().catch(console.error);","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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');`.","message":"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;`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.2.0 (integration tests affected), possibly earlier Node.js 18.x users"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","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.","error":"ReferenceError: SharedArrayBuffer is not defined"},{"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`.","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.","error":"TypeError: require is not a function"},{"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.","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.","error":"Error: Unknown module: sqlite3-worker1-promiser-node.mjs"}],"ecosystem":"npm","meta_description":null}