oracledb 3.0.0 → 3.1.2

package/CHANGELOG.md

@@ -1,8 +1,135 @@
 # Change Log
 
+## node-oracledb v3.1.2 (22 Feb 2019)
+
+- Fixed a bug causing CQN crashes when multiple queries are registered
+  ([ODPI-C change](https://github.com/oracle/odpi/issues/96)).
+
+- Fixed a CQN race condition to prevent a crash when a multiple
+  `conn.unsubscribe()` calls are made on the same subscription.
+
+- Improved validation of `executeMany()` arguments to prevent a crash.
+
+- Standardized error message for SODA `createCollection()` with
+  invalid metadata.
+
+- Correct the DPI-1050 error text displayed when the Oracle Client
+  libraries are too old ([ODPI-C change](https://github.com/oracle/odpi/commit/d2fea3801286d054e18b0102e60a69907b7faa9a)).
+
+- Allow `npm run buildbinary` to succeed even if `git` is not
+  available.
+
+- Use a relative URL for the ODPI-C submodule to make cloning from
+  oss.oracle.com also use ODPI-C from oss.oracle.com
+
+## node-oracledb v3.1.1 (25 Jan 2019)
+
+- Rebuild npm package to resolve Linux binary build issue.
+
+## node-oracledb v3.1.0 (22 Jan 2019)
+
+- Support tagging of pooled connections when releasing them to the
+  connection pool.  When using Oracle Client libraries 12.2 or later,
+  Oracle's multi-property tagging is used, and a PL/SQL "session"
+  state fix-up procedure can be called when a requested connection tag
+  does not match the actual tag.  This removes the need to reset
+  connection session state after every `pool.getConnection()` call.
+
+- Support a Node.js callback function for connection pools.  It is
+  called when a connection is newly created and has never been
+  acquired from the pool before, or when a requested connection tag
+  does not match the actual tag.
+
+- Support explicit dropping of connections from connection pools.
+
+- Support passing parameters in `oracledb.getConnection()` (such as
+  `poolAlias`, `tag` and proxy authentication credentials) for use
+  with the pool cache.
+
+- Support the combination of a user proxy and external authentication
+  with standalone connections (ODPI-C change).
+
+- Defer initialization of the Oracle Client libraries until the first
+  use of `oracledb.getConnection()`, `oracledb.createPool()`,
+  `oracledb.oracleClientVersion`, or
+  `oracledb.oracleClientVersionString`.
+
+  If the Oracle Client cannot be loaded, `getConnection()` and
+  `createPool()` will return an error via the callback.  Accessing
+  `oracledb.oracleClientVersion` or
+  `oracledb.oracleClientVersionString` with throw an error.
+
+  This change allows `require('oracledb')` to always succeed, allowing
+  node-oracledb constants and other attributes to be accessed even if
+  the Oracle Client is not installed.
+
+  This makes it easier to include node-oracledb in multi-database
+  applications where not all users will be accessing Oracle Database.
+
+  It allows code generation tools to access node-oracledb constants
+  without needing Oracle Client installed (see
+  [#983](https://github.com/oracle/node-oracledb/issues/983)).
+
+  Applications now have more scope to alter Oracle environment
+  variables referenced by the Oracle Client layer. Note it is still
+  recommended that the environment be set before Node.js is executed
+  due to potential for confusion or unexpected behavior due to
+  order-of-execution issues.
+
+- Support fetching XMLTYPE columns in queries.  They will return as
+  String limited to the VARCHAR2 length.
+
+- Updated install processes by bundling all pre-built binaries into
+  the https://www.npmjs.com/package/oracledb package, removing the
+  need for a separate binary package download from GitHub.  At runtime
+  an appropriate binary is loaded by `require()`, if it exists,
+  allowing one `node_modules/oracledb` install to be usable in
+  different environments.
+
+  Source code is no longer included in the npm package.  It is still
+  available from GitHub and oss.oracle.com.
+
+  The steps for self-hosting a node-oracledb package have changed, see
+  [INSTALL](https://github.com/oracle/node-oracledb/blob/master/INSTALL.md#selfhost).
+
+- Fixed a crash with high frequency notifications from CQN
+  ([#1009](https://github.com/oracle/node-oracledb/issues/1009)).
+
+- Fixed `poolPingInterval` with Oracle client libraries 12.2 or later
+  (ODPI-C change).
+
+- Fixed an issue with `poolPingInterval` that could cause usable
+  pooled connections to be unnecessarily dropped by
+  `connection.close()`.  (ODPI-C change).
+
+- Fixed a memory leak under certain cirumstances when pooled
+  connections are released back to the pool. (ODPI-C change)
+
+- Display correct error message for SODA `createIndex()` when no
+  parameter is passed.
+
+- Fixed some SODA stability issues (node-oracledb and ODPI-C changes).
+
+- Improved the statement error white list to avoid unnecessarily
+  dropping statements from the statement cache (ODPI-C change).
+
+- Made internal changes to fix V8 deprecation compilation warnings
+  with Node.js 10.12, and fixed other static analysis warnings.
+
+## node-oracledb v3.0.1 (15 Nov 2018)
+
+- Improve validation for SODA `createDocument()` arguments.
+
+- Stated compatibility is now for Node.js 6, 8, 10, and 11.
+
+- Upgraded NAN dependency from 2.10 to 2.11.1.
+
 ## node-oracledb v3.0.0 (1 Oct 2018)
 
-- Added new APIs for Simple Oracle Document Access ([SODA](https://github.com/oracle/node-oracledb/blob/master/doc/api.md#sodaoverview)), available when using Oracle Database 18.1 and Oracle client libraries version 18.3, or later.
+- Added new APIs for Simple Oracle Document Access
+  ([SODA](https://github.com/oracle/node-oracledb/blob/master/doc/api.md#sodaoverview)),
+  available when using Oracle Database 18.3 and Oracle client
+  libraries version 18.3, or later.
 
 - Added a `drainTime` argument to
   [`pool.close()`](https://github.com/oracle/node-oracledb/blob/master/doc/api.md#poolclose),
@@ -68,9 +195,9 @@
   support in connection pools.  This allows each connection in the
   pool to use different database credentials.
 
-- Added support for Oracle Database Continuous Query Notifications,
-  allowing JavaScript methods to be called when database changes are
-  committed.
+- Added support for Oracle Database Continuous Query Notifications
+  (CQN), allowing JavaScript methods to be called when database
+  changes are committed.
 
 - Added support to `fetchAsString` and `fetchInfo` for fetching RAW
   columns as STRING (hex-encoded).
@@ -171,8 +298,8 @@
 
 ## node-oracledb v2.1.1 (16 Feb 2018)
 
-- Fixed regression with querystream() in Node 4 & 6.
-  https://github.com/oracle/node-oracledb/issues/847
+- Fixed regression with `queryStream()` in Node 4 & 6
+  ([#847](https://github.com/oracle/node-oracledb/issues/847)).
 
 ## node-oracledb v2.1.0 (15 Feb 2018)
 
@@ -365,7 +492,7 @@
   the asynchronous portion of the `close()` method, so that all other
   attempts are no-ops.
 
-- Relaxed the restriction preventing `oracledb.connnectionClass` being
+- Relaxed the restriction preventing `oracledb.connectionClass` being
   used with dedicated connections; it previously gave ORA-56609.  Now
   DRCP can now be used with dedicated connections but the
   `CLIENT_DRIVER` value in `V$SESSION_CONNECT_INFO` will not be set in
@@ -481,7 +608,7 @@
 - Move operations on REF CURSORS out of the main thread in order to
   improve performance and memory usage.
 
-- Relaxed the restriction preventing `oracledb.connnectionClass` being
+- Relaxed the restriction preventing `oracledb.connectionClass` being
   used with dedicated connections; it previously gave ORA-56609.  Now
   DRCP can now be used with dedicated connections but the
   `CLIENT_DRIVER` value in `V$SESSION_CONNECT_INFO` will not be set in

package/README.md

@@ -1,9 +1,9 @@
-# node-oracledb version 3.0
+# node-oracledb version 3.1
 
 The node-oracledb add-on for Node.js powers high performance Oracle
 Database applications.
 
-Use node-oracledb to connect Node.js 6, 8 and 10 to Oracle Database.
+Use node-oracledb to connect Node.js 6, 8, 10 and 11 to Oracle Database.
 
 Node-oracledb supports basic and advanced features of Oracle Database
 and Oracle Client.  See the
@@ -27,8 +27,8 @@ See the [examples][30] directory.  Start with
 
 ## <a name="help"></a> Help
 
-Issues and questions can be raised with the node-oracledb community on
-[GitHub][3].
+Issues and questions about node-oracledb can be posted on [GitHub][3] or
+[Slack][5] ([link to join Slack][6]).
 
 ## <a name="testing"></a> Tests
 
@@ -64,6 +64,8 @@ limitations under the License.
 [2]: https://oracle.github.io/node-oracledb/INSTALL.html#quickstart
 [3]: https://github.com/oracle/node-oracledb/issues
 [4]: https://oracle.github.io/node-oracledb
+[5]: https://node-oracledb.slack.com/
+[6]: https://node-oracledb.slack.com/join/shared_invite/enQtNDU4Mjc2NzM5OTA2LTdkMzczODY3OGY3MGI0Yjk3NmQ4NDU4MTI2OGVjNTYzMjE5OGY5YzVkNDY4MWNkNjFiMDM2ZDMwOWRjNWVhNTg
 [30]: https://github.com/oracle/node-oracledb/blob/master/examples
 [31]: https://github.com/oracle/node-oracledb/blob/master/examples/example.js#L32
 [32]: https://oracle.github.io/node-oracledb/doc/api.html

package/build/Release/oracledb-abi48-darwin-x64.node-buildinfo.txt

@@ -0,0 +1 @@
+oracledb-abi48-darwin-x64.node v6.16.0 e70199aedd8542402cb2c5f8d75c2f8aa621df76 5768d8f93ef9ba42e8d4a6d701ace16504debc90 Tue, 19 Feb 2019 22:43:26 GMT

package/build/Release/oracledb-abi48-linux-x64.node-buildinfo.txt

@@ -0,0 +1 @@
+oracledb-abi48-linux-x64.node v6.16.0 e70199aedd8542402cb2c5f8d75c2f8aa621df76 5768d8f93ef9ba42e8d4a6d701ace16504debc90 Tue, 19 Feb 2019 23:04:20 GMT

package/build/Release/oracledb-abi48-win32-x64.node-buildinfo.txt

@@ -0,0 +1 @@
+oracledb-abi48-win32-x64.node v6.16.0 e70199aedd8542402cb2c5f8d75c2f8aa621df76 5768d8f93ef9ba42e8d4a6d701ace16504debc90 Wed, 20 Feb 2019 05:36:36 GMT

package/build/Release/oracledb-abi57-darwin-x64.node-buildinfo.txt

@@ -0,0 +1 @@
+oracledb-abi57-darwin-x64.node v8.15.0 e70199aedd8542402cb2c5f8d75c2f8aa621df76 5768d8f93ef9ba42e8d4a6d701ace16504debc90 Tue, 19 Feb 2019 22:44:49 GMT

package/build/Release/oracledb-abi57-linux-x64.node-buildinfo.txt

@@ -0,0 +1 @@
+oracledb-abi57-linux-x64.node v8.15.0 e70199aedd8542402cb2c5f8d75c2f8aa621df76 5768d8f93ef9ba42e8d4a6d701ace16504debc90 Tue, 19 Feb 2019 23:04:59 GMT

package/build/Release/oracledb-abi57-win32-x64.node-buildinfo.txt

@@ -0,0 +1 @@
+oracledb-abi57-win32-x64.node v8.15.0 e70199aedd8542402cb2c5f8d75c2f8aa621df76 5768d8f93ef9ba42e8d4a6d701ace16504debc90 Wed, 20 Feb 2019 05:36:45 GMT

package/build/Release/oracledb-abi64-darwin-x64.node-buildinfo.txt

@@ -0,0 +1 @@
+oracledb-abi64-darwin-x64.node v10.15.1 e70199aedd8542402cb2c5f8d75c2f8aa621df76 5768d8f93ef9ba42e8d4a6d701ace16504debc90 Tue, 19 Feb 2019 22:45:35 GMT

package/build/Release/oracledb-abi64-linux-x64.node-buildinfo.txt

@@ -0,0 +1 @@
+oracledb-abi64-linux-x64.node v10.15.1 e70199aedd8542402cb2c5f8d75c2f8aa621df76 5768d8f93ef9ba42e8d4a6d701ace16504debc90 Tue, 19 Feb 2019 23:06:02 GMT

package/build/Release/oracledb-abi64-win32-x64.node-buildinfo.txt

@@ -0,0 +1 @@
+oracledb-abi64-win32-x64.node v10.15.0 e70199aedd8542402cb2c5f8d75c2f8aa621df76 5768d8f93ef9ba42e8d4a6d701ace16504debc90 Wed, 20 Feb 2019 05:36:58 GMT

package/build/Release/oracledb-abi67-darwin-x64.node-buildinfo.txt

@@ -0,0 +1 @@
+oracledb-abi67-darwin-x64.node v11.10.0 e70199aedd8542402cb2c5f8d75c2f8aa621df76 5768d8f93ef9ba42e8d4a6d701ace16504debc90 Tue, 19 Feb 2019 22:46:26 GMT

package/build/Release/oracledb-abi67-linux-x64.node-buildinfo.txt

@@ -0,0 +1 @@
+oracledb-abi67-linux-x64.node v11.10.0 e70199aedd8542402cb2c5f8d75c2f8aa621df76 5768d8f93ef9ba42e8d4a6d701ace16504debc90 Tue, 19 Feb 2019 23:06:38 GMT

package/build/Release/oracledb-abi67-win32-x64.node-buildinfo.txt

@@ -0,0 +1 @@
+oracledb-abi67-win32-x64.node v11.10.0 e70199aedd8542402cb2c5f8d75c2f8aa621df76 5768d8f93ef9ba42e8d4a6d701ace16504debc90 Wed, 20 Feb 2019 05:37:10 GMT

package/lib/connection.js

@@ -273,13 +273,27 @@ rollbackPromisified = nodbUtil.promisify(rollback);
 
 // This close function is used to override the close method of the Connection
 // class, which is defined in the C layer.
-function close(closeCb) {
+function close(a1, a2) {
   var self = this;
+  var options = {};
+  var closeCb;
 
-  nodbUtil.assert(arguments.length === 1, 'NJS-009');
-  nodbUtil.assert(typeof closeCb === 'function', 'NJS-006', 1);
+  nodbUtil.assert(arguments.length >= 1 && arguments.length <= 2, 'NJS-009');
+
+  switch (arguments.length) {
+    case 1:
+      nodbUtil.assert(typeof a1 === 'function', 'NJS-006', 1);
+      closeCb = a1;
+      break;
+    case 2:
+      nodbUtil.assert(nodbUtil.isObject(a1), 'NJS-006', 1);
+      nodbUtil.assert(typeof a2 === 'function', 'NJS-006', 2);
+      options = a1;
+      closeCb = a2;
+      break;
+  }
 
-  self._close(function(err) {
+  self._close(options, function(err) {
     if (!err) {
       self.emit('_after_close');
     }

package/lib/oracledb.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -30,112 +30,45 @@ var getConnectionPromisified;
 var poolCache = {};
 var tempUsedPoolAliases = {};
 var defaultPoolAlias = 'default';
-var binaryReleasePath = '../build/Release/oracledb.node';
-var binaryDebugPath = '../build/Debug/oracledb.node';
-
-// Load the node-oracledb binary add-on that was built when 'npm
-// install' invoked node-gyp.
-// The Debug version of node-oracledb will only exist if 'npm install
-// --debug oracledb' was used.  Typically only the maintainers of
-// node-oracledb do this.
-try {
-  oracledbCLib =  require(binaryReleasePath);
-} catch (err) {
-  var nodeInfo = process.versions.node + ' (' + process.platform + ', ' + process.arch +')\n';
-  var fullReleasePath = require('path').resolve(__dirname, binaryReleasePath);
-  if (err.code === 'MODULE_NOT_FOUND') {
-    try {
-      oracledbCLib = require(binaryDebugPath);
-    } catch (err) {
+
+//  Load the Oracledb binary
+
+var binaryLocations = [
+  '../' + nodbUtil.RELEASE_DIR + '/' + nodbUtil.BINARY_FILE,  // pre-built binary
+  '../' + nodbUtil.RELEASE_DIR + '/' + 'oracledb.node',       // binary built from source
+  '../build/Debug/oracledb.node'                              // debug binary
+];
+
+for (var i = 0; i < binaryLocations.length; i++) {
+  try {
+    oracledbCLib = require(binaryLocations[i]);
+    break;
+  } catch(err) {
+    if (err.code !== 'MODULE_NOT_FOUND' || i == binaryLocations.length - 1) {
+      var nodeInfo;
       if (err.code === 'MODULE_NOT_FOUND') {
-        // Neither Release or Debug binary was found but assume users wanted Release binary
-        nodeInfo += 'Cannot find module ' + fullReleasePath + '\n' + getInfo();
-        throw new Error(nodbUtil.getErrorMessage('NJS-045', nodeInfo));
+        // none of the three binaries could be found
+        nodeInfo = `\n  Looked for ${binaryLocations.map(x => require('path').resolve(__dirname, x)).join(', ')}\n  ${nodbUtil.getInstallURL()}\n`;
       } else {
-        nodeInfo += 'Cannot load ' + binaryDebugPath + '\n';
-        nodeInfo += 'Node.js require() error was: \n  ' + err.message + '\n' + getInfo();
-        throw new Error(nodbUtil.getErrorMessage('NJS-045', nodeInfo));
+        nodeInfo = `\n  Node.js require('oracledb') error was:\n  ${err.message}\n  ${nodbUtil.getInstallHelp()}\n`;
       }
-    }
-  } else {
-    if (err.message.startsWith('DPI-1047:')) {
-      // Release add-on binary loaded OK, but ODPI-C can't load Oracle client
-      nodeInfo += 'Node.js require() error was: \n  ' + err.message + '\n';
-      nodeInfo += 'Node.js require() mapped to ' + fullReleasePath + '\n' + getInfo();
-      throw new Error(nodbUtil.getErrorMessage('NJS-045', nodeInfo));
-    } else {
-      nodeInfo += 'Cannot load ' + fullReleasePath + '\n' + err.message + '\n' + getInfo();
       throw new Error(nodbUtil.getErrorMessage('NJS-045', nodeInfo));
     }
   }
 }
 
+// Oracledb functions and classes
+
 oracledbCLib.Oracledb.prototype.newLob = function(iLob) {
   return new Lob(iLob, null, oracledbInst);
 };
 
-
-// Return a string with installation usage tips that may be helpful
-function getInfo() {
-  var arch, url, mesg = '';
-  mesg = 'Node-oracledb installation instructions: ';
-  mesg += 'https://oracle.github.io/node-oracledb/INSTALL.html\n';
-  if (process.platform === 'linux') {
-    if (process.arch === 'x64') {
-      url = 'http://www.oracle.com/technetwork/topics/linuxx86-64soft-092277.html\n';
-      arch = '64-bit';
-    } else if (process.arch === 'x32') {
-      url = 'http://www.oracle.com/technetwork/topics/linuxsoft-082809.html\n';
-      arch = '32-bit';
-    } else {
-      url = 'http://www.oracle.com/technetwork/database/database-technologies/instant-client/overview/index.html\n';
-      arch = process.arch;
-    }
-    mesg += 'You must have ' + arch + ' Oracle client libraries in LD_LIBRARY_PATH, or configured with ldconfig.\n';
-    mesg += 'If you do not have Oracle Database on this computer, then install the Instant Client Basic or Basic Light package from \n';
-    mesg += url;
-  } else if (process.platform === 'darwin') {
-    if (process.arch === 'x64') {
-      url = 'http://www.oracle.com/technetwork/topics/intel-macsoft-096467.html';
-      arch = '64-bit';
-    } else if (process.arch === 'x32') {
-      url = 'http://www.oracle.com/technetwork/topics/intel-macsoft-096467.html';
-      arch = '32-bit';
-    } else {
-      url = 'http://www.oracle.com/technetwork/database/database-technologies/instant-client/overview/index.html\n';
-      arch = process.arch;
-    }
-    mesg += 'You must have the ' + arch + ' Oracle Instant Client Basic or Basic Light package in ~/lib or /usr/local/lib\n';
-    mesg += 'They can be downloaded from ' + url;
-  } else if (process.platform === 'win32') {
-    if (process.arch === 'x64') {
-      url = 'http://www.oracle.com/technetwork/topics/winx64soft-089540.html\n';
-      arch = '64-bit';
-    } else if (process.arch === 'x32') {
-      url = 'http://www.oracle.com/technetwork/topics/winsoft-085727.html\n';
-      arch = '32-bit';
-    } else {
-      url = 'http://www.oracle.com/technetwork/database/database-technologies/instant-client/overview/index.html\n';
-      arch = process.arch;
-    }
-    mesg += 'You must have ' + arch + ' Oracle client libraries in your PATH environment variable.\n';
-    mesg += 'If you do not have Oracle Database on this computer, then install the Instant Client Basic or Basic Light package from\n';
-    mesg += url;
-    mesg += 'A Microsoft Visual Studio Redistributable suitable for your Oracle client library version must be available.\n';
-  } else {
-    url = 'http://www.oracle.com/technetwork/database/database-technologies/instant-client/overview/index.html\n';
-    mesg += 'You must have ' + process.arch + ' Oracle client libraries in your operating system library search path.\n';
-    mesg += 'If you do not have Oracle Database on this computer, then install an Instant Client Basic or Basic Light package from: \n';
-    mesg += url;
-  }
-  return mesg;
-}
-
 // This createPool function is used the override the createPool method of the
 // Oracledb class, which is defined in the C layer. The override allows us to do
 // things like extend out the pool instance prior to passing it to the caller.
 function createPool(poolAttrs, createPoolCb) {
   var self = this;
+  var sessionCallback;
   var poolAlias;
 
   // Initial argument count and type checks are done first and throw in the same
@@ -170,6 +103,18 @@ function createPool(poolAttrs, createPoolCb) {
     return;
   }
 
+  // Retain local callback for fixing up tags on connections acquired from the
+  // pool, if applicable; this value can either be a function which will be
+  // called when a connection is acquired from the pool which doesn't have the
+  // requested tag or will be a string defining a PL/SQL procedure which will
+  // be called by the database when a connection acquired from the pool doesn't
+  // have the requested tag
+  sessionCallback = poolAttrs.sessionCallback;
+  if (typeof poolAttrs.sessionCallback === 'function') {
+    poolAttrs = Object.assign({}, poolAttrs);
+    delete poolAttrs.sessionCallback;
+  }
+
   // Need to prevent another call in the same stack from succeeding, otherwise
   // two pools could be created with the same poolAlias and the second one that
   // comes back would overwrite the first in the cache.
@@ -184,6 +129,9 @@ function createPool(poolAttrs, createPoolCb) {
         delete tempUsedPoolAliases[poolAlias];
       }
 
+      if (err.message.match(/DPI-1047/)) {
+        err.message += "\n" + nodbUtil.getInstallHelp();
+      }
       createPoolCb(err);
 
       return;
@@ -196,6 +144,7 @@ function createPool(poolAttrs, createPoolCb) {
       delete tempUsedPoolAliases[poolAlias];
     }
 
+    poolAttrs.sessionCallback = sessionCallback;
     pool.extend(poolInst, poolAttrs, poolAlias, self);
 
     poolInst.on('_after_close', function() {
@@ -241,7 +190,7 @@ function getConnection(a1, a2) {
   var self = this;
   var pool;
   var poolAlias;
-  var connAttrs;
+  var connAttrs = {};
   var getConnectionCb;
 
   nodbUtil.assert(arguments.length < 3, 'NJS-009');
@@ -285,7 +234,7 @@ function getConnection(a1, a2) {
       return;
     }
 
-    pool.getConnection(getConnectionCb);
+    pool.getConnection(connAttrs, getConnectionCb);
   } else {
     // Allow user to use connectionString as an alias for connectString.
     if (connAttrs.connectString === undefined) {
@@ -294,6 +243,9 @@ function getConnection(a1, a2) {
 
     self._getConnection(connAttrs, function(err, connInst) {
       if (err) {
+        if (err.message.match(/DPI-1047/)) {
+          err.message += "\n" + nodbUtil.getInstallHelp();
+        }
         getConnectionCb(err);
         return;
       }

package/lib/pool.js

@@ -34,7 +34,7 @@ function completeConnectionRequest(config, getConnectionCb) {
   // to prevent other connection requests from exceeding the poolMax.
   self._connectionsOut += 1;
 
-  self._getConnection(config, function(err, connInst) {
+  self._getConnection(config, function(err, connInst, newSession) {
     if (err) {
       // Decrementing _connectionsOut if we didn't actually get a connection
       // and then rechecking the queue.
@@ -63,7 +63,28 @@ function completeConnectionRequest(config, getConnectionCb) {
       checkRequestQueue.call(self);
     });
 
-    getConnectionCb(null, connInst);
+    // Invoke tag fixup callback method if one has been specified and
+    // the actual tag on the connection doesn't match the one
+    // requested, or the connection is freshly created.
+    let requestedTag = config.tag || "";
+    if (typeof self.sessionCallback === 'function' &&
+        (newSession || connInst.tag != requestedTag)) {
+      self.sessionCallback(connInst, requestedTag,
+        function(err) {
+          if (err) {
+            connInst.close({drop: true}, function() {
+              getConnectionCb(err);
+            });
+            return;
+          }
+          getConnectionCb(null, connInst);
+        }
+      );
+
+    // otherwise, simply invoke the user's callback immediately
+    } else {
+      getConnectionCb(null, connInst);
+    }
   });
 }
 
@@ -326,6 +347,9 @@ function logStats() {
   console.log('...poolIncrement:', self.poolIncrement);
   console.log('...poolTimeout (seconds):', self.poolTimeout);
   console.log('...poolPingInterval:', self.poolPingInterval);
+  console.log('...sessionCallback:',
+    typeof self.sessionCallback === 'function' ? self.sessionCallback.name :
+      (typeof self.sessionCallback === 'string' ? '"' + self.sessionCallback + '"' : self.sessionCallback));
   console.log('...stmtCacheSize:', self.stmtCacheSize);
   console.log('Pool status:');
   console.log('...status:', self.status);
@@ -465,6 +489,16 @@ function extend(pool, poolAttrs, poolAlias, oracledb) {
         writable: true,
         enumerable: true,
         value: oracledb.POOL_STATUS_OPEN
+      },
+      sessionCallback: {  // session callback
+        enumerable: true,
+        get: function() {
+          return poolAttrs.sessionCallback;
+        },
+        set: function() {
+          throw new Error(nodbUtil.getErrorMessage('NJS-014',
+            'sessionCallback'));
+        }
       }
     }
   );

package/lib/sodaCollection.js

@@ -92,7 +92,7 @@ insertOneAndGetPromisified = nodbUtil.promisify(insertOneAndGet);
 function createIndex(spec, cb) {
   var self = this;
 
-  nodbUtil.assert(arguments.length === 2, 'NUS-009', 1);
+  nodbUtil.assert(arguments.length === 2, 'NJS-009', 1);
   nodbUtil.assert(nodbUtil.isObject(spec), 'NJS-006', 1);
   nodbUtil.assert(typeof cb === 'function', 'NJS-006', 2);
 

package/lib/sodaDatabase.js

@@ -49,7 +49,7 @@ function createCollection(name, a2, a3) {
       createCollCb = a3;
       if (options.metaData) {
         if (!nodbUtil.isObject(options.metaData)) {
-          createCollCb(Error(nodbUtil.getErrorMessage('NJS-006', 3)));
+          createCollCb(Error(nodbUtil.getErrorMessage('NJS-006', 2)));
           return;
         }
         options.metaData = JSON.stringify(options.metaData);