websql

node-websql

The WebSQL Database API, implemented for Node using sqlite3.

Install

npm install websql

Usage

var openDatabase = require('websql');

Create a SQLite3 database called mydb.db:

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

Create an in-memory database:

var db = openDatabase(':memory:', '1.0', 'description', 1);

API

openDatabase(name, version, description, size [, callback])

The name is the name of the database. It's passed verbatim to sqlite3.

The version is the database version (currently ignored - see below).

The description and size attributes are ignored, but they are required for compatibility with the WebSQL API.

The callback just returns the same database object returned synchronously (migrations currently aren't supported - see below).

For more information how to use the WebSQL API, see the spec or various tutorials.

For more information on sqlite3, see the SQLite3 readme.

Custom sqlite3 implementation

If you'd like to use your own sqlite3 implementation, just do:

var customOpenDatabase = require('websql/custom');
var openDatabase = customOpenDatabase(mySqlite3);

Your responsibility as a developer is to implement the subset of the sqlite3 API which this module uses. At this time, that means the db.all() and db.run() methods. See the sqlite3 docs for more info.

In the browser

You can also use this module in the browser (via Browserify/Webpack/etc.), in which case it will just use window.openDatabase, meaning you are subject to browser WebSQL support.

Goals

The WebSQL Database API is a deprecated standard, but in many cases it's useful to reuse legacy code designed for browsers that support WebSQL. Also, it allows you to quickly test WebSQL-based code in Node, which can be convenient.

The goal of this API is to exactly match the existing WebSQL API, as implemented in browsers. If there's any difference between browsers (e.g. rows[0] is supported in Chrome, whereas only rows.item(0) is supported in Safari), then the lowest-common denominator version is exported by this library.

This library has a robust test suite, and has been known to pass the PouchDB test suite as well.

Non-Goals

This library is not designed to:

• Invent new APIs, e.g. deleting databases, supporting BLOBs, encryption, etc.
• Support WebSQL in Firefox, IE, or other non-WebSQL browsers

In other words, the goal is not to carry the torch of WebSQL, but rather to bridge the gap from existing WebSQL-based code to Node.js.

TODOs

The versioning and migration APIs (i.e. changeVersion()) are not supported. Pull requests welcome!

Testing

First:

npm install

Main test suite:

npm test

Linter:

npm run lint

Test in debug mode (e.g. with the node-inspector):

npm run test-debug

Run the test suite against actual WebSQL in a browser:

npm run test-local

Run the actual-WebSQL test against PhantomJS:

npm run test-phantom