sql.js-httpvfs

library0.8.12jsnpmunverified

sql.js-httpvfs (v0.8.12) is a read-only HTTP-Range-request based virtual file system for SQLite in the browser. It wraps sql.js to allow querying SQLite databases hosted on static file hosts without full download. Key differentiators: enables client-side SQL queries on large databases with lazy loading via HTTP range requests, includes a DOM virtual table proof-of-concept, and supports splitting databases into chunks for CDN caching. Works well with proper indexing and page size tuning. Low release cadence; last update was 2024.

database

npm install sql.js-httpvfs

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQL.JS-HTTPVFS

sql.js-httpvfs

databasejavascriptv0.8.12

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createDbWorker

✓ import { createDbWorker } from 'sql.js-httpvfs'

✗ const createDbWorker = require('sql.js-httpvfs').createDbWorker

ESM-only; CommonJS require works but may have issues with default exports. Use named import for tree shaking.

default

✓ import sqlJsHttpVfs from 'sql.js-httpvfs'

✗ const sqlJsHttpVfs = require('sql.js-httpvfs')

Default export is the module itself; named exports are preferred. Use createDbWorker directly.

type ImportedConfig

✓ import type { ImportedConfig } from 'sql.js-httpvfs'

TypeScript users should import types separately; ImportedConfig defines the config shape.

type Config

✓ import type { Config } from 'sql.js-httpvfs'

Config is an alias for the inline configuration object; use for type checking.

Initialize a worker with an inline config pointing to a SQLite file, then run a parameterized SELECT query.

import { createDbWorker } from 'sql.js-httpvfs'; const workerUrl = new URL('sql.js-httpvfs/dist/sqlite.worker.js', import.meta.url); const wasmUrl = new URL('sql.js-httpvfs/dist/sql-wasm.wasm', import.meta.url); const config = { from: 'inline', config: { serverMode: 'full', requestChunkSize: 4096, url: '/foo/bar/test.sqlite3' } }; let maxBytesToRead = 10 * 1024 * 1024; const worker = await createDbWorker( [config], workerUrl.toString(), wasmUrl.toString(), maxBytesToRead ); const result = await worker.db.exec('SELECT * FROM table WHERE id = ?', [123]); console.log(result);

Debug

Known issues

gotchaWorker and WASM URLs must be resolved at build time. Using relative paths may fail in production if bundler doesn't copy assets.

fix

Use new URL() with import.meta.url or configure bundler to include sql.js-httpvfs/dist/* files.

affects: >=0.1.0

gotchaDatabase must be structured for range requests: use page_size=1024 and proper indexes. Without optimization, performance is poor.

fix

Run PRAGMA page_size=1024; VACUUM; on your SQLite database before hosting.

affects: >=0.1.0

gotchamaxBytesToRead limits total bytes fetched. If set too low (e.g., <10MB), queries may fail with 'out of memory' or incomplete data.

fix

Set maxBytesToRead to at least 10MB or Infinity for full database access.

affects: >=0.1.0

breakingIn v0.8.0, the config object format changed. 'from' field now expects 'inline' or 'jsonconfig' instead of direct url.

fix

Update config to use { from: 'inline', config: { ... } } instead of passing url directly.

affects: >=0.8.0

deprecatedcreateDbWorker's signature changed: third argument (wasmUrl) is now required; previously it was optional and defaulted to a bundled path.

fix

Always pass wasmUrl.toString() as third argument.

affects: <0.8.0

gotchaIf using with a bundler that doesn't support import.meta.url (e.g., older webpack), worker/wasm URLs may be undefined.

fix

Use file-loader or copy-webpack-plugin to manually copy dist files and reference them with a string URL.

affects: >=0.1.0

Errors

Common errors & fixes

Uncaught (in promise) ReferenceError: createDbWorker is not defined

Wrong import syntax or bundler not resolving named export.

fix

Use `import { createDbWorker } from 'sql.js-httpvfs'` (ESM) or ensure bundler is configured for ES modules.

TypeError: Cannot read properties of undefined (reading 'exec')

Worker not fully initialized or db property accessed before promise resolves.

fix

Await the createDbWorker promise: `const worker = await createDbWorker(...)`.

Failed to load wasm: Response has unsupported MIME type

WASM file served with incorrect MIME type (e.g., application/octet-stream).

fix

Configure server to serve .wasm files with MIME type application/wasm or set Content-Type header.

Access to XMLHttpRequest at 'http://...' from origin 'null' has been blocked by CORS policy

Database file hosted on a different origin without CORS headers.

fix

Add CORS headers to the server hosting the SQLite file, or serve it from the same origin.

Upgrade

Version history

0.8.12latest on npm

Audit

Dependencies

sql.jsrequiredCore SQLite compilation via Emscripten; sql.js-httpvfs is a wrapper around it.

Agent activity

18 hits · last 30 days

node