Registry / database / websql-configurable

websql-configurable

JSON →
library3.0.3jsnpmunverified

websql-configurable is a JavaScript/TypeScript library (version 3.0.3) that implements the WebSQL Database API for Node.js environments, leveraging `node-sqlite3` as its backend. It is a fork of `node-websql` which provides additional configuration options and incorporates TypeScript types from `@types/websql`. This package allows developers to reuse legacy WebSQL-based code in Node.js, facilitating quick testing and bridging existing WebSQL implementations to a Node.js context. When used in a browser environment via bundlers like Browserify or Webpack, it gracefully falls back to the native `window.openDatabase` implementation, subject to current browser support. The library aims for strict compatibility with the existing WebSQL API as found in browsers, focusing on bridging the gap rather than expanding the deprecated standard. Its release cadence is primarily driven by maintenance needs and fixes for its specific niche. A key differentiator is its enhanced configurability for the underlying `sqlite3` driver and the ability to swap custom SQLite3 implementations.

npm install websql-configurable
INSTALL
IMPORT
SIG · WEBSQL-CONFIGURABL
W
websql-configurable
databasejavascriptv3.0.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

openDatabase
import openDatabase from 'websql-configurable';
const openDatabase = require('websql-configurable');
This is the default export and primary function for opening a WebSQL-compatible database. While `require` works for CommonJS, modern Node.js and TypeScript projects should prefer the ESM `import` syntax.
customOpenDatabase
import { customOpenDatabase } from 'websql-configurable/custom';
const customOpenDatabase = require('websql-configurable/custom');
This function is a named export from a subpath and allows advanced users to provide their own custom SQLite3 database implementation. It is used for swappable backends beyond the default `node-sqlite3`.
Database
import type { Database } from 'websql-configurable';
This imports the TypeScript type definition for the `Database` object returned by `openDatabase`, useful for type-checking when working with TypeScript.

This quickstart demonstrates how to open a file-based or in-memory WebSQL database in Node.js, create a table, insert data, and query it within a transaction using the `websql-configurable` API.

import openDatabase from 'websql-configurable'; // Create a file-based SQLite3 database named 'mydb.db' const db = openDatabase('mydb.db', '1.0', 'My WebSQL Database', 1024 * 1024); // Alternatively, create an in-memory database that is temporary const inMemoryDb = openDatabase(':memory:', '1.0', 'In-memory DB', 1); console.log('Database opened (or created):', db); db.transaction((tx) => { tx.executeSql( 'CREATE TABLE IF NOT EXISTS items (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, quantity INTEGER)', [], () => console.log('Table "items" created or already exists.'), (tx, error) => console.error('Error creating table:', error.message) ); tx.executeSql( 'INSERT INTO items (name, quantity) VALUES (?, ?)', ['Apple', 5], () => console.log('Inserted: Apple'), (tx, error) => console.error('Error inserting Apple:', error.message) ); tx.executeSql( 'INSERT INTO items (name, quantity) VALUES (?, ?)', ['Orange', 3], () => console.log('Inserted: Orange'), (tx, error) => console.error('Error inserting Orange:', error.message) ); tx.executeSql( 'SELECT * FROM items WHERE quantity > ?', [4], (tx, results) => { console.log('Items with quantity > 4:'); for (let i = 0; i < results.rows.length; i++) { console.log(` ID: ${results.rows.item(i).id}, Name: ${results.rows.item(i).name}, Quantity: ${results.rows.item(i).quantity}`); } }, (tx, error) => console.error('Error selecting items:', error.message) ); }, (error) => { console.error('Transaction failed:', error.message); }, () => { console.log('Transaction completed successfully.'); });
Debug
Known issues
deprecatedThe underlying WebSQL Database API is a deprecated W3C standard. This library is intended for bridging legacy code and is not recommended for new projects that require long-term, modern database solutions.
fix
For new projects, consider modern alternatives like IndexedDB (for browsers) or standalone SQLite/PostgreSQL/MySQL libraries (for Node.js).
affects: >=1.0.0
gotchaThe `version`, `description`, and `size` parameters of the `openDatabase` function are largely ignored for functional purposes, though they are required for WebSQL API compatibility. Database migrations based on version changes are not supported.
fix
Do not rely on `version` for schema management. Implement schema updates manually as part of your application logic.
affects: >=1.0.0
gotchaThis library does not extend the WebSQL API to include SQLite-specific features like deleting databases, supporting `BLOB` types directly, encryption, or advanced PRAGMA statements. Attempts to use non-standard WebSQL SQL features may result in errors.
fix
Adhere strictly to the WebSQL API standard SQL subset. If advanced SQLite features are needed, consider using `node-sqlite3` directly or another dedicated database driver.
affects: >=1.0.0
gotchaWhen used in a browser, this library transparently falls back to `window.openDatabase`. This means its functionality is entirely dependent on the browser's native WebSQL support, which is deprecated and varies between browsers (e.g., Chrome-only for modern usage).
fix
Thoroughly test browser compatibility if targeting the browser. For robust browser storage, consider IndexedDB or local storage solutions.
affects: >=1.0.0
gotchaThe library normalizes behavior to the 'lowest-common denominator' when there are differences in WebSQL implementations (e.g., `rows[0]` vs `rows.item(0)`). Always use `rows.item(index)` for accessing result set rows to ensure maximum compatibility.
fix
Always use `results.rows.item(i)` to access individual rows within a `SQLResultSetRowList` to guarantee consistent behavior across environments.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: openDatabase is not a function
Incorrect import syntax (e.g., using CommonJS `require` in an ESM context, or a wrong path) for `openDatabase`.
fix
Ensure you are using `import openDatabase from 'websql-configurable';` for ESM/TypeScript projects. If using CommonJS, `const openDatabase = require('websql-configurable');` is correct.
Error: SQLITE_ERROR: unrecognized token: "BLOB"
Attempting to use SQLite-specific data types (like `BLOB`) or non-standard SQL keywords/functions not part of the core WebSQL API.
fix
Restrict SQL statements to the WebSQL standard. For binary data, consider storing it as `TEXT` (Base64 encoded) or as `INTEGER` (if referencing an external binary store).
Error: Database operations are not reflecting expected schema changes.
Reliance on the `version` parameter in `openDatabase` for automatic database migrations, which `websql-configurable` explicitly does not support.
fix
Implement database schema migration logic manually within your application. The `version` parameter is ignored by this library for functional purposes.
DOMException: Failed to execute 'openDatabase' on 'Window': The operation is not supported.
Running `websql-configurable` in a browser that does not support the native WebSQL API (e.g., Firefox, Edge, Safari in some configurations) when bundled for the client.
fix
Ensure your target browser environment supports `window.openDatabase` (primarily Chrome, or older versions of other browsers). For broader browser compatibility, consider switching to IndexedDB or other web storage APIs for new development.
Upgrade
Version history
3.0.3latest on npm
Audit
Dependencies
sqlite3requiredRequired for database operations in Node.js environments.
Agent activity
25 hits · last 30 days
node
22
OpenAI (training)
1
Resources
websql-configurable — npm install websql-configurable · libregistry