oracledb 6.9.0 → 7.0.0

package/lib/pool.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2016, 2024, Oracle and/or its affiliates.
+// Copyright (c) 2016, 2025, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -34,7 +34,7 @@ const settings = require('./settings.js');
 const nodbUtil = require('./util.js');
 const impl = require('./impl');
 const PoolStatistics = require('./poolStatistics.js');
-
+const traceHandler = require('./traceHandler.js');
 
 class Pool extends EventEmitter {
 
@@ -46,8 +46,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 +72,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 +92,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 +117,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 +129,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 +252,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,10 +276,21 @@ 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');
+    traceHandler.getTraceInstance()?.onPoolClose(this);
 
   }
 
@@ -391,7 +376,6 @@ class Pool extends EventEmitter {
   // queueTimeout milliseconds.
   //---------------------------------------------------------------------------
   async getConnection(a1) {
-    let poolMax;
     let options = {};
 
     // check arguments
@@ -412,131 +396,195 @@ 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);
+        traceHandler.getTraceInstance()?.onPoolWait(this);
 
-        // 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;
+          traceHandler.getTraceInstance()?.onPoolRequestTimeout(this);
+          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;
 
-    }
+    traceHandler.getTraceInstance()?.onPoolAcquire(this);
 
-    // 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 {
+    return request.conn;
+  }
 
-      // acquire connection from the pool
-      const conn = new Connection();
-      conn._impl = await this._impl.getConnection(options);
-      conn._pool = this;
+  //---------------------------------------------------------------------------
+  // _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) {
 
-      // 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();
-              }
-            });
-          });
-        } catch (err) {
-          await conn.close({ drop: true });
-          throw err;
-        }
+      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;
       }
+    }
 
-      // 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');
-        }
-      });
-
-      return (conn);
+    // reject _pendingRequests waiting to be processed
+    for (const request of this._pendingRequestQueue)
+      request.reject(errors.throwErr(errors.ERR_POOL_CLOSED));
+  }
 
+  //---------------------------------------------------------------------------
+  // _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) {
-      this._connectionsOut -= 1;
-      if (this._enableStatistics) {
-        this._totalFailedRequests += 1;
+      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();
+    }
+  }
+
+  //---------------------------------------------------------------------------
+  // _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;
       }
-      this.emit('_checkRequestQueue');
-      throw err;
     }
+  }
 
+  //---------------------------------------------------------------------------
+  // _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();
+      });
+    }
   }
 
   //---------------------------------------------------------------------------
@@ -747,7 +795,6 @@ class Pool extends EventEmitter {
     } finally {
       this._status = constants.POOL_STATUS_OPEN;
     }
-    this.emit('_checkRequestQueue');
   }
 
   //---------------------------------------------------------------------------
@@ -817,6 +864,15 @@ class Pool extends EventEmitter {
   get connectTraceConfig() {
     return this._impl && this._impl._getConnectTraceConfig();
   }
+
+  //---------------------------------------------------------------------------
+  // Symbol.asyncDispose
+  //
+  // Implement explicit resource management.
+  //---------------------------------------------------------------------------
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
 }
 
 nodbUtil.wrapFns(Pool.prototype, false,

package/lib/poolStatistics.js

@@ -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;

package/lib/resultset.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2016, 2023, Oracle and/or its affiliates.
+// Copyright (c) 2016, 2025, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -59,7 +59,7 @@ class ResultSet {
 
       // fetch all rows
       let rowsFetched = [];
-      while (true) {    // eslint-disable-line
+      while (true) {
         if (maxRows > 0 && fetchArraySize >= maxRows) {
           fetchArraySize = maxRows;
         }
@@ -206,12 +206,7 @@ class ResultSet {
     this._impl = resultSetImpl;
   }
 
-  //---------------------------------------------------------------------------
-  // close()
-  //
-  // Close the result set and make it unusable for further operations.
-  //---------------------------------------------------------------------------
-  async close() {
+  async _close() {
     errors.assertArgCount(arguments, 0, 0);
     errors.assert(this._impl && this._connection._impl, errors.ERR_INVALID_RS);
 
@@ -226,13 +221,15 @@ class ResultSet {
   }
 
   //---------------------------------------------------------------------------
-  // getRow()
+  // close()
   //
-  // Returns a single row to the caller from the result set, if one is
-  // available. Rows are buffered in a JavaScript array in order to avoid trips
-  // through the thread pool that would be required if implemented in C.
+  // Close the result set and make it unusable for further operations.
   //---------------------------------------------------------------------------
-  async getRow() {
+  async close() {
+    await this._close.apply(this, arguments);
+  }
+
+  async _getRow() {
     errors.assertArgCount(arguments, 0, 0);
     errors.assert(this._impl && this._connection._impl, errors.ERR_INVALID_RS);
 
@@ -252,15 +249,17 @@ class ResultSet {
   }
 
   //---------------------------------------------------------------------------
-  // getRows()
+  // getRow()
   //
-  // Check to see if any rows are in the JS buffer (which could result from
-  // interspersed calls to getRow() and getRows()). If no rows are in the
-  // buffer, the call is just proxied to the implementation layer. Otherwise,
-  // rows are pulled from the buffer and potentially concatenated with rows
-  // from calls to the implementation's getRows().
+  // Returns a single row to the caller from the result set, if one is
+  // available. Rows are buffered in a JavaScript array in order to avoid trips
+  // through the thread pool that would be required if implemented in C.
   //---------------------------------------------------------------------------
-  async getRows(numRows) {
+  async getRow() {
+    return await this._getRow.apply(this, arguments);
+  }
+
+  async _doGetRows(numRows) {
     let rowsNeeded;
 
     errors.assertArgCount(arguments, 0, 1);
@@ -282,7 +281,7 @@ class ResultSet {
     if (numRows == 0) {
       requestedRows = this._rowCache;
       const fetchArraySize = this._impl.fetchArraySize;
-      while (true) {  // eslint-disable-line
+      while (true) {
         const rows = await this._getRows(fetchArraySize);
         if (rows) {
           await this._processRows(rows, false);
@@ -312,6 +311,19 @@ class ResultSet {
     return requestedRows;
   }
 
+  //---------------------------------------------------------------------------
+  // getRows()
+  //
+  // Check to see if any rows are in the JS buffer (which could result from
+  // interspersed calls to getRow() and getRows()). If no rows are in the
+  // buffer, the call is just proxied to the implementation layer. Otherwise,
+  // rows are pulled from the buffer and potentially concatenated with rows
+  // from calls to the implementation's getRows().
+  //---------------------------------------------------------------------------
+  async getRows() {
+    return await this._doGetRows.apply(this, arguments);
+  }
+
   //---------------------------------------------------------------------------
   // metaData()
   //
@@ -358,6 +370,15 @@ class ResultSet {
     };
   }
 
+  //---------------------------------------------------------------------------
+  // Symbol.asyncDispose
+  //
+  // Implement explicit resource management.
+  //---------------------------------------------------------------------------
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
+
 }
 
 nodbUtil.wrapFns(ResultSet.prototype, errors.ERR_BUSY_RS,

package/lib/settings.js

@@ -62,6 +62,7 @@ class Settings {
     this.configProviderCacheTimeout = 86400;
     this.thin = true;
     this.thinDriverInitialized = false;
+    this.thickModeDSNPassthrough = true;
     this.createFetchTypeMap(this.fetchAsString, this.fetchAsBuffer);
     this.fetchTypeHandler = undefined;
     this.dbObjectTypeHandler = undefined;

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);