web-sqlite-js

library2.3.0jsnpmunverified

web-sqlite-js v2.3.0 is a persistent, non-blocking SQLite database for the browser using OPFS and Web Workers. It offers type-safe TypeScript APIs, transaction support, schema migrations, and two-tier validation (v2.2.0+). Compared to alternatives like sql.js or sqlocal, it focuses on out-of-the-box persistence and concurrency safety via mutex, with built-in logging and enhanced error messages. Released under MIT license with monthly updates.

database

npm install web-sqlite-js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WEB-SQLITE-JS

web-sqlite-js

databasejavascriptv2.3.0

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.

openDB

✓ import openDB from 'web-sqlite-js'

Default export only; named imports like { openDB } are not supported.

openDB

✓ const openDB = require('web-sqlite-js').default

✗ const openDB = require('web-sqlite-js')

CommonJS users must access the default export via .default.

✓ import openDB from 'web-sqlite-js'; type DB = Awaited<ReturnType<typeof openDB>>

✗ import { DB } from 'web-sqlite-js'

DB type is not exported; infer it from openDB's return type.

Transaction

✓ import type { Transaction } from 'web-sqlite-js'

✗ import { Transaction } from 'web-sqlite-js'

Transaction is a type-only export since v2.0.0; use import type.

Demonstrates opening a database with schema migration, running queries, and using transactions.

import openDB from 'web-sqlite-js'; const db = await openDB({ name: 'myapp', version: 1, migration: (db, oldVersion) => { if (oldVersion < 1) { db.exec('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)'); } } }); // Insert a record await db.run('INSERT INTO users (name) VALUES (?)', ['Alice']); // Query const rows = await db.query('SELECT * FROM users'); console.log(rows); // [{id: 1, name: 'Alice'}] // Transaction await db.transaction(async (tx) => { await tx.run('INSERT INTO users (name) VALUES (?)', ['Bob']); await tx.run('UPDATE users SET name = ? WHERE id = ?', ['Bobby', 2]); }); db.close();

Debug

Known issues

breakingVersion 2.0.0 changed openDB to return a Promise and drop callback support.

fix

Use await openDB(...) instead of openDB(..., callback).

affects: >=2.0.0

gotchaSharedArrayBuffer requires COOP/COEP headers; without them, database operations fail silently.

fix

Set 'Cross-Origin-Opener-Policy: same-origin' and 'Cross-Origin-Embedder-Policy: require-corp' on your server.

affects: >=1.0.0

deprecatedThe 'debug' option (boolean) is deprecated since v2.2.0; use onLog() for structured logging.

fix

Replace `debug: true` with `onLog: (msg) => console.log(msg)`.

affects: >=2.2.0 <3.0.0

gotchaDatabase name changes trigger a full migration re-run, potentially losing data.

fix

Keep database names consistent across app versions, or implement custom migration logic.

affects: >=1.0.0

gotchaweb-sqlite-js does not support concurrent connections to the same database file.

fix

Use a single openDB instance per database; close old connections before opening new ones.

affects: >=1.0.0

Errors

Common errors & fixes

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

CommonJS require() without .default on the default export.

fix

Use const openDB = require('web-sqlite-js').default;

Uncaught (in promise) DOMException: Failed to execute 'open' on 'IDBFactory': The operation is insecure.

Missing COOP/COEP headers required for SharedArrayBuffer.

fix

Add Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp headers.

TypeError: openDB is not a function

Named import instead of default import.

fix

Change to import openDB from 'web-sqlite-js' (no curly braces).

Error: Migration version 1 is less than current database schema version 2

Attempting to open a database with an older version after a migration.

fix

Always increment version and provide appropriate migration logic for each upgrade.

Upgrade

Version history

2.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

21 hits · last 30 days

node