oracledb 6.8.0 → 6.10.0

package/README.md

@@ -1,10 +1,10 @@
-# node-oracledb version 6.8.0
+# node-oracledb version 6.10.0 <img src="https://img.shields.io/npm/v/oracledb.svg" alt="oracledb"/>  <img src="https://img.shields.io/npm/dm/oracledb.svg" alt="oracledb"/>
 
 The node-oracledb add-on for Node.js powers high performance Oracle Database
 applications.  Applications can be written in TypeScript, or directly in
 JavaScript.
 
-Use node-oracledb 6.8.0 to connect Node.js 14.6, or later, to Oracle
+Use node-oracledb 6.10.0 to connect Node.js 14.17, or later, to Oracle
 Database.  Older versions of node-oracledb may work with older versions of
 Node.js.
 
@@ -16,8 +16,42 @@ It is stable, well documented, and has a comprehensive test suite.
 
 ## Installation
 
+Run `npm install oracledb`
+
 See [Getting Started with Node-oracledb][1] and [Quick Start Node-oracledb Installation][2].
 
+## Dependencies and Interoperability
+
+- Node.js versions 14.17 and later.
+
+  Pre-built packages are available on [npm][14] and other mirror repositories.
+
+  Source code is also available.
+
+  Previous versions of node-oracledb supported older Node.js versions.
+
+- Oracle Client libraries are *optional* starting from node-oracledb 6.0.
+  Older versions of node-oracledb require Oracle Client libraries.
+
+  **Thin mode**: By default node-oracledb (from version 6.0 onwards) runs in a
+  'Thin' mode which connects directly to Oracle Database.
+
+  **Thick mode**: Some advanced Oracle Database functionality is currently only
+  available when optional Oracle Client libraries are loaded by
+  node-oracledb. Libraries are available in the free [Oracle Instant
+  Client][15] packages. Node-oracledb can use Oracle Client
+  libraries 11.2 through 23ai.
+
+- Oracle Database
+
+  **Thin mode**: Oracle Database 12.1 (or later) is required.
+
+  **Thick mode**: Oracle Database 9.2 (or later) is required, depending on the
+  Oracle Client library version.  Oracle Database's standard client-server
+  version interoperability allows connection to both older and newer
+  databases. For example when node-oracledb uses Oracle Client 19c libraries,
+  then it can connect to Oracle Database 11.2 or later.
+
 ## Documentation
 
 See [Documentation for the Oracle Database Node.js Add-on][9] and the [release
@@ -34,7 +68,7 @@ to join Slack][6]).
 
 ## <a name="testing"></a> Tests
 
-To run the test suite see [test/README][11].
+To run the test suite, see [test/README][11].
 
 ## Contributing
 
@@ -83,3 +117,5 @@ limitations under the License.
 [11]: https://github.com/oracle/node-oracledb/blob/main/test/README.md
 [12]: https://github.com/oracle/node-oracledb/blob/main/CONTRIBUTING.md
 [13]: https://github.com/oracle/node-oracledb/blob/main/SECURITY.md
+[14]: https://www.npmjs.com/package/oracledb
+[15]: https://www.oracle.com/database/technologies/instant-client.html

package/build/Release/oracledb-6.10.0-darwin-arm64.node-buildinfo.txt

@@ -0,0 +1 @@
+oracledb-6.10.0-darwin-arm64.node v22.17.1 71ba4e79b3fb8ffe6191e84eb0422c9bdfbb6c9d 8b14d5980d7d6116abb8865c7baed9e458698dbf Thu, 09 Oct 2025 15:26:22 GMT

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

@@ -0,0 +1 @@
+oracledb-6.10.0-darwin-x64.node v20.11.1 71ba4e79b3fb8ffe6191e84eb0422c9bdfbb6c9d 8b14d5980d7d6116abb8865c7baed9e458698dbf Thu, 09 Oct 2025 15:33:20 GMT

package/build/Release/oracledb-6.10.0-js-buildinfo.txt

@@ -0,0 +1 @@
+71ba4e79b3fb8ffe6191e84eb0422c9bdfbb6c9d

package/build/Release/oracledb-6.10.0-linux-arm64.node-buildinfo.txt

@@ -0,0 +1 @@
+oracledb-6.10.0-linux-arm64.node v20.19.2 71ba4e79b3fb8ffe6191e84eb0422c9bdfbb6c9d 8b14d5980d7d6116abb8865c7baed9e458698dbf Thu, 09 Oct 2025 13:43:20 GMT

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

@@ -0,0 +1 @@
+oracledb-6.10.0-linux-x64.node v22.16.0 71ba4e79b3fb8ffe6191e84eb0422c9bdfbb6c9d 8b14d5980d7d6116abb8865c7baed9e458698dbf Thu, 09 Oct 2025 13:31:19 GMT

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

@@ -0,0 +1 @@
+oracledb-6.10.0-win32-x64.node v22.17.1 71ba4e79b3fb8ffe6191e84eb0422c9bdfbb6c9d 8b14d5980d7d6116abb8865c7baed9e458698dbf Thu, 09 Oct 2025 13:31:10 GMT

package/lib/aqDeqOptions.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2019, 2023, Oracle and/or its affiliates.
+// Copyright (c) 2019, 2025, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -74,6 +74,23 @@ class AqDeqOptions {
     this._impl.setCorrelation(value);
   }
 
+  //---------------------------------------------------------------------------
+  // deliveryMode
+  //
+  // Property for the delivery mode to use for dequeuing messages.
+  //---------------------------------------------------------------------------
+  get deliveryMode() {
+    return null;
+  }
+
+  set deliveryMode(value) {
+    errors.assertPropValue(value === constants.AQ_MSG_DELIV_MODE_PERSISTENT ||
+      value === constants.AQ_MSG_DELIV_MODE_BUFFERED ||
+      value === constants.AQ_MSG_DELIV_MODE_PERSISTENT_OR_BUFFERED,
+    "deliveryMode");
+    this._impl.setDeliveryMode(value);
+  }
+
   //---------------------------------------------------------------------------
   // mode
   //

package/lib/aqMessage.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2019, 2022, Oracle and/or its affiliates.
+// Copyright (c) 2019, 2025, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -48,6 +48,15 @@ class AqMessage {
     return this._impl.getDelay();
   }
 
+  //---------------------------------------------------------------------------
+  // enqTime
+  //
+  // Property to indicate the enqueue time for the message.
+  //---------------------------------------------------------------------------
+  get enqTime() {
+    return this._impl.getEnqTime();
+  }
+
   //---------------------------------------------------------------------------
   // deliveryMode
   //

package/lib/aqQueue.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2019, 2024, Oracle and/or its affiliates.
+// Copyright (c) 2019, 2025, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -87,17 +87,21 @@ class AqQueue {
       }
     }
 
-    // validate payload
+    // validate payload/queue type compatibility
     if (this._isJson) {
       message.payload = transformer.transformJsonValue(payload);
-    } else if (typeof payload === 'string') {
+    } else if (typeof payload === 'string' || Buffer.isBuffer(payload)) {
       message.payload = Buffer.from(payload);
-    } else if (Buffer.isBuffer(payload)) {
-      message.payload = payload;
-    } else {
+    } else if (this._payloadType == types.DB_TYPE_OBJECT) {
+      if (!(payload instanceof BaseDbObject) ||
+        (this._payloadTypeName !== payload._impl._objType.name))
+        errors.throwErr(errors.ERR_PAYLOAD_CANNOT_BE_ENQUEUED);
       message.payload = payload._impl;
+    } else {
+      errors.throwErr(errors.ERR_PAYLOAD_CANNOT_BE_ENQUEUED);
     }
 
+
     // validate options, if applicable
     if (message.correlation !== undefined) {
       errors.assertParamPropValue(typeof message.correlation === 'string', 1,

package/lib/configProviders/file.js

@@ -0,0 +1,72 @@
+// Copyright (c) 2025, Oracle and/or its affiliates.
+
+//-----------------------------------------------------------------------------
+//
+// This software is dual-licensed to you under the Universal Permissive License
+// (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
+// 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose
+// either license.
+//
+// If you elect to accept the software under the Apache License, Version 2.0,
+// the following applies:
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+//-----------------------------------------------------------------------------
+const fs = require('fs').promises;
+const util = require('node:util');
+const oracledb = require('oracledb');
+class locaJson {
+
+  constructor(provider_arg, urlExtendedPart) {
+    const params = new URLSearchParams(urlExtendedPart);
+    this.paramMap = new URLSearchParams([...params].map(([key, value]) => [key.toLowerCase(), value])); //parse the extended part and store parameters in Map
+    this.paramMap.set('filepath', provider_arg);
+  }
+  //---------------------------------------------------------------------------
+  // init()
+  //
+  // Require/import modules from ociobject
+  //---------------------------------------------------------------------------
+  init() {
+  // nothing to require
+  }
+  async returnConfig() {
+    const alias = this.paramMap.get('alias');
+    // Read input file
+    const data = Buffer.from(await fs.readFile(this.paramMap.get("filepath"), { encoding: 'utf8', flag: 'r' }));
+    // Converting to JSON
+    const listofAliases = JSON.parse(data);
+    if (alias) {
+      this.obj = listofAliases[alias];
+    } else {
+      this.obj = listofAliases;
+    }
+    return this.obj;
+  }
+}
+//---------------------------------------------------------------------------
+//  hookFn()
+//  hookFn will get registered to the driver while loading the plugins
+//---------------------------------------------------------------------------
+async function hookFn(args) {
+  const configProvider = new locaJson(args.provider_arg, args.urlExtendedPart);
+  try {
+    configProvider.init();
+  } catch (err) {
+    const errmsg = util.format('Centralized Config Provider failed to load required libraries. Please install the required libraries.\n %s', err.message);
+    throw new Error(errmsg);
+  }
+  return [await configProvider.returnConfig(), configProvider.credential];
+}
+oracledb.registerConfigurationProviderHook('file', hookFn);

package/lib/connection.js

@@ -110,6 +110,8 @@ class Connection extends EventEmitter {
     options.connection = this;
     if (options.keepInStmtCache === undefined)
       options.keepInStmtCache = true;
+    if (options.suspendOnSuccess === undefined)
+      options.suspendOnSuccess = false;
     settings.addToOptions(options,
       "autoCommit",
       "dbObjectAsPojo",
@@ -138,7 +140,12 @@ class Connection extends EventEmitter {
         }
         return (proxy);
       } else if (initialValue !== undefined) {
-        Object.assign(this, initialValue);
+        for (const attr of objType.attributes) {
+          const value = initialValue[attr.name];
+          if (value !== undefined) {
+            this._setAttrValue(attr, value);
+          }
+        }
       }
     };
     DbObject.prototype = Object.create(BaseDbObject.prototype);
@@ -591,6 +598,11 @@ class Connection extends EventEmitter {
       outOptions.keepInStmtCache = options.keepInStmtCache;
     }
 
+    if (options.suspendOnSuccess !== undefined) {
+      errors.assertParamPropBool(options, 2, "suspendOnSucess");
+      outOptions.suspendOnSuccess = options.suspendOnSuccess;
+    }
+
     // handle options specific to executeMany()
     if (inExecuteMany) {
 
@@ -701,6 +713,29 @@ class Connection extends EventEmitter {
     this._impl.setAction(value);
   }
 
+  //---------------------------------------------------------------------------
+  // beginSessionlessTransaction()
+  //
+  // Begin a new sessionless transaction with provided transactionId.
+  // If transactionId wasn't provided a random-generated transactionId will be
+  // used and returned.
+  //---------------------------------------------------------------------------
+  async beginSessionlessTransaction(options = {}) {
+    errors.assertArgCount(arguments, 0, 1);
+    errors.assertParamValue(nodbUtil.isObject(options), 1);
+    if (options.transactionId !== undefined)
+      errors.assertParamPropValue(
+        nodbUtil.isTransactionId(options.transactionId), 1, 'transactionId');
+    errors.assertParamPropUnsignedIntNonZero(options, 1, 'timeout');
+    errors.assertParamPropBool(options, 1, 'deferRoundTrip');
+    const normalizedTransactionId =
+      nodbUtil.normalizeTransactionId(options.transactionId);
+    const {timeout = 60, deferRoundTrip = false} = options;
+    await this._impl.startSessionlessTransaction(normalizedTransactionId,
+      timeout, constants.TPC_BEGIN_NEW, deferRoundTrip);
+    return normalizedTransactionId;
+  }
+
   //---------------------------------------------------------------------------
   // breakExecution()
   //
@@ -792,7 +827,12 @@ class Connection extends EventEmitter {
 
     this._closing = true;
     try {
-      await this._impl.close(options);
+      // If connection is part of a pool, notify the pool of its availability
+      if (this._pool) {
+        await this._pool._release(this._impl, options);
+      } else {
+        await this._impl.close(options);
+      }
     } finally {
       this._closing = false;
     }
@@ -804,7 +844,6 @@ class Connection extends EventEmitter {
       }
     }
     this._dbObjectClasses.clear();
-    this.emit('_afterConnClose');
   }
 
   //---------------------------------------------------------------------------
@@ -1255,6 +1294,18 @@ class Connection extends EventEmitter {
     this._impl.setInternalName(value);
   }
 
+  //---------------------------------------------------------------------------
+  // ltxid
+  //
+  // Property for identifying the logical transaction ID to avoid duplicate
+  // transactions. Used with Oracle Transaction Guard.
+  //---------------------------------------------------------------------------
+  get ltxid() {
+    if (this._impl)
+      return this._impl.getLTXID();
+    return undefined;
+  }
+
   //--------------------------------------------------------------------------
   // isHealthy()
   //
@@ -1407,6 +1458,25 @@ class Connection extends EventEmitter {
     return (stream);
   }
 
+  //---------------------------------------------------------------------------
+  // resumeSessionlessTransaction()
+  //
+  // Resume an existing sessionlesss transaction using given transactionId
+  //---------------------------------------------------------------------------
+  async resumeSessionlessTransaction(transactionId, options = {}) {
+    errors.assertArgCount(arguments, 1, 2);
+    errors.assertParamValue(nodbUtil.isTransactionId(transactionId), 1);
+    errors.assertParamValue(nodbUtil.isObject(options), 2);
+    errors.assertParamPropUnsignedInt(options, 2, 'timeout');
+    errors.assertParamPropBool(options, 2, 'deferRoundTrip');
+    const normalizedTransactionId =
+      nodbUtil.normalizeTransactionId(transactionId);
+    const {timeout = 60, deferRoundTrip = false} = options;
+    await this._impl.startSessionlessTransaction(normalizedTransactionId,
+      timeout, constants.TPC_BEGIN_RESUME, deferRoundTrip);
+    return normalizedTransactionId;
+  }
+
   //---------------------------------------------------------------------------
   // rollback()
   //
@@ -1521,6 +1591,17 @@ class Connection extends EventEmitter {
     return outValue;
   }
 
+  //---------------------------------------------------------------------------
+  // suspendSessionlessTransaction()
+  //
+  // Suspend any active sessionless transaction immediately
+  //---------------------------------------------------------------------------
+  async suspendSessionlessTransaction() {
+    errors.assertArgCount(arguments, 0, 0);
+    errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
+    await this._impl.suspendSessionlessTransaction();
+  }
+
   //---------------------------------------------------------------------------
   // tag
   //
@@ -1711,7 +1792,12 @@ class Connection extends EventEmitter {
     errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
     errors.assert(_subscriptions.has(name), errors.ERR_INVALID_SUBSCR);
     await this._impl.unsubscribe(_subscriptions.get(name));
-    _subscriptions.delete(name);
+
+    // Delay decreasing the reference count
+    // as NJS layer starts cleanup (uv_close) of async handle asynchronously.
+    setTimeout(() => {
+      _subscriptions.delete(name);
+    }, 0);
   }
 
 }
@@ -1724,6 +1810,7 @@ Connection.prototype.break =
 Connection.prototype.tpcRecover =
     nodbUtil.callbackify(nodbUtil.wrapFn(Connection.prototype.tpcRecover));
 nodbUtil.wrapFns(Connection.prototype,
+  "beginSessionlessTransaction",
   "changePassword",
   "close",
   "commit",
@@ -1734,10 +1821,12 @@ nodbUtil.wrapFns(Connection.prototype,
   "getQueue",
   "getStatementInfo",
   "ping",
+  "resumeSessionlessTransaction",
   "rollback",
   "shutdown",
   "startup",
   "subscribe",
+  "suspendSessionlessTransaction",
   "tpcBegin",
   "tpcCommit",
   "tpcEnd",

package/lib/dbObject.js

@@ -79,6 +79,18 @@ function validatePropertyValue(objType, metaData, value, index) {
 // instantiated; a cache of these classes are maintained on each connection
 class BaseDbObject {
 
+  //---------------------------------------------------------------------------
+  // _ensureCollection()
+  //
+  // Ensures that the object is a collection.
+  //---------------------------------------------------------------------------
+  _ensureCollection() {
+    if (!this.isCollection) {
+      errors.throwErr(errors.ERR_OBJECT_IS_NOT_A_COLLECTION,
+        this.name);
+    }
+  }
+
   //---------------------------------------------------------------------------
   // _getAttrValue()
   //
@@ -165,6 +177,7 @@ class BaseDbObject {
   //---------------------------------------------------------------------------
   append(value) {
     errors.assertArgCount(arguments, 1, 1);
+    this._ensureCollection();
     const info = {
       fqn: this._objType.fqn,
       type: this._objType.elementType,
@@ -200,6 +213,15 @@ class BaseDbObject {
         if (implAttr.typeClass) {
           attr.typeClass = implAttr.typeClass;
         }
+        if (implAttr.precision != null) {
+          attr.precision = implAttr.precision;
+        }
+        if (implAttr.scale != null) {
+          attr.scale = implAttr.scale;
+        }
+        if (implAttr.maxSize != null) {
+          attr.maxSize = implAttr.maxSize;
+        }
         attrs[implAttr.name] = attr;
       }
       this._attributes = attrs;
@@ -229,6 +251,7 @@ class BaseDbObject {
   //---------------------------------------------------------------------------
   deleteElement(index) {
     errors.assertArgCount(arguments, 1, 1);
+    this._ensureCollection();
     errors.assertParamValue(Number.isInteger(index), 1);
     return this._impl.deleteElement(index);
   }
@@ -291,6 +314,7 @@ class BaseDbObject {
   //---------------------------------------------------------------------------
   getElement(index) {
     errors.assertArgCount(arguments, 1, 1);
+    this._ensureCollection();
     errors.assertParamValue(Number.isInteger(index), 1);
     const value = this._impl.getElement(index);
     return this._transformValueOut(value, this.elementTypeClass, this._objType.elementTypeInfo);
@@ -303,6 +327,7 @@ class BaseDbObject {
   //---------------------------------------------------------------------------
   getKeys() {
     errors.assertArgCount(arguments, 0, 0);
+    this._ensureCollection();
     return this._impl.getKeys();
   }
 
@@ -313,6 +338,7 @@ class BaseDbObject {
   //---------------------------------------------------------------------------
   getFirstIndex() {
     errors.assertArgCount(arguments, 0, 0);
+    this._ensureCollection();
     return this._impl.getFirstIndex();
   }
 
@@ -323,6 +349,7 @@ class BaseDbObject {
   //---------------------------------------------------------------------------
   getLastIndex() {
     errors.assertArgCount(arguments, 0, 0);
+    this._ensureCollection();
     return this._impl.getLastIndex();
   }
 
@@ -333,6 +360,7 @@ class BaseDbObject {
   //---------------------------------------------------------------------------
   getNextIndex(index) {
     errors.assertArgCount(arguments, 1, 1);
+    this._ensureCollection();
     errors.assertParamValue(Number.isInteger(index), 1);
     return this._impl.getNextIndex(index);
   }
@@ -344,6 +372,7 @@ class BaseDbObject {
   //---------------------------------------------------------------------------
   getPrevIndex(index) {
     errors.assertArgCount(arguments, 1, 1);
+    this._ensureCollection();
     errors.assertParamValue(Number.isInteger(index), 1);
     return this._impl.getPrevIndex(index);
   }
@@ -355,6 +384,7 @@ class BaseDbObject {
   //---------------------------------------------------------------------------
   getValues() {
     errors.assertArgCount(arguments, 0, 0);
+    this._ensureCollection();
     const values = this._impl.getValues();
     for (let i = 0; i < values.length; i++) {
       values[i] = this._transformValueOut(values[i], this.elementTypeClass, this._objType.elementTypeInfo);
@@ -369,6 +399,7 @@ class BaseDbObject {
   //---------------------------------------------------------------------------
   hasElement(index) {
     errors.assertArgCount(arguments, 1, 1);
+    this._ensureCollection();
     errors.assertParamValue(Number.isInteger(index), 1);
     return this._impl.hasElement(index);
   }
@@ -417,6 +448,7 @@ class BaseDbObject {
   //---------------------------------------------------------------------------
   setElement(index, value) {
     errors.assertArgCount(arguments, 2, 2);
+    this._ensureCollection();
     errors.assertParamValue(Number.isInteger(index), 1);
     const info = {
       fqn: this._objType.fqn,
@@ -436,6 +468,7 @@ class BaseDbObject {
   //---------------------------------------------------------------------------
   trim(numToTrim) {
     errors.assertArgCount(arguments, 1, 1);
+    this._ensureCollection();
     errors.assertParamValue(Number.isInteger(numToTrim) && numToTrim >= 0, 1);
     this._impl.trim(numToTrim);
   }
@@ -478,10 +511,7 @@ class BaseDbObject {
   //---------------------------------------------------------------------------
   toMap() {
     errors.assertArgCount(arguments, 0, 0);
-    if (!this.isCollection) {
-      errors.throwErr(errors.ERR_OBJECT_IS_NOT_A_COLLECTION,
-        this.name);
-    }
+    this._ensureCollection();
     const result = new Map();
     this.getKeys().forEach(element => {
       result.set(element, this.getElement(element));