oracledb 5.1.0 → 5.4.0

package/lib/pool.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2016, 2020, Oracle and/or its affiliates. All rights reserved
+// Copyright (c) 2016, 2022, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -22,38 +22,35 @@
 const EventEmitter = require('events');
 const nodbUtil = require('./util.js');
 const util = require('util');
+const PoolStatistics = require('./poolStatistics.js');
+
 
 //-----------------------------------------------------------------------------
 // _checkRequestQueue()
 //   When a connection is returned to the pool, this method is called (via an
 // event handler) to determine when requests for connections should be
-// completed and cancels any timeout that may have been associated with the
-// request.
+// resumed and cancels any timeout that may have been associated with the
+// request. This method is also called from reconfigure() so that waiting
+// connection requests can be processed. Note the use of a local variable for
+// the number of connections out. This is because the connection requests will
+// not resume until after the loop is finished, and therefore the number of
+// connections the pool thinks is out will not be incremented.
 //-----------------------------------------------------------------------------
 function _checkRequestQueue() {
-
-  // nothing to do if no requests are in the queue or the pool is still full
-  if (this._connRequestQueue.length === 0 ||
-      this._connectionsOut >= this.poolMax) {
-    return;
-  }
-
-  // process the payload
-  const payload = this._connRequestQueue.shift();
-  if (this._enableStats) {
-    this._totalRequestsDequeued += 1;
-    const waitTime = Date.now() - payload.enqueuedTime;
-    this._totalTimeInQueue += waitTime;
-    this._minTimeInQueue = Math.min(this._minTimeInQueue, waitTime);
-    this._maxTimeInQueue = Math.max(this._maxTimeInQueue, waitTime);
-  }
-  if (payload.timeoutHandle) {
-    clearTimeout(payload.timeoutHandle);
+  let connectionsOut = this._connectionsOut;
+  while (this._connRequestQueue.length > 0 && connectionsOut < this.poolMax) {
+    connectionsOut += 1;
+    const payload = this._connRequestQueue.shift();
+    if (this._enableStatistics) {
+      this._totalRequestsDequeued += 1;
+      this._updateWaitStatistics(payload);
+    }
+    if (payload.timeoutHandle) {
+      clearTimeout(payload.timeoutHandle);
+    }
+    // inform the waiter that processing can continue
+    payload.resolve();
   }
-
-  // inform the waiter that processing can continue
-  payload.resolve();
-
 }
 
 
@@ -75,11 +72,11 @@ async function getConnection(a1) {
     options = a1;
   }
 
-  // if pool is draining or closed, throw an appropriate error
-  this._checkPoolOpen();
+  // if pool is draining/closed, throw an appropriate error
+  this._checkPoolOpen(true);
 
   // manage stats, if applicable
-  if (this._enableStats) {
+  if (this._enableStatistics) {
     this._totalConnectionRequests += 1;
   }
 
@@ -88,20 +85,22 @@ async function getConnection(a1) {
   try {
     poolMax = this.poolMax;
   } catch (err) {
-    if (this._enableStats) {
+    if (this._enableStatistics) {
       this._totalFailedRequests += 1;
     }
     throw err;
   }
 
-  if (this._connectionsOut >= poolMax) {
+  if (this._connectionsOut >= poolMax ||
+      this.status === this._oracledb.POOL_STATUS_RECONFIGURING) {
 
     // when the queue is huge, throw error early without waiting for queue timeout
-    if (this._connRequestQueue.length >= this.queueMax && this.queueMax >= 0) {
-      if (this._enableStats) {
+    if (this._connRequestQueue.length >= this._queueMax &&
+        this._queueMax >= 0) {
+      if (this._enableStatistics) {
         this._totalRequestsRejected += 1;
       }
-      throw new Error(nodbUtil.getErrorMessage('NJS-076', this.queueMax));
+      throw new Error(nodbUtil.getErrorMessage('NJS-076', this._queueMax));
     }
 
     // if too many connections are out, wait until room is made available or the
@@ -120,29 +119,29 @@ async function getConnection(a1) {
           if (ix >= 0) {
             this._connRequestQueue.splice(ix, 1);
           }
-          if (this._enableStats) {
+          if (this._enableStatistics) {
             this._totalRequestTimeouts += 1;
-            this._totalTimeInQueue += Date.now() - payload.enqueuedTime;
+            this._updateWaitStatistics(payload);
           }
           reject(new Error(nodbUtil.getErrorMessage('NJS-040',
-            this.queueTimeout)));
-        }, this.queueTimeout);
+            this._queueTimeout)));
+        }, this._queueTimeout);
       }
 
       // add payload to the queue
       this._connRequestQueue.push(payload);
-      if (this._enableStats) {
+      if (this._enableStatistics) {
         payload.enqueuedTime = Date.now();
         this._totalRequestsEnqueued += 1;
-        this._maxQueueLength = Math.max(this._maxQueueLength,
+        this._maximumQueueLength = Math.max(this._maximumQueueLength,
           this._connRequestQueue.length);
       }
 
     });
 
-    // check if pool is draining or closed after delay has completed and throw
-    // an appropriate error if so
-    this._checkPoolOpen();
+    // check if pool is draining/closed after delay has
+    // completed and throw an appropriate error
+    this._checkPoolOpen(true);
 
   }
 
@@ -180,7 +179,7 @@ async function getConnection(a1) {
 
     // when connection is closed, check to see if another request should be
     // processed and update any stats, as needed
-    conn.on('_after_close', () => {
+    conn.on('_afterConnClose', () => {
       this._connectionsOut -= 1;
       this.emit('_checkRequestQueue');
       if (this._connectionsOut == 0) {
@@ -188,11 +187,11 @@ async function getConnection(a1) {
       }
     });
 
-    return conn;
+    return (conn);
 
   } catch (err) {
     this._connectionsOut -= 1;
-    if (this._enableStats) {
+    if (this._enableStatistics) {
       this._totalFailedRequests += 1;
     }
     this.emit('_checkRequestQueue');
@@ -202,6 +201,69 @@ async function getConnection(a1) {
 }
 
 
+//-----------------------------------------------------------------------------
+// reconfigure()
+//   Reconfigure the pool, change the value for given pool-properties.
+//-----------------------------------------------------------------------------
+async function reconfigure(options) {
+
+  // check arguments
+  nodbUtil.checkArgCount(arguments, 1, 1);
+  nodbUtil.assert(nodbUtil.isObject(options));
+
+  // reconfiguration can happen only when status is OPEN
+  this._checkPoolOpen(false);
+
+  if ((options.queueMax !== undefined) &&
+      (typeof options.queueMax !== "number"))
+    throw new Error(nodbUtil.getErrorMessage('NJS-004', "queueMax"));
+
+  if ((options.queueTimeout !== undefined) &&
+      (typeof options.queueTimeout !== "number"))
+    throw new Error(nodbUtil.getErrorMessage('NJS-004', "queueTimeout"));
+
+  if ((options.enableStatistics !== undefined) &&
+      (typeof options.enableStatistics !== "boolean"))
+    throw new Error(nodbUtil.getErrorMessage('NJS-004', "enableStatistics"));
+
+  if ((options.resetStatistics !== undefined) &&
+      (typeof options.resetStatistics != "boolean"))
+    throw new Error(nodbUtil.getErrorMessage('NJS-004', "resetStatistics"));
+
+  this._status = this._oracledb.POOL_STATUS_RECONFIGURING;
+  try {
+    // poolMin/poolMax/poolIncrement/poolPingInterval/poolTimeout/
+    // poolMaxPerShard/stmtCacheSize/sodaMetaDataCache parameters
+    await this._reconfigure(options);
+
+    // pool JS parameters: queueMax, queueTimeout, enableStatistics,
+    // resetStatistics
+
+    // reset the statistics-metrics only if 'resetStatistics' is true or
+    // 'enableStatistics' is being set to true
+    if (options.resetStatistics == true || (options.enableStatistics == true &&
+        this._enableStatistics == false)) {
+      this._resetStatistics();
+    }
+
+    if (options.queueMax !== undefined) {
+      this._queueMax = options.queueMax;
+    }
+
+    if (options.queueTimeout !== undefined) {
+      this._queueTimeout = options.queueTimeout;
+    }
+
+    if (options.enableStatistics !== undefined) {
+      this._enableStatistics = options.enableStatistics;
+    }
+  } finally {
+    this._status = this._oracledb.POOL_STATUS_OPEN;
+  }
+  this.emit('_checkRequestQueue');
+}
+
+
 //-----------------------------------------------------------------------------
 // close()
 //   Close the pool, optionally allowing for a period of time to pass for
@@ -230,9 +292,8 @@ async function close(a1) {
 
   }
 
-  // check status of pool; if pool is already being drained or is already
-  // closed, raise an appropriate error
-  this._checkPoolOpen();
+  // if the pool is draining/reconfiguring/closed, throw an appropriate error
+  this._checkPoolOpen(false);
 
   // wait for the pool to become empty or for the drain timeout to expire
   // (whichever comes first)
@@ -253,67 +314,38 @@ async function close(a1) {
   // close the pool
   await this._close({forceClose: forceClose});
   this._status = this._oracledb.POOL_STATUS_CLOSED;
-  this.emit('_after_close');
+  this.emit('_afterPoolClose');
 
 }
 
 
 //-----------------------------------------------------------------------------
-// _logStats()
-//   Hidden method that provides an easy way to log out the statistics related
-// information that's collected when _enableStats is set to true when creating
-// a pool. This functionality may be altered or enhanced in the future.
+// logStatistics()
+//  Method to print statistical related information and pool related
+//  information when enableStatistics is set to true.
+// NOTE: This function replaces the DEPRECATED _logStats() function
 //-----------------------------------------------------------------------------
-function _logStats() {
-  let averageTimeInQueue;
-
-  if (this.status === this._oracledb.POOL_STATUS_CLOSED) {
-    throw new Error(nodbUtil.getErrorMessage('NJS-065'));
+function logStatistics() {
+  const stats = this.getStatistics();
+  if (stats === null) {
+    throw new Error(nodbUtil.getErrorMessage('NJS-083'));
   }
+  stats.logStatistics();
+}
 
-  if (this._enableStats !== true) {
-    console.log('Pool statistics not enabled');
-    return;
-  }
 
-  averageTimeInQueue = 0;
+//-----------------------------------------------------------------------------
+// getStatistics()
+//  Method to obtain a JSON object with all statistical metrics and pool
+//  properties
+//-----------------------------------------------------------------------------
+function getStatistics() {
+  this._checkPoolOpen(false);
 
-  if (this._totalRequestsEnqueued !== 0) {
-    averageTimeInQueue = Math.round(this._totalTimeInQueue/this._totalRequestsEnqueued);
+  if (this._enableStatistics !== true) {
+    return null;
   }
-
-  console.log('\nPool statistics:');
-  console.log('...total up time (milliseconds):', Date.now() - this._createdDate);
-  console.log('...total connection requests:', this._totalConnectionRequests);
-  console.log('...total requests enqueued:', this._totalRequestsEnqueued);
-  console.log('...total requests dequeued:', this._totalRequestsDequeued);
-  console.log('...total requests failed:', this._totalFailedRequests);
-  console.log('...total requests exceeding queueMax:', this._totalRequestsRejected);
-  console.log('...total request timeouts:', this._totalRequestTimeouts);
-  console.log('...max queue length:', this._maxQueueLength);
-  console.log('...sum of time in queue (milliseconds):', this._totalTimeInQueue);
-  console.log('...min time in queue (milliseconds):', this._minTimeInQueue);
-  console.log('...max time in queue (milliseconds):', this._maxTimeInQueue);
-  console.log('...avg time in queue (milliseconds):', averageTimeInQueue);
-  console.log('...pool connections in use:', this.connectionsInUse);
-  console.log('...pool connections open:', this.connectionsOpen);
-  console.log('Pool attributes:');
-  console.log('...poolAlias:', this.poolAlias);
-  console.log('...queueMax:', this.queueMax);
-  console.log('...queueTimeout (milliseconds):', this.queueTimeout);
-  console.log('...poolMin:', this.poolMin);
-  console.log('...poolMax:', this.poolMax);
-  console.log('...poolIncrement:', this.poolIncrement);
-  console.log('...poolTimeout (seconds):', this.poolTimeout);
-  console.log('...poolPingInterval:', this.poolPingInterval);
-  console.log('...sessionCallback:',
-    typeof this.sessionCallback === 'function' ? this.sessionCallback.name :
-      (typeof this.sessionCallback === 'string' ? '"' + this.sessionCallback + '"' : this.sessionCallback));
-  console.log('...stmtCacheSize:', this.stmtCacheSize);
-  console.log('Pool status:');
-  console.log('...status:', this.status);
-  console.log('Related environment variables:');
-  console.log('...process.env.UV_THREADPOOL_SIZE:', process.env.UV_THREADPOOL_SIZE);
+  return new PoolStatistics(this);
 }
 
 
@@ -323,21 +355,70 @@ function _logStats() {
 // statistics and managing the connection queue.
 //-----------------------------------------------------------------------------
 function _setup(poolAttrs, poolAlias, oracledb) {
-  let queueMax;
-  let queueTimeout;
-
   if (typeof poolAttrs.queueTimeout !== 'undefined') {
-    queueTimeout = poolAttrs.queueTimeout;
+    this._queueTimeout = poolAttrs.queueTimeout;
   } else {
-    queueTimeout = oracledb.queueTimeout;
+    this._queueTimeout = oracledb.queueTimeout;
   }
 
   if (typeof poolAttrs.queueMax !== 'undefined') {
-    queueMax = poolAttrs.queueMax;
+    this._queueMax = poolAttrs.queueMax;
+  } else {
+    this._queueMax = oracledb.queueMax;
+  }
+
+  if (typeof poolAttrs.poolMaxPerShard !== 'undefined') {
+    this.poolMaxPerShard = poolAttrs.poolMaxPerShard;
+  }
+
+  if (typeof poolAttrs.enableStatistics !== 'undefined') {
+    this._enableStatistics = poolAttrs.enableStatistics;
+  } else {
+    this._enableStatistics = false;   // default statistics is disabled.
+  }
+
+  if (!this._enableStatistics) {
+    // DEPRECATED property _enableStats.
+    if (typeof poolAttrs._enableStats !== 'undefined') {
+      this._enableStatistics = poolAttrs._enableStats;
+    }
+  }
+
+  if (typeof poolAttrs.sessionCallback !== 'undefined') {
+    if (typeof poolAttrs.sessionCallback === 'function' ||
+        typeof poolAttrs.sessionCallback === 'string')
+      this._sessionCallback = poolAttrs.sessionCallback;
+  }
+
+  // Properties - edition, events, externalAuth - values can be set globally
+  // on oracledb and can be overridden at pool creation time.
+  if (typeof poolAttrs.edition !== 'undefined') {
+    this.edition = poolAttrs.edition;
+  } else {
+    this.edition = oracledb.edition;
+  }
+
+  if (typeof poolAttrs.events !== 'undefined') {
+    this.events = poolAttrs.events;
+  } else {
+    this.events = oracledb.events;
+  }
+
+  if (typeof poolAttrs.externalAuth !== 'undefined') {
+    this.externalAuth = poolAttrs.externalAuth;
   } else {
-    queueMax = oracledb.queueMax;
+    this.externalAuth = oracledb.externalAuth;
   }
 
+  // Properties - homogeneous, user, connectString - are NOT global properties
+  if (typeof poolAttrs.homogeneous !== 'undefined') {
+    this.homogeneous = poolAttrs.homogeneous;
+  } else {
+    this.homogeneous = true;
+  }
+  this.user = poolAttrs.user || poolAttrs.userName;
+  this.connectString = poolAttrs.connectString || poolAttrs.connectionString;
+
   // register event handler for when request queue should be checked
   this.on('_checkRequestQueue', this._checkRequestQueue);
 
@@ -349,63 +430,25 @@ function _setup(poolAttrs, poolAlias, oracledb) {
       queueMax: { // maximum number of pending pool connections that can be queued
         enumerable: true,
         get: function() {
-          return queueMax;
-        }
+          return (this._queueMax);
+        },
       },
       queueTimeout: { // milliseconds a connection request can spend in queue before being failed
         enumerable: true,
         get: function() {
-          return queueTimeout;
-        }
-      },
-      _enableStats: { // true means pool stats will be recorded
-        value: poolAttrs._enableStats === true
-      },
-      _logStats: { // output pool stats
-        value: _logStats
-      },
-      _createdDate: {
-        value: Date.now()
-      },
-      _totalConnectionRequests: { // total number of pool.getConnection requests
-        value: 0,
-        writable: true
-      },
-      _totalRequestsRejected: { // number of pool.getConnection requests rejected because the queue length exceeded queueMax
-        value: 0,
-        writable: true
-      },
-      _totalRequestsEnqueued: { // number of pool.getConnection requests added to queue
-        value: 0,
-        writable: true
-      },
-      _totalRequestsDequeued: { // number of pool.getConnection requests removed from queue because a pool connection became available
-        value: 0,
-        writable: true
-      },
-      _totalFailedRequests: { // number of pool.getConnection requests that failed at the C layer
-        value: 0,
-        writable: true
+          return (this._queueTimeout);
+        },
       },
-      _totalRequestTimeouts: { // number of queued pool.getConnection requests that timed out without being satisfied
-        value: 0,
-        writable: true
-      },
-      _totalTimeInQueue: { // sum of time in milliseconds that all pool.getConnection requests spent in the queue
-        value: 0,
-        writable: true
-      },
-      _maxQueueLength: { // maximum length of pool queue
-        value: 0,
-        writable: true
-      },
-      _minTimeInQueue: { // shortest amount of time (milliseconds) that any pool.getConnection request spent in queue
-        value: 0,
-        writable: true
+      _enableStats: { // DEPRECATED. true means pool stats will be recorded
+        get: function() {
+          return (this._enableStatistics);
+        }
       },
-      _maxTimeInQueue: { // longest amount of time (milliseconds) that any pool.getConnection request spent in queue
-        value: 0,
-        writable: true
+      enableStatistics: { // true means pool stats will be recorded
+        enumerable: true,
+        get: function() {
+          return (this._enableStatistics);
+        }
       },
       _connectionsOut: { // number of connections checked out from the pool. Must be inc/dec in the main thread in JS
         value: 0,
@@ -422,23 +465,38 @@ function _setup(poolAttrs, poolAlias, oracledb) {
       poolAlias: {
         enumerable: true,
         get: function() {
-          return poolAlias;
+          return (poolAlias);
         }
       },
       status: {  // open/closing/closed
         enumerable: true,
         get: function() {
-          return this._status;
+          return (this._status);
         }
       },
       sessionCallback: {  // session callback
         enumerable: true,
         get: function() {
-          return poolAttrs.sessionCallback;
+          return this._sessionCallback;
         }
       }
     }
   );
+
+  this._resetStatistics();
+
+}
+
+
+//-----------------------------------------------------------------------------
+// setAccessToken()
+//   set parameters for token based authentication
+//-----------------------------------------------------------------------------
+async function setAccessToken(options) {
+  // check arguments
+  nodbUtil.checkArgCount(arguments, 1, 1);
+  nodbUtil.assert(nodbUtil.isObject(options), 'NJS-005', 1);
+  await this._setAccessToken(options);
 }
 
 
@@ -450,22 +508,72 @@ class Pool extends EventEmitter {
     this._checkRequestQueue = _checkRequestQueue;
     this.close = nodbUtil.callbackify(close);
     this.getConnection = nodbUtil.callbackify(getConnection);
+    this.reconfigure = nodbUtil.callbackify(reconfigure);
+    this.setAccessToken = nodbUtil.callbackify(setAccessToken);
+    this.logStatistics = logStatistics;
+    this.getStatistics = getStatistics;
     this.terminate = this.close;
+    this._queueMax = 0;
+    this._queueTimeout = 0;
+    this._enableStatistics = false;
+    this._timeOfReset = this._createdDate = Date.now();
+    this._sessionCallback = undefined;
+
+    // DEPRECATED alias
+    this._logStats = this.logStatistics;
   }
 
-  // check if pool is draining or closed and throw an appropriate error if so
-  _checkPoolOpen() {
+  // check if pool is draining/reconfiguring/closed and throw an
+  // appropriate error
+  _checkPoolOpen(ignoreReconfiguring) {
+    // if already in reconfiguring status, nothing to do.
     if (this.status === this._oracledb.POOL_STATUS_DRAINING) {
       throw new Error(nodbUtil.getErrorMessage('NJS-064'));
     } else if (this.status === this._oracledb.POOL_STATUS_CLOSED) {
       throw new Error(nodbUtil.getErrorMessage('NJS-065'));
+    } else if (!ignoreReconfiguring) {
+      if (this.status === this._oracledb.POOL_STATUS_RECONFIGURING) {
+        throw new Error(nodbUtil.getErrorMessage('NJS-082'));
+      }
     }
   }
 
   // temporary method for determining if an object is a date until
-  // napi_is_date() can be used (when N-API v5 can be used)
+  // napi_is_date() can be used (when Node-API v5 can be used)
   _isDate(val) {
-    return util.isDate(val);
+    return (util.isDate(val));
+  }
+
+  //---------------------------------------------------------------------------
+  // _resetStatistics()
+  //  To initialize the counters/timers
+  //---------------------------------------------------------------------------
+  _resetStatistics() {
+    this._timeOfReset = Date.now();
+    this._totalConnectionRequests = 0;
+    this._totalRequestsEnqueued = 0;
+    this._totalRequestsDequeued = 0;
+    this._totalFailedRequests = 0;
+    this._totalRequestsRejected = 0;
+    this._totalRequestTimeouts = 0;
+    this._maximumQueueLength = this._connRequestQueue.length;
+    this._totalTimeInQueue = 0;
+    this._minTimeInQueue = 0;
+    this._maxTimeInQueue = 0;
+  }
+
+
+  // update pool wait statistics after a connect request has spent some time in
+  // the queue
+  _updateWaitStatistics(payload) {
+    const waitTime = Date.now() - payload.enqueuedTime;
+    this._totalTimeInQueue += waitTime;
+    if (this._minTimeInQueue === 0) {
+      this._minTimeInQueue = waitTime;
+    } else {
+      this._minTimeInQueue = Math.min(this._minTimeInQueue, waitTime);
+    }
+    this._maxTimeInQueue = Math.max(this._maxTimeInQueue, waitTime);
   }
 
 }