oracledb 7.0.0 → 26.0.0

package/README.md

@@ -1,22 +1,30 @@
-# node-oracledb version 7.0.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"/>
+# node-oracledb version 26.0.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 7.0.0 to connect Node.js 14.17, or later, to Oracle
+Use node-oracledb 26.0.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.
 
 Node-oracledb supports basic and advanced features of Oracle Database
-and Oracle Client.  See the [homepage][4] for a list.
+and Oracle Client.  See the [homepage][4] for a list. It is used by many
+JavaScript and TypeScript frameworks, SQL generators, ORMs, and libraries.
+
+Node-oracledb has a rich feature set which is easy to use. It gives you
+control over SQL and PL/SQL statement execution, fast data ingestion, support
+for calling NoSQL-style document APIs, message queueing,database notifications
+and for starting and stopping the database.
+It also has high availability and security features. Database operations
+can optionally be [pipelined][16].
 
 The node-oracledb module is open source and maintained by Oracle Corp.
 It is stable, well documented, and has a comprehensive test suite.
 
 ## Installation
 
-Run `npm install oracledb`
+Run `npm install oracledb`.
 
 See [Getting Started with Node-oracledb][1] and [Quick Start Node-oracledb Installation][2].
 
@@ -40,7 +48,8 @@ See [Getting Started with Node-oracledb][1] and [Quick Start Node-oracledb Insta
   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 version
-  19 and later.
+  19 or later. Older node-oracledb versions supported older Client
+  versions.
 
 - Oracle Database
 
@@ -118,4 +127,5 @@ limitations under the License.
 [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
+[15]: https://www.oracle.com/database/technologies/instant-client.html
+[16]: https://node-oracledb.readthedocs.io/en/latest/user_guide/pipeline.html

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

@@ -0,0 +1 @@
+oracledb-26.0.0-darwin-arm64.node v24.11.1 fdba9345f92e83a5f0e66f01a5953ecfc358e053 1c8cabceb27b2e7a64737fb3de66f3d0014eed5f Mon, 28 Sep 2026 10:55:10 GMT

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

@@ -0,0 +1 @@
+fdba9345f92e83a5f0e66f01a5953ecfc358e053

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

@@ -0,0 +1 @@
+oracledb-26.0.0-linux-arm64.node v24.19.0 fdba9345f92e83a5f0e66f01a5953ecfc358e053 1c8cabceb27b2e7a64737fb3de66f3d0014eed5f Mon, 28 Sep 2026 10:49:51 GMT

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

@@ -0,0 +1 @@
+oracledb-26.0.0-linux-x64.node v22.19.0 fdba9345f92e83a5f0e66f01a5953ecfc358e053 1c8cabceb27b2e7a64737fb3de66f3d0014eed5f Mon, 28 Sep 2026 10:48:56 GMT

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

@@ -0,0 +1 @@
+oracledb-26.0.0-win32-x64.node v22.17.1 fdba9345f92e83a5f0e66f01a5953ecfc358e053 1c8cabceb27b2e7a64737fb3de66f3d0014eed5f Mon, 28 Sep 2026 10:54:04 GMT

package/lib/aqDeqOptions.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2019, 2025, Oracle and/or its affiliates.
+// Copyright (c) 2019, 2026, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -56,7 +56,7 @@ class AqDeqOptions {
   }
 
   set consumerName(value) {
-    errors.assertPropValue(typeof value === 'string', "consumerName");
+    errors.assertPropLength(value, "string", 128, "consumerName");
     this._impl.setConsumerName(value);
   }
 
@@ -70,7 +70,7 @@ class AqDeqOptions {
   }
 
   set correlation(value) {
-    errors.assertPropValue(typeof value === 'string', "correlation");
+    errors.assertPropLength(value, "string", 128, "correlation");
     this._impl.setCorrelation(value);
   }
 
@@ -148,7 +148,7 @@ class AqDeqOptions {
   }
 
   set transformation(value) {
-    errors.assertPropValue(typeof value === 'string', "transformation");
+    errors.assertPropLength(value, "string", 128, "transformation");
     this._impl.setTransformation(value);
   }
 

package/lib/aqEnqOptions.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2019, 2022, Oracle and/or its affiliates.
+// Copyright (c) 2019, 2026, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -57,7 +57,7 @@ class AqEnqOptions {
   }
 
   set transformation(value) {
-    errors.assertPropValue(typeof value === 'string', "transformation");
+    errors.assertPropLength(value, "string", 128, "transformation");
     this._impl.setTransformation(value);
   }
 

package/lib/aqQueue.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2019, 2025, Oracle and/or its affiliates.
+// Copyright (c) 2019, 2026, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -104,15 +104,15 @@ class AqQueue {
 
     // validate options, if applicable
     if (message.correlation !== undefined) {
-      errors.assertParamPropValue(typeof message.correlation === 'string', 1,
+      errors.assertPropLength(message.correlation, "string", 128,
         "correlation");
     }
     if (message.delay !== undefined) {
       errors.assertParamPropValue(Number.isInteger(message.delay), 1, "delay");
     }
     if (message.exceptionQueue !== undefined) {
-      errors.assertParamPropValue(typeof message.exceptionQueue === 'string',
-        1, "exceptionQueue");
+      errors.assertPropLength(message.exceptionQueue, "string", 128,
+        "exceptionQueue");
     }
     if (message.expiration !== undefined) {
       errors.assertParamPropValue(Number.isInteger(message.expiration), 1,
@@ -123,8 +123,13 @@ class AqQueue {
         "priority");
     }
     if (message.recipients !== undefined) {
-      errors.assertParamPropValue(nodbUtil.isArrayOfStrings(message.recipients),
-        1, "recipients");
+      // Check recipients length and type
+      errors.assertPropLength(message.recipients, "array", 1024, "recipients");
+      // Check value and length of each recipient
+      message.recipients.forEach((recipient, index) => {
+        errors.assertPropLength(recipient, "string", 128,
+          `recipient at index ${index}`);
+      });
     }
 
     return message;

package/lib/connection.js

@@ -55,6 +55,19 @@ const APP_CONTEXT_VALUE_MAX_BYTES = 4 * 1000;
 // and destroyed with another!
 const _subscriptions = new Map();
 
+//---------------------------------------------------------------------------
+// _removeSubscription()
+//
+// Remove a subscription only when it is still the subscription currently
+// registered for the name. A terminal old subscription must not remove a newer
+// subscription that reused the same name.
+//---------------------------------------------------------------------------
+function _removeSubscription(name, subscription) {
+  if (_subscriptions.get(name) === subscription) {
+    _subscriptions.delete(name);
+  }
+}
+
 // default closure for NUMBER type.
 const defaultNumberConverter = (v) => (v === null) ? null : parseFloat(v);
 
@@ -83,9 +96,8 @@ function _determineDbObjTypeConverter(metadata, options) {
       }
       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');
+        // converters for LOBs are not supported.
+        return errors.throwNotImplemented('DbObjConverter for LOBs');
       }
       metadata.converter = result.converter;
     }
@@ -905,6 +917,23 @@ class Connection extends EventEmitter {
     this._impl.setCurrentSchema(value);
   }
 
+  //---------------------------------------------------------------------------
+  // databaseOpenTelemetryTracing
+  //
+  // Property for enabling database OpenTelemetry trace propagation.
+  //---------------------------------------------------------------------------
+  get databaseOpenTelemetryTracing() {
+    if (this._impl)
+      return this._impl.getDatabaseOpenTelemetryTracing();
+    return undefined;
+  }
+
+  set databaseOpenTelemetryTracing(value) {
+    errors.assertPropValue(typeof value === 'boolean', "databaseOpenTelemetryTracing");
+    errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
+    this._impl.setDatabaseOpenTelemetryTracing(value);
+  }
+
   //---------------------------------------------------------------------------
   // dbOp
   //
@@ -1406,7 +1435,7 @@ class Connection extends EventEmitter {
     errors.assertArgCount(arguments, 1, 1);
     errors.assertParamValue(typeof sql === 'string', 1);
     errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
-    const info = await this._impl.getStatementInfo(sql);
+    const info = await this._impl.getStatementInfo(sql, { connection: this });
     if (info.metaData) {
       for (let i = 0; i < info.metaData.length; i++) {
         const m = info.metaData[i];
@@ -1564,6 +1593,21 @@ class Connection extends EventEmitter {
     return this._impl && this._impl.getTransactionInProgress();
   }
 
+  //---------------------------------------------------------------------------
+  // txnPriority
+  //
+  // Property for transaction priority associated with the connection.
+  //---------------------------------------------------------------------------
+  get txnPriority() {
+    return this._impl && this._impl.getTxnPriority();
+  }
+
+  set txnPriority(value) {
+    errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
+    errors.assertTxnPriority(value);
+    this._impl.setTxnPriority(value);
+  }
+
   //---------------------------------------------------------------------------
   // ping()
   //
@@ -1590,9 +1634,11 @@ class Connection extends EventEmitter {
     } else {
       options = {};
     }
+    errors.assertParamPropUnsignedIntNonZero(options, 3, "rowsPerDataEvent");
+    const rowsPerDataEvent = options.rowsPerDataEvent;
     options.resultSet = true;
 
-    const stream = new QueryStream();
+    const stream = new QueryStream(undefined, rowsPerDataEvent);
 
     // calling execute() via nextTick to ensure that handlers are registered
     // prior to the events being emitted
@@ -1732,15 +1778,22 @@ class Connection extends EventEmitter {
     errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
 
     const inSubscr = _subscriptions.get(name);
+    if (this.thin) {
+      options._onRetire = (subscription) =>
+        _removeSubscription(name, subscription);
+    }
     const outValue = await this._impl.subscribe(inSubscr, options);
     let subscription;
     if (options.namespace === constants.SUBSCR_NAMESPACE_DBCHANGE) {
       subscription = outValue.subscription;
       delete outValue.subscription;
+      outValue.regId = Number(outValue.regId);
     } else {
       subscription = outValue;
     }
-    _subscriptions.set(name, subscription);
+    if (!this.thin || subscription._registered) {
+      _subscriptions.set(name, subscription);
+    }
     return outValue;
   }
 
@@ -1988,11 +2041,14 @@ class Connection extends EventEmitter {
 
       // Force a ResultSet and then fetch rows according to the requested
       // fetch variant in non-pipeline flow.
-      op.options.resultSet = true;
-      op.options.fetchTypeHandler = this._createFetchTypeHandler(op.fetchLobs);
+      const execOptions = {
+        ...op.options,
+        resultSet: true,
+        fetchTypeHandler: this._createFetchTypeHandler(op.fetchLobs)
+      };
       let shouldClose = false;
       try {
-        res = await this._execute(op.statement, op.parameters, op.options);
+        res = await this._execute(op.statement, op.parameters, execOptions);
         if (opType === 'fetchOne') {
           const row = await res.resultSet._getRow();
           res.rows = row ? [row] : [];
@@ -2095,12 +2151,18 @@ class Connection extends EventEmitter {
     errors.assertParamValue(typeof name === 'string', 1);
     errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
     errors.assert(_subscriptions.has(name), errors.ERR_INVALID_SUBSCR);
-    await this._impl.unsubscribe(_subscriptions.get(name));
+    const subscription = _subscriptions.get(name);
+    await this._impl.unsubscribe(subscription);
+
+    if (this.thin) {
+      _removeSubscription(name, subscription);
+      return;
+    }
 
     // Delay decreasing the reference count
     // as NJS layer starts cleanup (uv_close) of async handle asynchronously.
     setTimeout(() => {
-      _subscriptions.delete(name);
+      _removeSubscription(name, subscription);
     }, 0);
   }
 
@@ -2116,13 +2178,6 @@ class Connection extends EventEmitter {
       errors.throwErr(errors.ERR_APP_CONTEXT_EMPTY_NAMESPACE);
     }
 
-    // Passing null/undefined/[] currently leaves existing entries intact in
-    // thick mode and triggers an error in thin mode.
-    // It does not clear the context; use clearAppContext() explicitly
-    // when you need to remove keys.
-    if (keyValues === null || keyValues === undefined) {
-      keyValues = [];
-    }
     errors.assertParamValue(Array.isArray(keyValues), 2);
 
     for (const entry of keyValues) {

package/lib/constants.js

@@ -207,4 +207,8 @@ module.exports = {
   VECTOR_FORMAT_INT8: 4,
   VECTOR_FORMAT_BINARY: 5,
 
+  TXN_PRIORITY_HIGH: 'HIGH',
+  TXN_PRIORITY_MEDIUM: 'MEDIUM',
+  TXN_PRIORITY_LOW: 'LOW',
+  TXN_PRIORITY_DEFAULT: '',
 };

package/lib/endUserSecurityContext.js

@@ -40,16 +40,17 @@ function hasNonEmptyText(value) {
 }
 
 /*
-Represents the credential set an application associates with an end user.
+Represents a Deep Data Security credential set for an end user or, for direct
+application logon, the application identity encoded by its database token.
 
 Required properties
 - databaseAccessToken: non-empty string accepted by the database driver.
-- endUserToken or endUserName: at least one must be supplied as a string.
-- key: required whenever endUserName is supplied; otherwise optional.
+- endUserToken or endUserName: exactly one must be supplied as a string for an
+  end-user context. Neither is supplied for direct application logon.
 
 Optional properties
 - key: look-up identifier the database maps to stored context attributes; may be
-  omitted only when identifying users via endUserToken.
+  supplied only with endUserName.
 - dataRoles: data roles enabled/disabled by the application logic, rather
   than a database security policy.
 - attributes: Attributes are contained in JSON objects conforming
@@ -72,29 +73,31 @@ class EndUserSecurityContext {
       dataRoles,
       attributes
     } = options;
-
-    // The database access token is always required, and the end user must be
-    // identified either by token or by name.
+    const hasEndUserToken = endUserToken !== undefined && endUserToken !== null;
+    const hasEndUserName = endUserName !== undefined && endUserName !== null;
+    const hasKey = key !== undefined && key !== null;
+
+    // The database access token is always required. An end-user context has
+    // exactly one identity mechanism. A context with neither token nor name
+    // is an application-direct logon: the database maps the client identity
+    // in databaseAccessToken to its registered application identity.
     errors.assertParamValue(hasNonEmptyText(databaseAccessToken), 1);
     errors.assertParamValue(
-      (endUserToken !== undefined && endUserToken !== null) ||
-      (endUserName !== undefined && endUserName !== null),
-      1
-    );
+      (hasEndUserToken && !hasEndUserName && !hasKey) ||
+      (!hasEndUserToken && hasEndUserName) ||
+      (!hasEndUserToken && !hasEndUserName && !hasKey), 1);
 
     // When supplied, token/name/key values must contain non-whitespace text.
-    if (endUserToken !== undefined && endUserToken !== null) {
+    if (hasEndUserToken) {
       errors.assertParamValue(hasNonEmptyText(endUserToken), 1);
     }
 
-    // Name-based contexts require a key so the database can locate the stored
-    // end user context attributes.
-    if (endUserName !== undefined && endUserName !== null) {
+    if (hasEndUserName) {
       errors.assertParamValue(hasNonEmptyText(endUserName), 1);
-      errors.assertParamValue(key !== undefined && key !== null, 1);
     }
 
-    if (key !== undefined && key !== null) {
+    if (hasKey) {
+      errors.assertParamValue(hasEndUserName, 1);
       errors.assertParamValue(hasNonEmptyText(key), 1);
     }
 
@@ -117,7 +120,10 @@ class EndUserSecurityContext {
 
     // Data roles are optional, but must be passed as an array when present.
     if (dataRoles != null) {
-      errors.assertParamValue(Array.isArray(dataRoles), 1);
+      errors.assertParamValue(
+        Array.isArray(dataRoles) && dataRoles.every(hasNonEmptyText),
+        1
+      );
       payload.data_roles = Array.from(dataRoles);
     }
 
@@ -128,17 +134,21 @@ class EndUserSecurityContext {
         1
       );
       payload.attributes = Object.entries(attributes).map(
-        ([name, values]) => ({ name, values }));
+        ([name, values]) => ({ name, values: values ?? null }));
     }
 
     this._payloadStore = new ObfuscatedValue();
     this._encodeAndStorePayload(payload);
   }
 
+  // Encode EUSC payloads with strict validation of unsupported JSON values and
+  // field names.
   _encodePayload(value) {
     const encoder = new oson.OsonEncoder();
     return encoder.encode(
-      transformer.transformJsonValue(value),
+      transformer.transformJsonValue(value, {
+        rejectUnsupportedTypes: true
+      }),
       DEFAULT_MAX_FIELD_NAME_SIZE
     );
   }
@@ -159,7 +169,6 @@ class EndUserSecurityContext {
         payloadLength
       );
     }
-    this.clearEncodedPayload();
     this._payloadStore.set(encodedPayload, { returnBuffer: true });
     encodedPayload.fill(0);
   }
@@ -167,10 +176,6 @@ class EndUserSecurityContext {
   getDeobfuscatedValue() {
     return this._payloadStore.get({ returnBuffer: true });
   }
-
-  clearEncodedPayload() {
-    this._payloadStore.clear();
-  }
 }
 
 module.exports = EndUserSecurityContext;