any-db-pool - npm Package Compare versions

Comparing version 1.0.1 to 1.0.2

index.js

 var inherits     = require('util').inherits
 var EventEmitter = require('events').EventEmitter
+var Transaction  = require('any-db-transaction')
 var Pool         = require('generic-pool').Pool
@@ -17,17 +18,32 @@ var once         = require('once')
 
-  var onConnect = options.onConnect;
+  options    = options    || {}
+  connParams = connParams || {}
 
+  if (options.create || options.destroy) {
+    throw new Error("Use onConnect/reset options instead of create/destroy.")
+  }
+
+  if (connParams.adapter == 'sqlite3'
+      && /:memory:$/i.test(connParams.database)
+      && (options.min > 1 || options.max > 1))
+  {
+    console.warn(
+      "Pools of more than 1 connection do not work for in-memory SQLite3 databases\n" +
+      "The specified minimum (%d) and maximum (%d) connections have been overridden",
+      options.min, options.max
+    )
+    if (options.min) options.min = 1
+    options.max = 1
+  }
+  
   var poolOpts = {
-    min: options.min,
-    max: options.max,
-    create: onConnect ?
-      function (ready) {
-        adapter.createConnection(connParams, function (err, conn) {
-          if (err) ready(err);
-          else onConnect(conn, ready)
-        })
-      }
-      : function (ready) { adapter.createConnection(connParams, ready) }
-    ,
-
+    min: options.min || 0,
+    max: options.max || 10,
+    create: function (ready) {
+      adapter.createConnection(connParams, function (err, conn) {
+        if (err) return ready(err);
+        else if (options.onConnect) options.onConnect(conn, ready)
+        else ready(null, conn)
+      })
+    },
     destroy: function (conn) {
@@ -42,6 +58,7 @@ conn.end()
   var resetSteps = [];
-  if (adapter.reset) resetSteps.unshift(adapter.reset);
+  if (adapter.reset) resetSteps.unshift(adapter.reset)
   if (options.reset) resetSteps.unshift(options.reset)
+  this.adapter = adapter.name
   this._adapter = adapter
-  this._reset = chain(resetSteps);
+  this._reset = chain(resetSteps)
   this._pool = new Pool(poolOpts)
@@ -105,1 +122,17 @@ }
 }
+
+ConnectionPool.prototype.begin = function (beginStatement, callback) {
+  var tx = Transaction.begin(this._adapter.createQuery, beginStatement, callback)
+
+  var pool = this
+  this.acquire(function (err, connection) {
+    if (err) return tx.emit('error', err);
+    var release = pool.release.bind(pool, connection)
+    tx.on('query', pool.emit.bind(pool, 'query'))
+    tx.once('rollback:complete', release)
+      .once('commit:complete', release)
+      .setConnection(connection)
+  })
+
+  return tx;
+}

package.json

 {
   "name": "any-db-pool",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Any-DB connection pool",
@@ -8,2 +8,5 @@ "main": "index.js",
   "license": "BSD-2-Clause",
+  "scripts": {
+    "test": "tape tests/*.js"
+  },
   "repository": {
@@ -18,4 +21,9 @@ "type": "git",
     "generic-pool": "~2.0.2",
+    "any-db-transaction": "0.0.1",
     "once": "~1.1.1"
+  },
+  "devDependencies": {
+    "tape": "~2.3.2",
+    "any-db-fake": "0.0.0"
   }
 }

README.md

@@ -9,22 +9,14 @@ # any-db-pool - database agnostic connection pool
 var ConnectionPool = require('any-db-pool')
-var mysql = require('mysql')
+var adapter = require('any-db-mysql')
 
-var adapter = {
-  createConnection: function (opts, callback) {
-    var conn = mysql.createConnection(opts, callback)
-    conn.connect(function (err) {
-      if (err) callback(err)
-      else callback(null, conn)
-    })
-    return conn
-  },
-  createQuery: mysql.createQuery
-}
+var pool = new ConnectionPool(
+  adapter,
+  { user: 'scott', password: 'tiger' },
+  { min: 5,
+    max: 15,
+    reset: function (conn, done) {
+      conn.query('ROLLBACK', done)
+    }
+  })
 
-var pool = new ConnectionPool(adapter, {user: 'scott', password: 'tiger'}, {
-  min: 5,
-  max: 15,
-  reset: function (conn, done) { conn.query('ROLLBACK', done) }
-})
-
 // Proxies to mysql's connection.query
@@ -37,27 +29,113 @@ var q = pool.query('SELECT 1', function (err, res) { })
 This module contains a database connection pool that can be used with any
-driver, though it is designed to integrate well with [any-db][any-db], a
-minimal database abstraction layer. If you are writing a library that needs to
-support multiple database backends (e.g. SQLite3 or Postgres or MySQL) then it's
-highly encouraged that you use [any-db][any-db] and **not** this
-module.
+driver, though it is designed to work well with [any-db compliant
+adapters][any-db-adapter-spec]. If you are writing a library that needs to support multiple database
+backends (e.g. SQLite3 or Postgres or MySQL) then it's highly encouraged that
+you add [any-db][any-db] to your `peerDependencies` and **not** this module
+directly.
 
-If, on the other hand, you just need a connection pool for your application this
-should work for you with very little fuss.
+[any-db-adapter-spec]: https://github.com/grncdr/node-any-db-adapter-spec
 
-[any-db]: http://npm.im/any-db
-
 ## Why wouldn't I just use `generic-pool`?
 
-[generic-pool][gpool] is awesome, but it's *very* generic.  This is a Good Thing
-for a library with "generic" in the name, but not so good for the very common
-but slightly more specialized case of pooling stateful database connection. This
-library uses `generic-pool` and simply augments it with some added niceties:
+[generic-pool][gpool] is awesome, but it's *very* generic.  This is a Good
+Thing for a library with "generic" in the name, but not so good for the very
+common but slightly more specialized case of pooling stateful SQL database
+connections.  This library uses `generic-pool` and simply augments it with some
+added niceties:
 
-* Hooks for initializing and/or resetting connection state when connections are
-	added to the pool.
-* A `query` method that allows queries to be performed without the user needing
-	a reference to a connection object (and potentially leaking that reference).
+* Hooks for initializing and/or resetting connection state when connections are added or returned to the pool.
+* A `query` method that allows queries to be performed without the user needing a reference to a connection object (and potentially leaking that reference).
 
-[gpool]: http://npm.im/generic-pool
+## API
 
+*Note:* ConnectionPool instances are usually created with the [createPool][] function from [any-db], which automatically selects an [Adapter][] for a given database URL.
+
+```ocaml
+module.exports := (Adapter, adapterConfig: Object, PoolConfig) => ConnectionPool
+
+ConnectionPool := EventEmitter & {
+  adapter: String,
+  query:   (String, Array?, Continuation<ResultSet>?) => Query,
+  begin:   (Continuation<Transaction>?) => Transaction,
+  acquire: (Continuation<Connection>) => void,
+  release: (Connection) => void,
+  close:   (Continuation<void>?) => void,
+}
+
+PoolConfig := {
+  min: Number?,
+  max: Number?,
+  onConnect: (Connection, ready: Continuation<Connection>) => void
+  reset: (Connection, done: Continuation<void>) => void
+}
+```
+
+### PoolConfig
+
+A `PoolConfig` is generally a plain object with any of the following properties (they are all optional):
+
+ - `min` (default `0`) The minimum number of connections to keep open in the pool.
+ - `max` (default `10`) The maximum number of connections to keep open in the pool. When this limit is reached further requests for connections will queue waiting for an existing connection to be released back into the pool.
+ - `onConnect` Called immediately after a connection is first established. Use this to do one-time setup of new connections. The supplied `Connection` will not be added to the pool until you pass it to the `done` continuation.
+ - `reset` Called each time a connection is returned to the pool. Use this to restore a connection to it's original state (e.g. rollback transactions, set the database session vars). If `reset` fails to call the `done` continuation the connection will be lost in limbo.
+
+### ConnectionPool.query
+
+```ocaml
+(String, Array?, Continuation<ResultSet>?) => Query
+```
+
+Acts exactly like [Connection.query][] by automatically acquiring a connection
+and releasing it when the query completes.
+
+### ConnectionPool.begin
+
+```ocaml
+(Continuation<Transaction>?) => Transaction
+```
+
+Acts exactly like [Connection.begin][], but the underlying
+connection is returned to the pool when the transaction commits or rolls back.
+
+### ConnectionPool.acquire
+
+```ocaml
+(Continuation<Connection>) => void
+```
+
+Remove a connection from the pool. If you use this method you **must** return
+the connection back to the pool using [ConnectionPool.release][]
+
+### ConnectionPool.release
+
+```ocaml
+(Connection) => void
+```
+
+Return a connection to the pool. This should only be called with connections
+you've manually [acquired](#connectionpoolacquire). You **must not** continue
+to use the connection after releasing it.
+
+### ConnectionPool.close
+
+```ocaml
+(Continuation<void>?) => void
+```
+
+Stop giving out new connections, and close all existing database connections as
+they are returned to the pool.
+
+### ConnectionPool.adapter
+
+The string name of the adapter used for this connection pool, e.g. `'sqlite3'`.
+
+### ConnectionPool events
+
+ * `'acquire'` - emitted whenever `pool.acquire` is called
+ * `'release'` - emitted whenever `pool.release` is called
+ * `'query', query` - emitted immediately after `.query` is called on a
+   connection via `pool.query`. The argument is a [Query][] object.
+ * `'close'` - emitted when the connection pool has closed all of it
+   connections after a call to `close()`.
+
 ## Installation
@@ -67,10 +145,11 @@
 
-## API
-
-You can find the API documentation for this connection pool included in the rest of
-the any-db API docs
-[here](https://github.com/grncdr/node-any-db/blob/master/API.md#connectionpool).
-
 ## License
 
 MIT
+
+[gpool]: http://npm.im/generic-pool
+[any-db]: https://github.com/grncdr/node-any-db
+[Adapter]: https://github.com/grncdr/node-any-db-adapter-spec#adapter
+[createPool]: https://github.com/grncdr/node-any-db#exportscreatepool
+[Connection.query]: https://github.com/grncdr/node-any-db-adapter-spec#connectionquery
+[Query]: https://github.com/grncdr/node-any-db-adapter-spec#query

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

15757

increased by123.85%

Number of package files

10

increased by100%

Lines of code

308

increased by124.82%

Number of lines in readme file

153

increased by106.76%

Worsened metrics

Dependency count

3

increased by50%

Dev dependency count

2

increased byInfinity%

Dependency changes

• + Addedany-db-transaction@0.0.1

• + Addedany-db-transaction@0.0.1(transitive)

• + Addedinherits@2.0.4(transitive)

• + Addedyafsm@0.0.0(transitive)