oracledb 6.8.0 → 6.10.0

package/lib/pool.js

@@ -35,7 +35,6 @@ const nodbUtil = require('./util.js');
 const impl = require('./impl');
 const PoolStatistics = require('./poolStatistics.js');
 
-
 class Pool extends EventEmitter {
 
   constructor() {
@@ -46,8 +45,12 @@ class Pool extends EventEmitter {
     this._enableStatistics = false;
     this._timeOfReset = this._createdDate = Date.now();
     this._sessionCallback = undefined;
-    this._connRequestQueue = [];
+    this._pendingRequestQueue = new Set();
     this._connectionClass = settings.connectionClass;
+    this._bgRequestWaiter = null;
+    this._bgRequestId = 0;
+    this._processing = 0;
+    this._ensureNoPendingRequests = null;
   }
 
   //---------------------------------------------------------------------------
@@ -68,36 +71,6 @@ class Pool extends EventEmitter {
     }
   }
 
-  //---------------------------------------------------------------------------
-  // _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
-  // 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.
-  //---------------------------------------------------------------------------
-  _checkRequestQueue() {
-    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();
-    }
-  }
-
-  //---------------------------------------------------------------------------
   // _enableStats (DEPRECATED)
   //
   // Property for whether statistics are enabled on the pool.
@@ -118,7 +91,7 @@ class Pool extends EventEmitter {
     this._totalFailedRequests = 0;
     this._totalRequestsRejected = 0;
     this._totalRequestTimeouts = 0;
-    this._maximumQueueLength = this._connRequestQueue.length;
+    this._maximumQueueLength = this._pendingRequestQueue.size;
     this._totalTimeInQueue = 0;
     this._minTimeInQueue = 0;
     this._maxTimeInQueue = 0;
@@ -143,9 +116,7 @@ class Pool extends EventEmitter {
     this._status = constants.POOL_STATUS_OPEN;
     this._connectionsOut = 0;
     this._poolAlias = poolAlias;
-
-    // register event handler for when request queue should be checked
-    this.on('_checkRequestQueue', this._checkRequestQueue);
+    this._bgRequestHandler();
 
     this._resetStatistics();
 
@@ -157,8 +128,8 @@ class Pool extends EventEmitter {
   // Update pool wait statistics after a connect request has spent some time in
   // the queue.
   //---------------------------------------------------------------------------
-  _updateWaitStatistics(payload) {
-    const waitTime = Date.now() - payload.enqueuedTime;
+  _updateWaitStatistics(request) {
+    const waitTime = Date.now() - request.enqueuedTime;
     this._totalTimeInQueue += waitTime;
     if (this._minTimeInQueue === 0) {
       this._minTimeInQueue = waitTime;
@@ -280,10 +251,12 @@ class Pool extends EventEmitter {
     // if the pool is draining/reconfiguring/closed, throw an appropriate error
     this._checkPoolOpen(false);
 
+    if (forceClose)
+      this._status = constants.POOL_STATUS_DRAINING;
+
     // wait for the pool to become empty or for the drain timeout to expire
     // (whichever comes first)
     if (drainTime > 0) {
-      this._status = constants.POOL_STATUS_DRAINING;
       await new Promise(resolve => {
         const timeout = setTimeout(() => {
           this.removeAllListeners('_allCheckedIn');
@@ -302,9 +275,19 @@ class Pool extends EventEmitter {
       errors.throwErr(errors.ERR_POOL_HAS_BUSY_CONNECTIONS);
     }
 
+    // ensure no connection requests are being processed before proceeding to
+    // close the pool (required for thick mode)
+    if (this._processing != 0)
+      await new Promise(resolve => this._ensureNoPendingRequests = resolve);
+
     // close the pool
     await this._impl.close();
     this._status = constants.POOL_STATUS_CLOSED;
+
+    // stop the _bgRequestWaiter waiting in background
+    if (this._bgRequestWaiter)
+      this._bgRequestWaiter();
+
     this.emit('_afterPoolClose');
 
   }
@@ -391,7 +374,6 @@ class Pool extends EventEmitter {
   // queueTimeout milliseconds.
   //---------------------------------------------------------------------------
   async getConnection(a1) {
-    let poolMax;
     let options = {};
 
     // check arguments
@@ -412,131 +394,191 @@ class Pool extends EventEmitter {
       this._totalConnectionRequests += 1;
     }
 
-    // getting the poolMax setting on the pool may fail if the pool is no
-    // longer valid
-    try {
-      poolMax = this.poolMax;
-    } catch (err) {
-      if (this._enableStatistics) {
-        this._totalFailedRequests += 1;
-      }
-      throw err;
-    }
-
-    while (this._connectionsOut >= poolMax ||
-        this.status === constants.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._enableStatistics) {
-          this._totalRequestsRejected += 1;
+    if (this._bgRequestId == Number.MAX_SAFE_INTEGER)
+      this._bgRequestId = 0;
+
+    const request = {
+      id: this._bgRequestId++,
+      options: options,
+      conn: null,
+      isWaiting: true,
+      error: null,
+      timeoutHandle: null,
+      enqueuedTime: Date.now(),
+      wasQueued: false
+    };
+
+    // This promise acquires a connection from pool
+    const promiseToAcquire = new Promise((resolve, reject) => {
+      request.resolve = resolve;
+      request.reject = reject;
+
+      // If we haven't reached poolMax we shouldn't add to queue(honor queueMax)
+      if (this._connectionsOut < this.poolMax) {
+        this._processRequest(request);
+      } else {
+        // Ensure queueMax is not exceeded
+        if (this._pendingRequestQueue.size == this._queueMax) {
+          if (this._enableStatistics)
+            this._totalRequestsRejected += 1;
+          return reject(errors.getErr(errors.ERR_QUEUE_MAX_EXCEEDED,
+            this._queueMax));
         }
-        errors.throwErr(errors.ERR_QUEUE_MAX_EXCEEDED, this._queueMax);
-      }
 
-      // if too many connections are out, wait until room is made available or
-      // the queue timeout expires
-      await new Promise((resolve, reject) => {
-
-        // set up a payload which will be added to the queue for processing
-        const payload = { resolve: resolve, reject: reject };
-
-        // if using a queue timeout, establish the timeout so that when it
-        // expires the payload will be removed from the queue and an exception
-        // thrown
-        if (this._queueTimeout !== 0) {
-          payload.timeoutHandle = setTimeout(() => {
-            const ix = this._connRequestQueue.indexOf(payload);
-            if (ix >= 0) {
-              this._connRequestQueue.splice(ix, 1);
-            }
-            if (this._enableStatistics) {
-              this._totalRequestTimeouts += 1;
-              this._updateWaitStatistics(payload);
-            }
-            try {
-              errors.throwErr(errors.ERR_CONN_REQUEST_TIMEOUT,
-                this._queueTimeout);
-            } catch (err) {
-              reject(err);
-            }
-          }, this._queueTimeout);
-        }
+        // Queueing our request
+        request.wasQueued = true;
+        this._pendingRequestQueue.add(request);
 
-        // add payload to the queue
-        this._connRequestQueue.push(payload);
         if (this._enableStatistics) {
-          payload.enqueuedTime = Date.now();
           this._totalRequestsEnqueued += 1;
           this._maximumQueueLength = Math.max(this._maximumQueueLength,
-            this._connRequestQueue.length);
+            this._pendingRequestQueue.size);
         }
+      }
+    });
+
+    // This promise will timeout after queueTimeout seconds
+    const promiseToTimeout = new Promise ((_, reject) => {
+      if (this._queueTimeout > 0)
+        request.timeoutHandle = setTimeout(() => {
+          request.isWaiting = false;
+          this._pendingRequestQueue.delete(request);
+          if (this.enableStatistics)
+            this._totalRequestTimeouts += 1;
+          reject(errors.getErr(errors.ERR_CONN_REQUEST_TIMEOUT,
+            this._queueTimeout));
+        }, this._queueTimeout);
+    });
+
+    // Earliest promise to resolve/reject gets fulfilled
+    try {
+      await Promise.race([promiseToAcquire, promiseToTimeout]);
+    } catch (err) {
+      request.error = err;
+    }
 
-      });
+    clearTimeout(request.timeoutHandle);
+    // Update time waited by request
+    if (this._enableStatistics && request.wasQueued)
+      this._updateWaitStatistics(request);
 
-      // check if pool is draining/closed after delay has
-      // completed and throw an appropriate error
-      this._checkPoolOpen(true);
+    // Request failed to be fulfilled (errored/timeout)
+    if (request.error)
+      throw request.error;
 
+    return request.conn;
+  }
+
+  //---------------------------------------------------------------------------
+  // _bgRequestHandler()
+  //
+  // This method handles the queuing of all pending requests and processes them
+  // depending on the open connections and if the request is still waiting.
+  //---------------------------------------------------------------------------
+  async _bgRequestHandler() {
+    while (this.status != constants.POOL_STATUS_DRAINING ||
+          this.status != constants.POOL_STATUS_CLOSED) {
+
+      const request = this._pendingRequestQueue.values().next().value;
+      if (request && (this._connectionsOut < this.poolMax)) {
+        this._processRequest(request);
+      } else  {
+        await new Promise((resolve) => {
+          this._bgRequestWaiter = resolve;
+        });
+        this._bgRequestWaiter = null;
+      }
     }
 
-    // room is available in the queue, so proceed to acquire a connection from
-    // the pool; adjust the connections out immediately in order to ensure that
-    // another attempt doesn't proceed while this one is underway
-    this._connectionsOut += 1;
-    try {
+    // reject _pendingRequests waiting to be processed
+    for (const request of this._pendingRequestQueue)
+      request.reject(errors.throwErr(errors.ERR_POOL_CLOSED));
+  }
 
-      // acquire connection from the pool
-      const conn = new Connection();
-      conn._impl = await this._impl.getConnection(options);
+  //---------------------------------------------------------------------------
+  // _processRequest()
+  //
+  // Method called to process a connection request and return the required
+  // 'connection'/'error returned by DB' if the client is still waiting.
+  //---------------------------------------------------------------------------
+  async _processRequest(request) {
+    const conn = new Connection();
+    try {
+      this._processing += 1;
+      this._connectionsOut += 1;
+      this._pendingRequestQueue.delete(request);
+      conn._impl = await this._impl.getConnection(request.options);
       conn._pool = this;
+      await this._tagFixup(conn, request.options.tag);
+      if (request.isWaiting)
+        request.conn = conn;
+      else
+        await conn.close({});
+      request.resolve();
+    } catch (err) {
+      if (request.isWaiting) {
+        if (this._enableStatistics)
+          this._totalFailedRequests += 1;
+        request.reject(err);
+      }
+      // Request errored, so we have some space in pool
+      this._release(conn._impl, request.options);
+    } finally {
+      this._processing -= 1;
+      if (this.status == constants.POOL_STATUS_DRAINING &&
+          this._processing == 0 && this._ensureNoPendingRequests)
+        this._ensureNoPendingRequests();
+    }
+  }
 
-      // 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; if the callback fails, close the
-      // connection and remove it from the pool
-      const requestedTag = options.tag || "";
-      if (typeof this.sessionCallback === 'function' &&
-          (conn._impl._newSession || conn.tag != requestedTag)) {
-        try {
-          await new Promise((resolve, reject) => {
-            this.sessionCallback(conn, requestedTag, function(err) {
-              if (err) {
-                reject(err);
-              } else {
-                resolve();
-              }
-            });
+  //---------------------------------------------------------------------------
+  // _tagFixup()
+  //
+  // Method to check if requested tag matches the connection's tag.
+  // If it does not match the callback function is invoked.
+  //---------------------------------------------------------------------------
+  async _tagFixup(conn, tag) {
+    const requestedTag = tag || "";
+    if (typeof this.sessionCallback === 'function' &&
+        (conn._impl._newSession ||
+         conn.tag != requestedTag)) {
+      try {
+        await new Promise((resolve, reject) => {
+          this.sessionCallback(conn, requestedTag, function(err) {
+            if (err) {
+              reject(err);
+            } else {
+              resolve();
+            }
           });
-        } catch (err) {
-          await conn.close({ drop: true });
-          throw err;
-        }
+        });
+      } catch (err) {
+        await conn.close({ drop: true });
+        throw err;
       }
+    }
+  }
 
-      // when connection is closed, check to see if another request should be
-      // processed and update any stats, as needed
-      conn.on('_afterConnClose', () => {
-        this._connectionsOut -= 1;
-        this.emit('_checkRequestQueue');
-        if (this._connectionsOut == 0) {
-          this.emit('_allCheckedIn');
-        }
+  //---------------------------------------------------------------------------
+  // _release()
+  //
+  // Method called by 'close() in connection.js after a release'/'error in
+  // _processRequest' to decrease connectionsOut & wake up _bgRequestWaiter
+  //---------------------------------------------------------------------------
+  async _release(impl, options) {
+    this._connectionsOut -= 1;
+    try {
+      // Directly close the connection using the underlying connection impl
+      if (impl)
+        await impl.close(options);
+    } finally {
+      if (this._connectionsOut == 0)
+        this.emit('_allCheckedIn');
+      setImmediate(() => {
+        if (this._pendingRequestQueue.size > 0 && this._bgRequestWaiter)
+          this._bgRequestWaiter();
       });
-
-      return (conn);
-
-    } catch (err) {
-      this._connectionsOut -= 1;
-      if (this._enableStatistics) {
-        this._totalFailedRequests += 1;
-      }
-      this.emit('_checkRequestQueue');
-      throw err;
     }
-
   }
 
   //---------------------------------------------------------------------------
@@ -653,6 +695,15 @@ class Pool extends EventEmitter {
     return this._impl.getPoolTimeout();
   }
 
+  //---------------------------------------------------------------------------
+  // maxLifetimeSession
+  //
+  // Property for the max allowed lifetime of a session in the pool.
+  //---------------------------------------------------------------------------
+  get maxLifetimeSession() {
+    return this._impl.getMaxLifetimeSession();
+  }
+
   //---------------------------------------------------------------------------
   // queueMax
   //
@@ -693,6 +744,7 @@ class Pool extends EventEmitter {
     errors.assertParamPropUnsignedInt(options, 1, "poolIncrement");
     errors.assertParamPropInt(options, 1, "poolPingInterval");
     errors.assertParamPropUnsignedInt(options, 1, "poolTimeout");
+    errors.assertParamPropUnsignedInt(options, 1, "maxLifetimeSession");
     errors.assertParamPropUnsignedInt(options, 1, "stmtCacheSize");
     errors.assertParamPropBool(options, 1, "sodaMetaDataCache");
 
@@ -708,7 +760,8 @@ class Pool extends EventEmitter {
     this._status = constants.POOL_STATUS_RECONFIGURING;
     try {
       // poolMin/poolMax/poolIncrement/poolPingInterval/poolTimeout/
-      // poolMaxPerShard/stmtCacheSize/sodaMetaDataCache parameters
+      // poolMaxPerShard/stmtCacheSize/sodaMetaDataCache/maxLifetimeSession
+      // parameters
       await this._impl.reconfigure(options);
 
       // pool JS parameters: queueMax, queueTimeout, enableStatistics,
@@ -736,7 +789,6 @@ class Pool extends EventEmitter {
     } finally {
       this._status = constants.POOL_STATUS_OPEN;
     }
-    this.emit('_checkRequestQueue');
   }
 
   //---------------------------------------------------------------------------

package/lib/poolStatistics.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2021, 2024, Oracle and/or its affiliates.
+// Copyright (c) 2021, 2025, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -54,7 +54,7 @@ class PoolStatistics {
     this.rejectedRequests = pool._totalRequestsRejected;
     this.requestTimeouts = pool._totalRequestTimeouts;
     this.maximumQueueLength = pool._maximumQueueLength;
-    this.currentQueueLength = pool._connRequestQueue.length;
+    this.currentQueueLength = pool._pendingRequestQueue.size;
     this.timeInQueue = pool._totalTimeInQueue;
     this.minimumTimeInQueue = pool._minTimeInQueue;
     this.maximumTimeInQueue = pool._maxTimeInQueue;
@@ -74,6 +74,7 @@ class PoolStatistics {
     this.poolPingInterval = pool.poolPingInterval;
     this.poolPingTimeout = pool.poolPingTimeout;
     this.poolTimeout = pool.poolTimeout;
+    this.maxLifetimeSession = pool.maxLifetimeSession;
     this.queueMax = pool.queueMax;
     this.queueTimeout = pool.queueTimeout;
     this.sodaMetaDataCache = pool.sodaMetaDataCache;
@@ -127,6 +128,7 @@ class PoolStatistics {
     console.log('...poolPingInterval (seconds):', this.poolPingInterval);
     console.log('...poolPingTimeout (milliseconds):', this.poolPingTimeout);
     console.log('...poolTimeout (seconds):', this.poolTimeout);
+    console.log('...maxLifetimeSession (seconds):', this.maxLifetimeSession);
     console.log('...queueMax:', this.queueMax);
     console.log('...queueTimeout (milliseconds):', this.queueTimeout);
     console.log('...sessionCallback:', this.sessionCallback);

package/lib/sodaCollection.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2018, 2023, Oracle and/or its affiliates.
+// Copyright (c) 2018, 2025, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -34,6 +34,10 @@ const settings = require('./settings.js');
 
 class SodaCollection {
 
+  constructor(sodaDb) {
+    this._sodaDb = sodaDb;
+  }
+
   //---------------------------------------------------------------------------
   // createIndex()
   //
@@ -84,7 +88,7 @@ class SodaCollection {
   //---------------------------------------------------------------------------
   find() {
     errors.assertArgCount(arguments, 0, 0);
-    const op = new SodaOperation();
+    const op = new SodaOperation(this._sodaDb);
     op._impl = this._impl.find();
     return op;
   }
@@ -111,7 +115,7 @@ class SodaCollection {
 
     const actualDocs = Array(docs.length);
     for (let i = 0; i < docs.length; i++) {
-      actualDocs[i] = nodbUtil.verifySodaDoc(docs[i]);
+      actualDocs[i] = this._sodaDb._verifySodaDoc(docs[i]);
     }
 
     const options = {autoCommit: settings.autoCommit};
@@ -140,7 +144,7 @@ class SodaCollection {
 
     const actualDocs = Array(docs.length);
     for (let i = 0; i < docs.length; i++) {
-      actualDocs[i] = nodbUtil.verifySodaDoc(docs[i]);
+      actualDocs[i] = this._sodaDb._verifySodaDoc(docs[i]);
     }
 
     const docImpls = await this._impl.insertManyAndGet(actualDocs, options);
@@ -159,7 +163,7 @@ class SodaCollection {
   //---------------------------------------------------------------------------
   async insertOne(content) {
     errors.assertArgCount(arguments, 1, 1);
-    content = nodbUtil.verifySodaDoc(content);
+    content = this._sodaDb._verifySodaDoc(content);
     const options = {autoCommit: settings.autoCommit};
     await this._impl.insertOne(content, options);
   }
@@ -174,7 +178,7 @@ class SodaCollection {
     const options = {autoCommit: settings.autoCommit};
 
     errors.assertArgCount(arguments, 1, 2);
-    content = nodbUtil.verifySodaDoc(content);
+    content = this._sodaDb._verifySodaDoc(content);
     if (arguments.length == 2) {
       errors.assertParamValue(nodbUtil.isObject(a2), 2);
       if (a2.hint !== undefined) {
@@ -223,7 +227,7 @@ class SodaCollection {
   //---------------------------------------------------------------------------
   async save(content) {
     errors.assertArgCount(arguments, 1, 1);
-    content = nodbUtil.verifySodaDoc(content);
+    content = this._sodaDb._verifySodaDoc(content);
     const options = {autoCommit: settings.autoCommit};
     await this._impl.save(content, options);
   }
@@ -236,7 +240,7 @@ class SodaCollection {
   //---------------------------------------------------------------------------
   async saveAndGet(content, a2) {
     errors.assertArgCount(arguments, 1, 2);
-    content = nodbUtil.verifySodaDoc(content);
+    content = this._sodaDb._verifySodaDoc(content);
     const options = {autoCommit: settings.autoCommit};
     if (arguments.length == 2) {
       errors.assertParamValue(nodbUtil.isObject(a2), 2);

package/lib/sodaDatabase.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2018, 2023, Oracle and/or its affiliates.
+// Copyright (c) 2018, 2025, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -32,6 +32,7 @@ const SodaDocument = require('./sodaDocument.js');
 const errors = require('./errors.js');
 const nodbUtil = require('./util.js');
 const settings = require('./settings.js');
+const transformer = require('./transformer.js');
 
 class SodaDatabase {
 
@@ -64,7 +65,7 @@ class SodaDatabase {
       }
     }
 
-    const coll = new SodaCollection();
+    const coll = new SodaCollection(this);
     coll._impl = await this._impl.createCollection(name, options);
     return coll;
   }
@@ -76,6 +77,7 @@ class SodaDatabase {
   //---------------------------------------------------------------------------
   createDocument(content, a2) {
     let options = {};
+    let inContent;
 
     errors.assertArgCount(arguments, 1, 2);
     errors.assertParamValue(Buffer.isBuffer(content) ||
@@ -87,14 +89,20 @@ class SodaDatabase {
       errors.assertParamPropString(options, 2, "mediaType");
     }
 
-    if (typeof content === 'string') {
-      content = Buffer.from(content);
-    } else if (nodbUtil.isObject(content)) {
-      content = Buffer.from(JSON.stringify(content));
+    // native JSON support for SODA is available from Oracle Client 23.4
+    if (this._impl.supportsJson &&
+      (!options.mediaType || options.mediaType === 'application/json')) {
+      inContent = transformer.transformJsonValue(content);
+    } else if (Buffer.isBuffer(content)) {
+      inContent = content;
+    } else if (typeof content === 'string') {
+      inContent = Buffer.from(content);
+    } else {
+      inContent = Buffer.from(JSON.stringify(content));
     }
 
     const doc = new SodaDocument();
-    doc._impl = this._impl.createDocument(content, options);
+    doc._impl = this._impl.createDocument(inContent, options);
     return doc;
   }
 
@@ -133,12 +141,31 @@ class SodaDatabase {
     const options = {autoCommit: settings.autoCommit};
     const collImpl = await this._impl.openCollection(name, options);
     if (collImpl) {
-      const coll = new SodaCollection();
+      const coll = new SodaCollection(this);
       coll._impl = collImpl;
       return coll;
     }
   }
 
+  //---------------------------------------------------------------------------
+  // _verifySodaDoc()
+  //
+  // Verifies the content passed is valid for a SodaDocument object.
+  //---------------------------------------------------------------------------
+  _verifySodaDoc(content) {
+    // check if the content is a sodaDocument object
+    if (content != null && content._sodaDocumentMarker)
+      return content._impl;
+    errors.assertParamValue(nodbUtil.isObject(content), 1);
+
+    // JSON is assumed, if you pass in the content
+    // starting from Oracle Client 23ai onwards, JSON in SODA is supported
+    if (this._impl._supportsJson)
+      return transformer.transformJsonValue(content);
+
+    return Buffer.from(JSON.stringify(content));
+  }
+
 }
 
 nodbUtil.wrapFns(SodaDatabase.prototype,