absurd-sql

library0.0.54jsnpmunverified

absurd-sql (v0.0.54) is a backend for sql.js that stores SQLite databases in IndexedDB, enabling persistent SQLite storage in the browser with incremental block-level reads/writes rather than full database blobs. It uses SharedArrayBuffer and Atomics for high performance, consistently beating raw IndexedDB by up to 10x. Released as an experimental/absurd project by James Long, with sporadic updates. Key differentiators: true persistence without full DB reload, support for fallback mode without SharedArrayBuffer (Safari), and requiring a worker thread. Not for production use; primarily a proof-of-concept.

database

npm install absurd-sql

package ↗

INSTALL

IMPORT

SIG · ABSURD-SQL

absurd-sql

databasejavascriptv0.0.54

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.

initBackend

✓ import { initBackend } from 'absurd-sql/dist/indexeddb-main-thread';

✗ import { initBackend } from 'absurd-sql'; // wrong path

Must import from the specific subpath for main thread; worker-side imports are different

SQLiteFS

✓ import { SQLiteFS } from 'absurd-sql';

✗ const { SQLiteFS } = require('absurd-sql'); // CJS require won't work; this is ESM

ESM-only; CJS require will fail.

IndexedDBBackend

✓ import IndexedDBBackend from 'absurd-sql/dist/indexeddb-backend';

✗ import { IndexedDBBackend } from 'absurd-sql'; // wrong export; it's a default export

Default export from subpath; named import will get undefined at runtime.

Sets up absurd-sql with a worker, mounts SQLite filesystem on IndexedDB, opens a database, and applies recommended PRAGMA.

// Main thread import { initBackend } from 'absurd-sql/dist/indexeddb-main-thread'; function init() { let worker = new Worker(new URL('./index.worker.js', import.meta.url)); initBackend(worker); } init(); // Worker (index.worker.js) import initSqlJs from '@jlongster/sql.js'; import { SQLiteFS } from 'absurd-sql'; import IndexedDBBackend from 'absurd-sql/dist/indexeddb-backend'; async function run() { let SQL = await initSqlJs({ locateFile: file => file }); let sqlFS = new SQLiteFS(SQL.FS, new IndexedDBBackend()); SQL.register_for_idb(sqlFS); SQL.FS.mkdir('/sql'); SQL.FS.mount(sqlFS, {}, '/sql'); const path = '/sql/db.sqlite'; if (typeof SharedArrayBuffer === 'undefined') { let stream = SQL.FS.open(path, 'a+'); await stream.node.contents.readIfFallback(); SQL.FS.close(stream); } let db = new SQL.Database(path, { filename: true }); db.exec(`PRAGMA journal_mode=MEMORY;`); // Your code } run();

Debug

Known issues

breakingRequires SharedArrayBuffer. Must serve with Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp headers.

fix

Configure server to send the required COOP/COEP headers. Without these, SharedArrayBuffer is unavailable and the library may fall back or fail.

affects: >=0.0.1

gotchaMust run inside a Web Worker; main thread usage will throw or silently fail.

fix

Always create a Worker and run all SQLite operations inside it.

affects: >=0.0.1

deprecatedUses @jlongster/sql.js fork; official sql.js may not have the required internal hooks (register_for_idb).

fix

Install @jlongster/sql.js instead of regular sql.js, or verify compatibility with your sql.js version.

affects: >=0.0.1

gotchaFallback mode (no SharedArrayBuffer) only works in single-tab scenarios; concurrent writes throw an error.

fix

Implement a custom handler to notify users or prevent multiple tabs from writing simultaneously.

affects: >=0.0.1

gotchaSQLite journal_mode must be set to MEMORY; default DELETE mode may cause data loss or corruption.

fix

Always execute PRAGMA journal_mode=MEMORY after opening the database.

affects: >=0.0.1

Errors

Common errors & fixes

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

Attempting fallback read without checking for SharedArrayBuffer support.

fix

Wrap fallback code in `if (typeof SharedArrayBuffer === 'undefined') { ... }`.

Error: SharedArrayBuffer is not defined

Server missing COOP/COEP headers or code not running in a secure context.

fix

Ensure server sends Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp headers. Also must be served over HTTPS or localhost.

Module not found: Error: Can't resolve 'absurd-sql/dist/indexeddb-main-thread'

Import path is wrong or package not installed correctly.

fix

Install 'absurd-sql' and use the correct subpath import: 'absurd-sql/dist/indexeddb-main-thread'.

Upgrade

Version history

0.0.54latest on npm

Audit

Dependencies

@jlongster/sql.jsoptionalFork of sql.js needed for absurd-sql integration; official sql.js may not work

Agent activity

44 hits · last 30 days

node

OpenAI (training)

Resources

packageabsurd-sql ↗