Common interface for accessing SQL databases from node.js
CoffeeScript JavaScript
Switch branches/tags
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Library that attempts to provide a common interface for SQL databases by wrapping third party drivers with a simple API. Inspired by python's dbapi, java jdbc, etc. So far there's support for sqlite, mysql and postgres. See the end of README for info on how to wrap other drivers.


$ npm install sqli


Acquire a connection:

var sqli = require('sqli')
, sqlite = sqli.getDriver('sqlite')
, conn = sqlite.connect(':memory:');

Connections can also be acquired via pools which are useful in web applications

// max 5 connections, 10 seconds before idle connections will be closed
pool = sqlite.createPool('some.db', 5, 10000);
conn = pool.get();

The pool is implemented using

The API methods always return promises/futures, which will queue statements/callbacks to be executed when appropriate, creating the illusion of synchronous programming style:

conn.exec('CREATE TABLE tags (id TEXT, value TEXT)');
conn.exec('INSERT INTO tags (id, value) VALUES (?, ?)', ['id1', 'value1']);
conn.exec("INSERT INTO tags (id, value) VALUES ('id2', 'value2')");
conn.exec('SELECT * FROM tags').each(function(row) {

Transactions API

conn.exec('INSERT INTO test (id,stringcol) VALUES(?,?)', [1, 'abc']);
conn.exec('INSERT INTO test (id,stringcol) VALUES(?,?)', [2, 'def']);
conn.begin(); // This will disable autocommit
conn.exec('INSERT INTO test (id,stringcol) VALUES(?,?)', [3, 'ghi']);
conn.exec('INSERT INTO test (id,stringcol) VALUES(?,?)', [4, 'jkl']);
conn.commit(); // commits everything since 'begin'
conn.exec('SELECT COUNT(*) FROM test').scalar(function(value) {
  console.log(value); // 4

There's also limited support to isolation levels and savepoints:

conn.exec('INSERT INTO test (id,stringcol) VALUES(?,?)', [1, 'abc']);
conn.exec('INSERT INTO test (id,stringcol) VALUES(?,?)', [2, 'def']);
conn.exec("UPDATE test SET stringcol = 'txt' WHERE id=2");'s1');
conn.exec('DELETE FROM test WHERE id = 1');
conn.exec('SELECT stringcol AS s FROM test').all(function(rows) {
conn.rollback('s1'); // Revert everything since 'save'
conn.exec('SELECT stringcol AS s FROM test').all(function(rows) {
conn.rollback(); // Revert everything done since 'begin'
conn.exec('SELECT stringcol AS s FROM test ORDER BY id').first(function(row) {
  console.log(row.s); // 'abc'

An error handler can be attached invoking 'then' on the result object:

conn.exec('INSERT INTO t1 VALUES (?, ?)', [a1, a2]);
conn.exec('INSERT INTO t2 VALUES (?, ?)', [a1, a2]);
conn.exec('INSERT INTO t3 VALUES (?, ?)', [a1, a2]);
conn.exec('INSERT INTO t4 VALUES (?, ?)', [a1, a2])
.then(function(err) {
  // This handler will be executed after all other statements.
  // If an error ocurred during the execution of any statement,
  // it will be referenced by the 'err' parameter
  if (err) console.log(err);
  else console.log('success');

Errors can also be caught by attaching a handler to the connection object:

conn.error(function(err) {
  // handle the first connection error

After an error ocurrs, the connection will pause, and can be resumed like this:

conn.exec('INSERT INTO t1 VALUES (1, 2)')
conn.exec('INSERT INTO t2 VALUES (3, 4)')
.then(function() {
conn.error(function(err) {
  // lets say an error ocurred in the first statement
  if (err.code = 100) {
    // ignore the error and continue from the second statement
  } else {
    // unexpected error, clear the statement queue
    // the 'true' argument will clear queued statements
    // so you can restart work or do something else

If inside a transaction, it is possible to rollback which will also clear any pending statements:

conn.exec('INSERT INTO t1 VALUES (1, 2)')
conn.exec('INSERT INTO t2 VALUES (3, 4)')
conn.error(function(err) {

Implementing custom drivers:

Here is node-sqlite3 wrapper:

function factory(sqlite3) {
  var sqli = require('./sqli');
  sqli.register('sqlite', {
    connect: function(filename, cb) {
      var db = new sqlite3.Database(filename, function(err) {
        if (err) return cb(err, null);
        cb(null, db);
    close: function(db) {
    execute: function(db, sql, params, rowCb, endCb, errCb) {
      db.each(sql, params, function(err, row) {
        if (err) errCb(err);
        else rowCb(row);
      }, function(err, count) {
        if (err) errCb(err);
        else endCb();
    begin: function(isolation) {
      switch (isolation) {
        case sqli.REPEATABLE_READ:
        case sqli.SERIALIZABLE:
          return 'BEGIN TRANSACTION';
    save: function(savepoint) {
      return 'SAVEPOINT ' + savepoint;
    commit: function() {
      return 'COMMIT';
    rollback: function(savepoint) {
      if (!savepoint)
        return 'ROLLBACK';
      return 'ROLLBACK TO ' + savepoint;

try {
} catch (error) {
  console.log('Could not load sqlite3 wrapper ' + error.message);

If you do implement more wrappers, please send me pull requests :).

There's a generic test suite(test/common.js) that can be used as a quick sanity check.

To run the tests(will only run the tests for the available database systems)

$ npm install -d
$ make test