Add acquire and release events to Pool for tracking

closes #1366
closes #1449
closes #1528
closes #1625

Author: arnaudchenyensu

Changes.md

@@ -8,6 +8,7 @@ you spot any mistakes.
 
 * Accept regular expression as pool cluster pattern #1572
 * Accept wildcard anywhere in pool cluster pattern #1570
+* Add `acquire` and `release` events to `Pool` for tracking #1366 #1449 #1528 #1625
 * Add new error codes up to MySQL 5.7.17
 * Fix edge cases when determing Query result packets #1547
 * Fix memory leak when using long-running domains #1619 #1620

Readme.md

@@ -394,6 +394,18 @@ constructor. In addition to those options pools accept a few extras:
 
 ## Pool events
 
+### acquire
+
+The pool will emit an `acquire` event when a connection is acquired from the pool.
+This is called after all acquiring activity has been performed on the connection,
+right before the connection is handed to the callback of the acquiring code.
+
+```js
+pool.on('acquire', function (connection) {
+  console.log('Connection %d acquired', connection.threadId);
+});
+```
+
 ### connection
 
 The pool will emit a `connection` event when a new connection is made within the pool.
@@ -417,6 +429,18 @@ pool.on('enqueue', function () {
 });
 ```
 
+### release
+
+The pool will emit a `release` event when a connection is released back to the
+pool. This is called after all release activity has been performed on the connection,
+so the connection will be listed as free at the time of the event.
+
+```js
+pool.on('release', function (connection) {
+  console.log('Connection %d released', connection.threadId);
+});
+```
+
 ## Closing all the connections in a pool
 
 When you are done using the pool, you have to end all the connections or the

lib/Pool.js

@@ -60,6 +60,7 @@ Pool.prototype.getConnection = function (cb) {
       }
 
       pool.emit('connection', connection);
+      pool.emit('acquire', connection);
       cb(null, connection);
     });
     return;
@@ -105,6 +106,7 @@ Pool.prototype.acquireConnection = function acquireConnection(connection, cb) {
       pool.emit('connection', connection);
     }
 
+    pool.emit('acquire', connection);
     cb(null, connection);
   }
 
@@ -137,6 +139,7 @@ Pool.prototype.releaseConnection = function releaseConnection(connection) {
     } else {
       // add connection to end of free queue
       this._freeConnections.push(connection);
+      this.emit('release', connection);
     }
   }
 

test/unit/pool/test-acquire-event.js

@@ -0,0 +1,39 @@
+var assert = require('assert');
+var common = require('../../common');
+var pool   = common.createPool({
+  connectionLimit : 1,
+  port            : common.fakeServerPort
+});
+
+var server = common.createFakeServer();
+
+server.listen(common.fakeServerPort, function (err) {
+  assert.ifError(err);
+
+  var count    = 0;
+  var threadId = -1;
+  pool.on('acquire', function (connection) {
+    count++;
+    threadId = connection.threadId;
+  });
+
+  pool.getConnection(function (err, connection) {
+    assert.ifError(err);
+    assert.ok(connection);
+    assert.equal(count, 1);
+    assert.equal(threadId, connection.threadId);
+    connection.release();
+  });
+
+  pool.getConnection(function (err, connection) {
+    assert.ifError(err);
+    assert.ok(connection);
+    assert.equal(count, 2);
+    assert.equal(threadId, connection.threadId);
+    connection.release();
+    pool.end(function (err) {
+      assert.ifError(err);
+      server.destroy();
+    });
+  });
+});

test/unit/pool/test-release-event.js

@@ -0,0 +1,41 @@
+var assert = require('assert');
+var common = require('../../common');
+var pool   = common.createPool({
+  connectionLimit : 1,
+  port            : common.fakeServerPort
+});
+
+var server = common.createFakeServer();
+
+server.listen(common.fakeServerPort, function (err) {
+  assert.ifError(err);
+
+  var count    = 0;
+  var threadId = -1;
+  pool.on('release', function (connection) {
+    count++;
+    threadId = connection.threadId;
+  });
+
+  pool.getConnection(function (err, connection) {
+    assert.ifError(err);
+    assert.ok(connection);
+    assert.equal(count, 0);
+    connection.release();
+    assert.equal(count, 1);
+    assert.equal(threadId, connection.threadId);
+  });
+
+  pool.getConnection(function (err, connection) {
+    assert.ifError(err);
+    assert.ok(connection);
+    assert.equal(count, 1);
+    connection.release();
+    assert.equal(count, 2);
+    assert.equal(threadId, connection.threadId);
+    pool.end(function (err) {
+      assert.ifError(err);
+      server.destroy();
+    });
+  });
+});