Connection pooling logic for use with any service


100.0.48 years ago8 years agoMinified + gzip package size for connection-pool in KB



Connection pooling logic for use with any service

Build Status Dependency Status NPM version


npm install connection-pool


For example, say you wanted to set up and use a connection pool for MySQL:

var MySqlProvider = require('connection-pool/providers/mysql');
var LimitStrategy = require('connection-pool/strategies/limit');

var pool = new LimitStrategy(new MySqlProvider({
  host: 'hostname',
  port: 'port',
  user: 'user',
  password: 'password',
  database: 'database'
}), {
  limit: 20,
  idleTime: '10 minutes'

function query(str) {
  return pool.use(function (connection) {
    return new Promise(function (resolve, reject) {
      connection.query(str, function (err, rows) {
        if (err) reject(err);
        else resolve(rows);


Each strategy takes a Provider as it's first argument and an options object as its second argument. The provier must be an object with the following interface:

  • .create() returns either a Connection or a Promise.<Connection>
  • .destroy(connection) takes a Connection and ensures that it is properly disposed of
  • .isLive(connection) takes a Connection and returns true if it is still usable and false if an error may have caused it to become stale.
  • .unwrap(connection) takes a Connection and returns the true underlying conneciton/service to be passed to the use function.

Only .create() is required. By default, .destroy(connectioin) is a no-op, .isLive(connection) returns true and .unwrap(connection) returns the connection.


All other strategies inherit from Base. The base strategy provides the following public methods:

  • expand - increases the number of connections available in the pool by one.
  • shrink - reduces the number of connections available in the pool by one.
  • destroy - removes all connections from the pool and prevents any more being opened.
  • use(fn) - take a connection out of the pool and give it to fn, wait for fn to complete, then return the connection to the pool. It will return a Promise for the result of calling fn.

The base stratgy is also an EventEmitter and provides the following events:

  • expand - fired when .expand() is called
  • shrink - fired when .shrink() is called
  • use - fired when .use() is called
  • queue-push - fired when a transaction is pushed into the queue
  • queue-shift - fired when a transaction is taken off the queue
  • begin-transaction - fired when a transaction starts
  • end-transaction - fired when a transaction ends

By default the base strategy is pretty useless as it starts with an empty pool. You can call expand to add to the pool though, so could fairly easilly have a fixed sized pool.

// create a connection pool of size 2
var BaseStrategy = require('conneciton-pool/strategies/base');

var pool = new BaseStrategy(provider);


The simple strategy creates a new connection whenever there is an operation waiting for a connection. The problem with this is that a sudden spike can lead to a lot of connections staying open forever (unless you manually close them using shrink).


Limit extends the Simple strategy by letting you specify a maximum number of connections to create and/or a maximum time to have idle connections before closing one.

var LimitStrategy = require('conneciton-pool/strategies/limit');

var pool = new LimitStrategy(provider, {
  min: 4, // always keep at least one connection open (default: 0)
  max: 20, // never open more than 20 connections (default: Infinity)
  idleTime: '10 minutes', // every 10 minutes that go past with at least the `lowWaterMark` number of
                          // connections going spare, close a conneciton (default: Infinity)
  lowWaterMark: 2 // only close connections if there are more than this many spare (default: 0)



If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from