willcode2surf / node-sqli

Common interface for accessing SQL databases from node.js

node-sqli

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.

Instalation

$ npm install sqli

Usage

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 https://github.com/coopernurse/node-pool.

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) {
  console.log(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.begin(sqli.SERIALIZABLE);
conn.exec("UPDATE test SET stringcol = 'txt' WHERE id=2");
conn.save('s1');
conn.exec('DELETE FROM test WHERE id = 1');
conn.exec('SELECT stringcol AS s FROM test').all(function(rows) {
  console.log(rows);
});
conn.rollback('s1'); // Revert everything since 'save'
conn.exec('SELECT stringcol AS s FROM test').all(function(rows) {
  console.log(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() {
  console.log('success');
})
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
    conn.resume();
  } else {
    // unexpected error, clear the statement queue
    conn.resume(true);
    // 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.begin();
conn.exec('INSERT INTO t1 VALUES (1, 2)')
conn.exec('INSERT INTO t2 VALUES (3, 4)')
conn.error(function(err) {
  conn.rollback();
})
conn.commit();

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) {
      db.close();
    },
    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:
          return 'BEGIN IMMEDIATE TRANSACTION';
        case sqli.SERIALIZABLE:
          return 'BEGIN EXCLUSIVE TRANSACTION';
        default:
          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 {
  factory(require('sqlite3'));
} 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