oracledb 6.7.2 → 6.9.0

package/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2015, 2024 Oracle and/or its affiliates.
+Copyright (c) 2015, 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

package/NOTICE.txt

@@ -1 +1 @@
-Copyright (c) 2015, 2024, Oracle and/or its affiliates.
+Copyright (c) 2015, 2025, Oracle and/or its affiliates.

package/README.md

@@ -1,10 +1,10 @@
-# node-oracledb version 6.7.2
+# node-oracledb version 6.9.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.7.2 to connect Node.js 14.6, or later, to Oracle
+Use node-oracledb 6.9.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.9.0-darwin-arm64.node-buildinfo.txt

@@ -0,0 +1 @@
+oracledb-6.9.0-darwin-arm64.node v23.10.0 2eb94e8660458ba0f6a59a00ebaa1d65e380cbd9 9cbfa993c59da0cfba2baa65e1c51fc0216bf586 Tue, 15 Jul 2025 11:23:44 GMT

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

@@ -0,0 +1 @@
+oracledb-6.9.0-darwin-x64.node v22.16.0 2eb94e8660458ba0f6a59a00ebaa1d65e380cbd9 9cbfa993c59da0cfba2baa65e1c51fc0216bf586 Tue, 15 Jul 2025 11:07:19 GMT

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

@@ -0,0 +1 @@
+2eb94e8660458ba0f6a59a00ebaa1d65e380cbd9

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

@@ -0,0 +1 @@
+oracledb-6.9.0-linux-arm64.node v20.19.2 2eb94e8660458ba0f6a59a00ebaa1d65e380cbd9 9cbfa993c59da0cfba2baa65e1c51fc0216bf586 Tue, 15 Jul 2025 11:06:47 GMT

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

@@ -0,0 +1 @@
+oracledb-6.9.0-linux-x64.node v22.13.1 2eb94e8660458ba0f6a59a00ebaa1d65e380cbd9 9cbfa993c59da0cfba2baa65e1c51fc0216bf586 Tue, 15 Jul 2025 11:48:53 GMT

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

@@ -0,0 +1 @@
+oracledb-6.9.0-win32-x64.node v20.17.0 2eb94e8660458ba0f6a59a00ebaa1d65e380cbd9 9cbfa993c59da0cfba2baa65e1c51fc0216bf586 Tue, 15 Jul 2025 11:04:06 GMT

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/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

@@ -1,4 +1,4 @@
-// Copyright (c) 2016, 2024, Oracle and/or its affiliates.
+// Copyright (c) 2016, 2025, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -50,6 +50,48 @@ const oson = require('./impl/datahandlers/oson.js');
 // and destroyed with another!
 const _subscriptions = new Map();
 
+// default closure for NUMBER type.
+const defaultNumberConverter = (v) => (v === null) ? null : parseFloat(v);
+
+//---------------------------------------------------------------------------
+// _determineDbObjTypeConverter()
+//
+// Determines the converter associated with each DB type and its metadata.
+// This function is called once during metadata construction and the
+// converters are invoked when retriving DBObject values.
+//---------------------------------------------------------------------------
+function _determineDbObjTypeConverter(metadata, options) {
+  // clear any previous converter functions that may have been
+  // retained
+  delete metadata.converter;
+
+  // If a DBfetch type handler is specified, update converter,
+  // if available.
+  if (options.dbObjectTypeHandler) {
+    const result = options.dbObjectTypeHandler(metadata);
+    if (result !== undefined) {
+      errors.assert(typeof result === 'object',
+        errors.ERR_DB_FETCH_TYPE_HANDLER_RETURN_VALUE);
+      if (result.converter !== undefined) {
+        errors.assert(typeof result.converter === 'function',
+          errors.ERR_DB_FETCH_TYPE_HANDLER_CONVERTER);
+      }
+      if ([types.DB_TYPE_CLOB, types.DB_TYPE_NCLOB, types.DB_TYPE_BLOB,
+        types.DB_TYPE_BFILE].includes(metadata.type)) {
+        // converters for LOB's are not supported.
+        return errors.throwErr(errors.ERR_NOT_IMPLEMENTED,
+          'DbObjConverter for LOBs');
+      }
+      metadata.converter = result.converter;
+    }
+  }
+  if (metadata.type === types.DB_TYPE_NUMBER && !metadata.converter) {
+    // set default converter for NUMBER type as they are returned as strings
+    // from DB.
+    metadata.converter = defaultNumberConverter;
+  }
+}
+
 // define class
 class Connection extends EventEmitter {
 
@@ -68,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",
@@ -96,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);
@@ -106,9 +155,11 @@ class Connection extends EventEmitter {
       const cls = this._getDbObjectClass(objType.elementTypeClass);
       objType.elementTypeClass = cls;
     }
+    const options = {dbObjectTypeHandler: settings.dbObjectTypeHandler};
     if (objType.isCollection) {
       nodbUtil.addTypeProperties(objType, "elementType");
       objType.elementTypeInfo.type = objType.elementType;
+      _determineDbObjTypeConverter(objType.elementTypeInfo, options);
     }
     if (objType.attributes) {
       const props = {};
@@ -126,6 +177,10 @@ class Connection extends EventEmitter {
           }
         };
         props[attr.name] = prop;
+
+        // calculate for each attribute metadata as converters might change
+        // based on precision, scale, maxSize,..
+        _determineDbObjTypeConverter(attr, options);
       }
       Object.defineProperties(DbObject.prototype, props);
     }
@@ -368,7 +423,9 @@ class Connection extends EventEmitter {
         bindInfo.type !== types.DB_TYPE_TIMESTAMP &&
         bindInfo.type !== types.DB_TYPE_TIMESTAMP_LTZ &&
         bindInfo.type !== types.DB_TYPE_TIMESTAMP_TZ &&
-        bindInfo.type !== types.DB_TYPE_RAW) {
+        bindInfo.type !== types.DB_TYPE_RAW &&
+        bindInfo.type !== types.DB_TYPE_INTERVAL_YM &&
+        bindInfo.type !== types.DB_TYPE_INTERVAL_DS) {
       errors.throwErr(errors.ERR_INVALID_TYPE_FOR_ARRAY_BIND);
     }
 
@@ -541,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) {
 
@@ -651,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()
   //
@@ -1205,6 +1290,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()
   //
@@ -1216,6 +1313,20 @@ class Connection extends EventEmitter {
       this._impl.isHealthy());
   }
 
+  isCompressionEnabled() {
+    return (this._impl && this._impl.isCompressionEnabled());
+  }
+
+  //---------------------------------------------------------------------------
+  // maxIdentifierLength
+  //
+  // Returns the maximum length of identifiers supported by the database to
+  // which this connection has been established.
+  //---------------------------------------------------------------------------
+  get maxIdentifierLength() {
+    return this._impl && this._impl.getMaxIdentifierLength();
+  }
+
   //---------------------------------------------------------------------------
   // maxOpenCursors
   //
@@ -1343,6 +1454,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()
   //
@@ -1457,6 +1587,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
   //
@@ -1647,7 +1788,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);
   }
 
 }
@@ -1660,6 +1806,7 @@ Connection.prototype.break =
 Connection.prototype.tpcRecover =
     nodbUtil.callbackify(nodbUtil.wrapFn(Connection.prototype.tpcRecover));
 nodbUtil.wrapFns(Connection.prototype,
+  "beginSessionlessTransaction",
   "changePassword",
   "close",
   "commit",
@@ -1670,10 +1817,12 @@ nodbUtil.wrapFns(Connection.prototype,
   "getQueue",
   "getStatementInfo",
   "ping",
+  "resumeSessionlessTransaction",
   "rollback",
   "shutdown",
   "startup",
   "subscribe",
+  "suspendSessionlessTransaction",
   "tpcBegin",
   "tpcCommit",
   "tpcEnd",

package/lib/dbObject.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2019, 2024, Oracle and/or its affiliates.
+// Copyright (c) 2019, 2025, Oracle and/or its affiliates.
 
 //----------------------------------------------------------------------------
 //
@@ -86,7 +86,7 @@ class BaseDbObject {
   //---------------------------------------------------------------------------
   _getAttrValue(attr) {
     const value = this._impl.getAttrValue(attr);
-    return this._transformValueOut(value, attr.typeClass);
+    return this._transformValueOut(value, attr.typeClass, attr);
   }
 
   //---------------------------------------------------------------------------
@@ -138,16 +138,21 @@ class BaseDbObject {
   //
   // Transforms a value going out to the caller from the implementation.
   //---------------------------------------------------------------------------
-  _transformValueOut(value, cls) {
+  _transformValueOut(value, cls, metaData) {
     let outValue = value;
     if (value instanceof impl.LobImpl) {
       outValue = new Lob();
       outValue._setup(value, true);
-    } else if (value instanceof impl.DbObjectImpl) {
-      outValue = Object.create(cls.prototype);
-      outValue._impl = value;
-      if (outValue.isCollection) {
-        outValue = new Proxy(outValue, BaseDbObject._collectionProxyHandler);
+    } else {
+      if (value instanceof impl.DbObjectImpl) {
+        outValue = Object.create(cls.prototype);
+        outValue._impl = value;
+        if (outValue.isCollection) {
+          outValue = new Proxy(outValue, BaseDbObject._collectionProxyHandler);
+        }
+      }
+      if (metaData.converter) {
+        outValue = metaData.converter(outValue);
       }
     }
     return outValue;
@@ -195,6 +200,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;
@@ -202,6 +216,21 @@ class BaseDbObject {
     return this._attributes;
   }
 
+  //---------------------------------------------------------------------------
+  // copy
+  //
+  // Creates and returns a copy of the object. The copy is independent of
+  // the original object that was copied.
+  //---------------------------------------------------------------------------
+  copy() {
+    errors.assertArgCount(arguments, 0, 0);
+    const newObj = Object.create(this);
+    newObj._impl = this._impl.copy();
+    if (this.isCollection)
+      return new Proxy(newObj, BaseDbObject._collectionProxyHandler);
+    return newObj;
+  }
+
   //---------------------------------------------------------------------------
   // deleteElement()
   //
@@ -253,6 +282,17 @@ class BaseDbObject {
     return this._objType.fqn;
   }
 
+  //---------------------------------------------------------------------------
+  // length
+  //
+  // Length of the database object type, if it is a collection. Else it
+  // returns undefined.
+  //---------------------------------------------------------------------------
+  get length() {
+    if (this.isCollection)
+      return this._impl.getLength();
+    return undefined;
+  }
   //---------------------------------------------------------------------------
   // getElement()
   //
@@ -262,7 +302,7 @@ class BaseDbObject {
     errors.assertArgCount(arguments, 1, 1);
     errors.assertParamValue(Number.isInteger(index), 1);
     const value = this._impl.getElement(index);
-    return this._transformValueOut(value, this.elementTypeClass);
+    return this._transformValueOut(value, this.elementTypeClass, this._objType.elementTypeInfo);
   }
 
   //---------------------------------------------------------------------------
@@ -326,7 +366,7 @@ class BaseDbObject {
     errors.assertArgCount(arguments, 0, 0);
     const values = this._impl.getValues();
     for (let i = 0; i < values.length; i++) {
-      values[i] = this._transformValueOut(values[i], this.elementTypeClass);
+      values[i] = this._transformValueOut(values[i], this.elementTypeClass, this._objType.elementTypeInfo);
     }
     return values;
   }
@@ -483,6 +523,7 @@ wrapFns(BaseDbObject.prototype,
   "_getAttrValue",
   "_setAttrValue",
   "append",
+  "copy",
   "deleteElement",
   "getElement",
   "getKeys",