Any-DB

The less-opinionated Node.js database abstraction layer

Status

Any-DB is in maintenance mode and bug fixes will happen infrequently/never.* What this means for you depends on how you are using any-db:

• If you need support for a fixed set of database engines: you should replace the dependency on any-db with the underlying database driver(s). Code adjustments should be minimal and you'll get access to all the modern features provided by the database drivers that any-db doesn't expose (such as promises).
• If you need to support arbitrary runtime defined database connections: any-db is still functional, but has had to start restricting the driver versions it depends on. If you are interested in maintaining these packages feel free to contact me.
• If you are using a library that depends on any-db: contact the author of that library and ask them to read this notice.

* Why? I haven't used any-db myself in nearly a decade and there are no other maintainers.

Synopsis

Establish a connection:

// Takes an optional callback
var conn = anyDB.createConnection('driver://user:pass@hostname/database')

Make queries:

var sql = 'SELECT * FROM questions'

// query() returns a readable stream
conn.query(sql).on('data', function (row) {})

// pass a callback to collect results
conn.query(sql, function (error, result) {})

Use bound parameters:

sql += ' WHERE answer = ?'
conn.query(sql, [42], function (err, res) {})

Manage database transactions with any-db-transaction:

var begin = require('any-db-transaction')

var tx = begin(conn)              // Can also take a callback
tx.on('error', function (err) {}) // Emitted for unhandled query errors
tx.query(...)                     // same interface as connections, plus...
tx.rollback()                     // this too
tx.commit()                       // takes an optional callback for errors

Create a connection pool that maintains 2-20 connections:

var pool = anyDB.createPool(dbURL, {min: 2, max: 20})

pool.query(...)       // perform a single query, same API as connection
var tx = begin(pool)  // create a transaction with the first available connection
pool.close()          // close the pool (call when your app should exit)

Description

The purpose of this library is to provide a consistent API for the commonly used functionality of SQL database drivers, while avoiding altering driver behaviour as much as possible.

Installation

For Applications

npm install --save any-db-{postgres,mysql,sqlite3,mssql} any-db

All of the adapter libraries have any-db as a peerDependency, which means that you will have to install any-db as well.

For Libraries

Add any-db to peerDependencies in package.json. This allows users of your library to satisfy the any-db dependency by installing the adapter of their choice. If you need to run tests, list it as a devDependency too.

API

module.exports := {
  createConnection: (Url, Continuation<Connection>?) => Connection
  createPool: (Url, PoolConfig) => ConnectionPool
}

Url := String | { adapter: String }

PoolConfig := {
  min: Number,
  max: Number,
  onConnect: (Connection, ((Error) => void) => void
  reset: (Connection, ((Error) => void) => void
}

Continuation := (Maybe<Error>, Any) => void

The API of Connection and Query objects is fully described in the adapter-spec, while Transaction and ConnectionPool objects have their own documentation. Connections, transactions and pools all have a query method that behaves consistently between drivers.

Both exported functions require an Url as their first parameter. This can either be a string of the form adapter://user:password@host/database (which will be parsed by parse-db-url) or an object. When an object is used, it must have an adapter property, and any other properties required by the specified adapters createConnection method.

See also: README for your chosen adapter (MS SQL, MySQL, Postgres, and SQLite3)

License

MIT