websql

library2.0.3jsnpmunverified

This `websql` package provides a Node.js implementation of the deprecated WebSQL Database API, leveraging `sqlite3` for its backend operations. It enables developers to run code originally designed for browser-based WebSQL environments within a Node.js context, and also falls back to `window.openDatabase` when used in a browser via bundlers like Browserify or Webpack. The current stable version is 2.0.3, with no explicit release cadence specified, indicating a focus on stability and compatibility rather than active feature development. Its primary differentiator is its strict adherence to the existing WebSQL API as implemented in browsers, acting as a bridge for legacy applications rather than extending the standard. It specifically *does not* aim to invent new APIs, support features like BLOBs or encryption, or enhance WebSQL beyond its original scope, focusing instead on accurate emulation for compatibility.

database

npm install websql

github ↗package ↗

INSTALL

IMPORT

SIG · WEBSQL

websql

databasejavascriptv2.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

openDatabase

✓ import openDatabase from 'websql';

✗ const openDatabase = require('websql').openDatabase;

The primary function for opening a WebSQL database. While the package's README shows CommonJS `require`, modern Node.js and bundlers support ESM `import`.

customOpenDatabase

✓ import customOpenDatabase from 'websql/custom';

✗ const customOpenDatabase = require('websql');

Used to provide a custom `SQLiteDatabase` implementation, allowing you to swap out the default `node-sqlite3` binding for alternatives.

Database

✓ const db = openDatabase('mydb.db', '1.0', 'description', 1);

✗ import { Database } from 'websql';

The actual database instance returned by `openDatabase` is an object that exposes WebSQL transaction methods like `transaction()` and `readTransaction()`. The `Database` class itself is not directly exported for instantiation.

Demonstrates how to open a WebSQL database, create a table, insert data, and query it using the `transaction` API.

import openDatabase from 'websql'; // Or `const openDatabase = require('websql');` for CommonJS async function initializeDatabase() { // Create a SQLite3 database file called 'mydb.db' const db = openDatabase('mydb.db', '1.0', 'My Test Database', 1 * 1024 * 1024); // Size in bytes console.log('Database opened successfully.'); // Perform a transaction to create a table and insert data return new Promise((resolve, reject) => { db.transaction((tx) => { tx.executeSql( 'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER)', [], () => { console.log('Table "users" created or already exists.'); tx.executeSql( 'INSERT INTO users (name, age) VALUES (?, ?)', ['Alice', 30], () => { console.log('Inserted Alice.'); tx.executeSql( 'INSERT INTO users (name, age) VALUES (?, ?)', ['Bob', 24], () => { console.log('Inserted Bob.'); tx.executeSql( 'SELECT * FROM users', [], (_, result) => { console.log('Users:', Array.from(result.rows).map(row => row)); resolve(true); }, (_, error) => { console.error('Error selecting users:', error.message); reject(error); } ); }, (_, error) => { console.error('Error inserting Bob:', error.message); reject(error); } ); }, (_, error) => { console.error('Error inserting Alice:', error.message); reject(error); } ); }, (_, error) => { console.error('Error creating table:', error.message); reject(error); } ); }); }); } initializeDatabase().catch(console.error);

Debug

Known issues

breakingThe underlying WebSQL Database API is a deprecated standard and is not recommended for new development. This library is primarily intended for bridging legacy WebSQL code to Node.js environments.

fix

For new projects, consider modern alternatives like IndexedDB or client-side SQLite libraries that are actively maintained.

affects: >=1.0

gotchaThe `version`, `description`, and `size` parameters in `openDatabase()` are ignored by this library for compatibility reasons. Database versioning and migrations are not supported.

fix

Manage database schema versions and migrations separately in your application logic, or ensure your legacy code does not rely on WebSQL's internal versioning.

affects: >=1.0

gotchaThis library does not extend the WebSQL API with new features such as `BLOB` support, encryption, or database deletion, strictly adhering to the original WebSQL specification.

fix

Do not expect modern SQLite features or extensions. If these are required, `websql` may not be suitable, and a direct `sqlite3` integration might be necessary.

affects: >=1.0

gotchaWhen used in the browser, this library transparently falls back to `window.openDatabase`, meaning its functionality is subject to the browser's native WebSQL support (which is deprecated and often limited to Chrome/Safari).

fix

Ensure target browser environments have WebSQL support if relying on browser fallback. For broader cross-browser compatibility, consider other storage solutions like IndexedDB.

affects: >=1.0

Errors

Common errors & fixes

SQLITE_CANTOPEN: unable to open database file

The Node.js process lacks write permissions to the directory where the database file is being created, or the specified path is invalid.

fix

Ensure the Node.js process has appropriate write permissions to the specified database directory. Use an absolute path or a path relative to the process's working directory, or use `:memory:` for an in-memory database.

TypeError: db.transaction is not a function

The `db` object returned by `openDatabase` might not be correctly initialized, or `openDatabase` failed to return a valid database instance.

fix

Verify that `openDatabase` completed successfully and returned a valid database object. Check for any errors during the `openDatabase` call and ensure you're calling transaction methods on the correctly initialized `db` object.

Error: Cannot find module 'sqlite3'

`node-sqlite3`, the default backend for `websql`, is not installed as a dependency or failed to compile during installation.

fix

Ensure `sqlite3` is installed as a direct dependency: `npm install sqlite3`. If it's a native module compilation issue, verify your environment meets `node-gyp` requirements (e.g., Python, C++ build tools).

Upgrade

Version history

2.0.3latest on npm

Audit

Dependencies

sqlite3requiredBackend database engine for WebSQL operations in Node.js.

Agent activity

22 hits · last 30 days

node