WebSQL API for Node.js (Configurable)

Common errors

• TypeError: openDatabase is not a function

  cause 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"

  cause 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.

  cause 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.

  cause 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.

Warnings

• deprecated The 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).
• gotcha The `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.
• gotcha This 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.
• gotcha When 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.
• gotcha The 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.

Install

• npm install websql-configurable npm
• yarn add websql-configurable yarn
• pnpm add websql-configurable pnpm

Imports

• openDatabase
  wrong:

  const openDatabase = require('websql-configurable');

  correct:

  import openDatabase from '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
  wrong:

  const customOpenDatabase = require('websql-configurable/custom');

  correct:

  import { customOpenDatabase } from '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.

Quickstart

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.');
});