Thin and less-opinionated database abstraction layer for node.
JavaScript
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
packages
.gitignore
.travis.yml
CONTRIBUTING.md
LICENSE Add CONTRIBUTING and LICENSE files, more doc updates Sep 9, 2013
README.md
index.js
lerna.json
package-lock.json Let's see what Travis makes of this Jul 13, 2018
package.json
test.js use any-db-fake for unit test Dec 22, 2013

README.md

Any-DB

Build Status

The less-opinionated Node.js database abstraction layer

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