{"id":16581,"library":"websql","title":"WebSQL API Implementation for Node.js","description":"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.","status":"maintenance","version":"2.0.3","language":"javascript","source_language":"en","source_url":"git://github.com/nolanlawson/node-websql","tags":["javascript","websql","sql","opendatabase","sqlite","storage","sqlite3","database"],"install":[{"cmd":"npm install websql","lang":"bash","label":"npm"},{"cmd":"yarn add websql","lang":"bash","label":"yarn"},{"cmd":"pnpm add websql","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Backend database engine for WebSQL operations in Node.js.","package":"sqlite3","optional":false}],"imports":[{"note":"The primary function for opening a WebSQL database. While the package's README shows CommonJS `require`, modern Node.js and bundlers support ESM `import`.","wrong":"const openDatabase = require('websql').openDatabase;","symbol":"openDatabase","correct":"import openDatabase from 'websql';"},{"note":"Used to provide a custom `SQLiteDatabase` implementation, allowing you to swap out the default `node-sqlite3` binding for alternatives.","wrong":"const customOpenDatabase = require('websql');","symbol":"customOpenDatabase","correct":"import customOpenDatabase from 'websql/custom';"},{"note":"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.","wrong":"import { Database } from 'websql';","symbol":"Database","correct":"const db = openDatabase('mydb.db', '1.0', 'description', 1);"}],"quickstart":{"code":"import openDatabase from 'websql'; // Or `const openDatabase = require('websql');` for CommonJS\n\nasync function initializeDatabase() {\n  // Create a SQLite3 database file called 'mydb.db'\n  const db = openDatabase('mydb.db', '1.0', 'My Test Database', 1 * 1024 * 1024); // Size in bytes\n\n  console.log('Database opened successfully.');\n\n  // Perform a transaction to create a table and insert data\n  return new Promise((resolve, reject) => {\n    db.transaction((tx) => {\n      tx.executeSql(\n        'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER)',\n        [],\n        () => {\n          console.log('Table \"users\" created or already exists.');\n          tx.executeSql(\n            'INSERT INTO users (name, age) VALUES (?, ?)',\n            ['Alice', 30],\n            () => {\n              console.log('Inserted Alice.');\n              tx.executeSql(\n                'INSERT INTO users (name, age) VALUES (?, ?)',\n                ['Bob', 24],\n                () => {\n                  console.log('Inserted Bob.');\n                  tx.executeSql(\n                    'SELECT * FROM users',\n                    [],\n                    (_, result) => {\n                      console.log('Users:', Array.from(result.rows).map(row => row));\n                      resolve(true);\n                    },\n                    (_, error) => {\n                      console.error('Error selecting users:', error.message);\n                      reject(error);\n                    }\n                  );\n                },\n                (_, error) => {\n                  console.error('Error inserting Bob:', error.message);\n                  reject(error);\n                }\n              );\n            },\n            (_, error) => {\n              console.error('Error inserting Alice:', error.message);\n              reject(error);\n            }\n          );\n        },\n        (_, error) => {\n          console.error('Error creating table:', error.message);\n          reject(error);\n        }\n      );\n    });\n  });\n}\n\ninitializeDatabase().catch(console.error);","lang":"typescript","description":"Demonstrates how to open a WebSQL database, create a table, insert data, and query it using the `transaction` API."},"warnings":[{"fix":"For new projects, consider modern alternatives like IndexedDB or client-side SQLite libraries that are actively maintained.","message":"The 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.","severity":"breaking","affected_versions":">=1.0"},{"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.","message":"The `version`, `description`, and `size` parameters in `openDatabase()` are ignored by this library for compatibility reasons. Database versioning and migrations are not supported.","severity":"gotcha","affected_versions":">=1.0"},{"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.","message":"This 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.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Ensure target browser environments have WebSQL support if relying on browser fallback. For broader cross-browser compatibility, consider other storage solutions like IndexedDB.","message":"When 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).","severity":"gotcha","affected_versions":">=1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The Node.js process lacks write permissions to the directory where the database file is being created, or the specified path is invalid.","error":"SQLITE_CANTOPEN: unable to open database file"},{"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.","cause":"The `db` object returned by `openDatabase` might not be correctly initialized, or `openDatabase` failed to return a valid database instance.","error":"TypeError: db.transaction is not a function"},{"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).","cause":"`node-sqlite3`, the default backend for `websql`, is not installed as a dependency or failed to compile during installation.","error":"Error: Cannot find module 'sqlite3'"}],"ecosystem":"npm"}