{"id":16580,"library":"websql-configurable","title":"WebSQL API for Node.js (Configurable)","description":"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.","status":"active","version":"3.0.3","language":"javascript","source_language":"en","source_url":"git://github.com/brettz9/node-websql","tags":["javascript","websql","sql","opendatabase","sqlite","storage","sqlite3","database","typescript"],"install":[{"cmd":"npm install websql-configurable","lang":"bash","label":"npm"},{"cmd":"yarn add websql-configurable","lang":"bash","label":"yarn"},{"cmd":"pnpm add websql-configurable","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for database operations in Node.js environments.","package":"sqlite3","optional":false}],"imports":[{"note":"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.","wrong":"const openDatabase = require('websql-configurable');","symbol":"openDatabase","correct":"import openDatabase from 'websql-configurable';"},{"note":"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`.","wrong":"const customOpenDatabase = require('websql-configurable/custom');","symbol":"customOpenDatabase","correct":"import { customOpenDatabase } from 'websql-configurable/custom';"},{"note":"This imports the TypeScript type definition for the `Database` object returned by `openDatabase`, useful for type-checking when working with TypeScript.","symbol":"Database","correct":"import type { Database } from 'websql-configurable';"}],"quickstart":{"code":"import openDatabase from 'websql-configurable';\n\n// Create a file-based SQLite3 database named 'mydb.db'\nconst db = openDatabase('mydb.db', '1.0', 'My WebSQL Database', 1024 * 1024);\n\n// Alternatively, create an in-memory database that is temporary\nconst inMemoryDb = openDatabase(':memory:', '1.0', 'In-memory DB', 1);\n\nconsole.log('Database opened (or created):', db);\n\ndb.transaction((tx) => {\n  tx.executeSql(\n    'CREATE TABLE IF NOT EXISTS items (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, quantity INTEGER)',\n    [],\n    () => console.log('Table \"items\" created or already exists.'),\n    (tx, error) => console.error('Error creating table:', error.message)\n  );\n\n  tx.executeSql(\n    'INSERT INTO items (name, quantity) VALUES (?, ?)',\n    ['Apple', 5],\n    () => console.log('Inserted: Apple'),\n    (tx, error) => console.error('Error inserting Apple:', error.message)\n  );\n\n  tx.executeSql(\n    'INSERT INTO items (name, quantity) VALUES (?, ?)',\n    ['Orange', 3],\n    () => console.log('Inserted: Orange'),\n    (tx, error) => console.error('Error inserting Orange:', error.message)\n  );\n\n  tx.executeSql(\n    'SELECT * FROM items WHERE quantity > ?', [4],\n    (tx, results) => {\n      console.log('Items with quantity > 4:');\n      for (let i = 0; i < results.rows.length; i++) {\n        console.log(`  ID: ${results.rows.item(i).id}, Name: ${results.rows.item(i).name}, Quantity: ${results.rows.item(i).quantity}`);\n      }\n    },\n    (tx, error) => console.error('Error selecting items:', error.message)\n  );\n}, (error) => {\n  console.error('Transaction failed:', error.message);\n}, () => {\n  console.log('Transaction completed successfully.');\n});\n","lang":"typescript","description":"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."},"warnings":[{"fix":"For new projects, consider modern alternatives like IndexedDB (for browsers) or standalone SQLite/PostgreSQL/MySQL libraries (for Node.js).","message":"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.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Do not rely on `version` for schema management. Implement schema updates manually as part of your application logic.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Thoroughly test browser compatibility if targeting the browser. For robust browser storage, consider IndexedDB or local storage solutions.","message":"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).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use `results.rows.item(i)` to access individual rows within a `SQLResultSetRowList` to guarantee consistent behavior across environments.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure you are using `import openDatabase from 'websql-configurable';` for ESM/TypeScript projects. If using CommonJS, `const openDatabase = require('websql-configurable');` is correct.","cause":"Incorrect import syntax (e.g., using CommonJS `require` in an ESM context, or a wrong path) for `openDatabase`.","error":"TypeError: openDatabase is not a function"},{"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).","cause":"Attempting to use SQLite-specific data types (like `BLOB`) or non-standard SQL keywords/functions not part of the core WebSQL API.","error":"Error: SQLITE_ERROR: unrecognized token: \"BLOB\""},{"fix":"Implement database schema migration logic manually within your application. The `version` parameter is ignored by this library for functional purposes.","cause":"Reliance on the `version` parameter in `openDatabase` for automatic database migrations, which `websql-configurable` explicitly does not support.","error":"Error: Database operations are not reflecting expected schema changes."},{"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.","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.","error":"DOMException: Failed to execute 'openDatabase' on 'Window': The operation is not supported."}],"ecosystem":"npm"}