Skip to content

README.md

Latest commit

 

History

History
94 lines (68 loc) · 3.62 KB

README.md

File metadata and controls

94 lines (68 loc) · 3.62 KB
Raw

@objectstack/driver-sqlite-wasm

SQLite-on-WASM driver for ObjectStack. Runs the same SqlDriver codepath as @objectstack/driver-sqlite but swaps the native better-sqlite3 N-API binding for sql.js (SQLite compiled to WebAssembly), so it works in environments where native modules are unavailable — most notably StackBlitz WebContainer (Node-in-browser).

  • Plugin ID: com.objectstack.driver.sqlite-wasm
  • Strategy: subclass SqlDriver + custom Knex dialect; no fork of upstream logic.
  • Persistence: sql.js db.export() bytes → Node fs (node:fs/promises).

When to use

Driver Backend Runs in WebContainer Native binary
@objectstack/driver-sqlite better-sqlite3 ❌ yes
@objectstack/driver-sqlite-wasm sql.js (WASM) ✅ no
@objectstack/driver-postgres pg ✅ (with TCP) no

Pick the WASM driver when you need a zero-binary SQLite that boots in the browser sandbox, in serverless edge runtimes that expose Node fs, or in CI environments where building better-sqlite3 against the host Node is painful. For production servers, prefer the native driver.

Install

pnpm add @objectstack/driver-sqlite-wasm

Quick start

import { SqliteWasmDriver } from '@objectstack/driver-sqlite-wasm';

const driver = new SqliteWasmDriver({
  filename: './data/app.db',
  persist: 'on-disconnect', // default
});

await driver.connect();

await driver.create('users', { name: 'Alice', age: 30 });
const rows = await driver.find('users', { where: { age: { $gt: 18 } } });

await driver.disconnect(); // flushes pending writes to disk

Use :memory: (or any :... filename) for an ephemeral database that lives only for the process.

Persistence modes

sql.js holds the entire database in memory; mutations only reach disk when the driver calls db.export() and writes the resulting bytes. Pick the strategy that matches your write pattern:

persist Behavior Use when
'on-disconnect' (default) Flush once at disconnect() (and on process.beforeExit). Batch jobs, short-lived processes, write-heavy migrations.
'on-write' Flush after every mutation. Safest. Few writes per second.
`debounced:${ms}` Flush at most once per N ms after the last write. Bursty writes; balance durability vs throughput.

Call await driver.flush() at any time to force a synchronous flush.

In environments without node:fs/promises (pure browser), the driver logs a warning and falls back to in-memory only — data is not persisted across reloads.

Architecture

SqlDriver  ──► Knex  ──► Client_WasmSqlite  ──► WasmSqliteConnection  ──► sql.js  ──► fs
(unchanged)                  (custom dialect)         (sqlite-wasm-driver/src)
  • Client_WasmSqlite extends Knex's upstream Client_SQLite3, so the SQLite query compiler, schema builder, and column compiler are reused as-is. Only _driver, acquireRawConnection, destroyRawConnection, and _query are overridden.
  • WasmSqliteConnection wraps sql.js's Database with the prepare/exec/run/close subset Knex needs, plus persistence orchestration.
  • SqliteWasmDriver is a thin SqlDriver subclass that forces isSqlite to true (the base class string-matches config.client; we pass a class) and wires process.beforeExit to a best-effort flush.

Pool

sql.js is single-threaded; the dialect defaults to { min: 1, max: 1 }. Don't raise max — concurrent access would corrupt the in-memory database handle.

License

Apache-2.0. See LICENSING.md.