oracledb 6.8.0 → 6.9.0

package/lib/oracledb.js

@@ -34,15 +34,15 @@ const impl = require('./impl');
 const process = require('process');
 const util = require('util');
 
-// This version of node-oracledb works with Node.js 14.6 or later.
+// This version of node-oracledb works with Node.js 14.17 or later.
 // Note: the checked version is the minimum required for Node-API
 // compatibility.  When new Node.js versions are released, older Node.js
 // versions are dropped from the node-oracledb test plan.
 //
 // Keep this code in sync with package/install.js
 const vs = process.version.substring(1).split(".").map(Number);
-errors.assert(vs[0] > 14 || (vs[0] === 14 && vs[1] >= 6),
-  errors.ERR_NODE_TOO_OLD, nodbUtil.PACKAGE_JSON_VERSION, "14.6");
+errors.assert(vs[0] > 14 || (vs[0] === 14 && vs[1] >= 17),
+  errors.ERR_NODE_TOO_OLD, nodbUtil.PACKAGE_JSON_VERSION, "14.17");
 
 const AqDeqOptions = require('./aqDeqOptions.js');
 const AqEnqOptions = require('./aqEnqOptions.js');
@@ -68,6 +68,7 @@ const poolCache = {};
 const tempUsedPoolAliases = {};
 const defaultPoolAlias = 'default';
 const registeredHooks = [];
+const registeredConfigProviderHooks = new Map();
 let configProviderCache;
 
 // save arguments for call to initOracleClient()
@@ -382,6 +383,15 @@ async function _verifyOptions(options, inCreatePool) {
     outOptions.useSNI = options.useSNI;
   }
 
+  // appContext must be an array of array values. The element arrays should
+  // have 3 string values (namespace, name and value).
+  if (options.appContext !== undefined) {
+    const value = options.appContext;
+    errors.assertParamPropValue(nodbUtil.isAppContext(value), 1,
+      "appContext");
+    outOptions.appContext = options.appContext;
+  }
+
   // check pool specific options
   if (inCreatePool) {
 
@@ -435,6 +445,13 @@ async function _verifyOptions(options, inCreatePool) {
       outOptions.poolPingTimeout = options.poolPingTimeout;
     }
 
+    // maxLifeTime must be an unsigned integer
+    if (options.maxLifetimeSession !== undefined) {
+      errors.assertParamPropValue(Number.isInteger(options.maxLifetimeSession) &&
+    options.maxLifetimeSession >= 0, 1, "maxLifetimeSession");
+      outOptions.maxLifetimeSession = options.maxLifetimeSession;
+    }
+
     // homogeneous must be a boolean (and defaults to True)
     outOptions.homogeneous = true;
     if (options.homogeneous !== undefined) {
@@ -888,6 +905,84 @@ async function shutdown(a1, a2) {
   await conn.close();
 }
 
+async function _setConfigParameters(obj, credential, configProvider) {
+  const configObject = {};
+  const pmSection = 'njs';
+  const params = obj[pmSection];
+  for (const key in params) {
+    const val = params[key];
+    configObject[key] = val;
+  }
+  configObject.connectString = obj.connect_descriptor;
+  if (!configObject.connectString)
+    errors.throwErr(errors.ERR_CONFIG_PROVIDER_FAILED_TO_RETRIEVE_CONFIG, 'connect_descriptor must be set');
+
+  configObject.user = obj.user;
+  if (obj.password) {
+    configObject.password = await _retrieveParamValueFromVault(obj['password'], credential, configProvider);
+  }
+  if (obj.wallet_location) {
+    // retrieve wallet_location
+    configObject.walletContent = await _retrieveParamValueFromVault(obj['wallet_location'], credential, configProvider);
+    //only Pem file supported
+    if (!nodbUtil.isPemFile(configObject.walletContent))
+      errors.throwErr(errors.ERR_WALLET_TYPE_NOT_SUPPORTED);
+  }
+  return configObject;
+}
+
+async function _retrieveParamValueFromVault(paramObj, credential, configProvider) {
+  const paramMap = new Map();
+  const auth = paramObj.authentication;
+  if (auth) {
+    for (const key in auth) {
+      if (key == 'method')
+        paramMap.set('authentication', auth[key]);
+      const val = auth[key];
+      paramMap.set(key.toLowerCase(), val);
+    }
+  }
+  const args = {};
+  if (paramObj.type == "base64") {
+    console.log("WARNING: Base64 Encoding in a JSON Password should only be used in development environments");
+    return Buffer.from(paramObj.value, "base64").toString("utf-8");
+  } else if (paramObj.type == "text") {
+    if (configProvider == 'azurevault' || configProvider == 'ocivault') {
+      console.log("WARNING: Plain Text in a JSON Password should only be used in development environments");
+      return paramObj.value;
+    } else
+      errors.throwErr(errors.ERR_CONFIG_PROVIDER_PARAM_TYPE, 'password type text is only allowed in ocivault and azurevault');
+  } else if (paramObj.type == "azurevault") {
+    paramMap.set('azuresecreturl', paramObj.value);
+    if (!(configProvider == 'azure' || configProvider == 'azurevault'))
+      credential = null;
+    const hookFn = registeredConfigProviderHooks['azurevault'];
+    if (hookFn == undefined)
+      errors.throwErr(errors.ERR_REGISTER_HOOKFN_CONFIGPROVIDER, 'azurevault');
+    args.credential = credential;
+    args.paramMap = paramMap;
+    const vaultReturn = await hookFn(args);
+    const paramValue = vaultReturn[0];
+    return paramValue;
+
+  } else if (paramObj.type == "ocivault") {
+
+    paramMap.set('ocidvault', paramObj.value);
+    if (!(configProvider == 'ociobject' || configProvider == 'ocivault'))
+      credential = null;
+    const hookFn = registeredConfigProviderHooks['ocivault'];
+    if (hookFn == undefined)
+      errors.throwErr(errors.ERR_REGISTER_HOOKFN_CONFIGPROVIDER, 'ocivault');
+    const args = {};
+    args.credential = credential;
+    args.paramMap = paramMap;
+    const vaultReturn = await hookFn(args);
+    const paramValue = vaultReturn[0];
+    return paramValue;
+  }  else {
+    errors.throwErr(errors.ERR_CONFIG_PROVIDER_PARAM_TYPE, 'password/wallet_location');
+  }
+}
 //-----------------------------------------------------------------------------
 // _checkConfigProvider()
 //
@@ -928,23 +1023,27 @@ async function _checkConfigProvider(options) {
     if (match) {
       const provider = match.groups.provider;
       const provider_arg = match.groups.provider_arg;
-      let configPckg;
-      try {
-        configPckg = require('./configProviders/' + provider);
-      } catch (err) {
-        errors.throwErr(errors.ERR_CONFIG_PROVIDER_NOT_SUPPORTED, provider);
-      }
-      const configProvider = new configPckg(provider_arg, urlExtendedPart);
-      try {
-        configProvider.init();
-      } catch (err) {
-        errors.throwErr(errors.ERR_CONFIG_PROVIDER_LOAD_FAILED, err.message);
-      }
+      const hookFn = registeredConfigProviderHooks[provider];
+      if (hookFn == undefined)
+        errors.throwErr(errors.ERR_REGISTER_HOOKFN_CONFIGPROVIDER, provider);
+      const args = {};
+      args.provider_arg = provider_arg;
+      args.urlExtendedPart = urlExtendedPart;
+
       try {
+      // hookFn returns an array with first element as the config stored in the configProvider
+      // second being the credential to the configProvider
+        const configProviderReturn = await hookFn(args);
+        secondOpts = configProviderReturn[0];
         if (!configProviderCache) {
           configProviderCache = new Map();
         }
-        secondOpts = await configProvider.returnConfig();
+        if (!secondOpts) {
+          errors.throwErr(errors.ERR_CONFIG_PROVIDER_FAILED_TO_RETRIEVE_CONFIG, 'no configuration found in ' + provider);
+        }
+        if (provider != 'azure')
+          secondOpts = await _setConfigParameters(secondOpts, configProviderReturn[1], provider);
+
         // obfuscate password & walletcontent and store config in the cache
         const cacheOpts = { ...secondOpts};
         if (secondOpts.password)
@@ -1057,6 +1156,19 @@ function registerProcessConfigurationHook(fn) {
   registeredHooks.push(fn);
 }
 
+//-----------------------------------------------------------------------------
+// registerConfigurationProviderHook()
+//
+// Registers Configuration Provider plugin modules and registered modules will
+// be called and executed during pool and standalone connection creation.
+//-----------------------------------------------------------------------------
+function registerConfigurationProviderHook(configProvider, fn) {
+  errors.assertArgCount(arguments, 2, 2);
+  errors.assertParamValue(typeof fn === 'function', 1);
+  errors.assertParamValue(typeof configProvider === 'string', 1);
+  registeredConfigProviderHooks[configProvider] = fn;
+}
+
 // module exports
 module.exports = {
 
@@ -1088,6 +1200,7 @@ module.exports = {
   getPool,
   initOracleClient,
   registerProcessConfigurationHook,
+  registerConfigurationProviderHook,
   shutdown: nodbUtil.callbackify(nodbUtil.wrapFn(shutdown)),
   startup: nodbUtil.callbackify(nodbUtil.wrapFn(startup)),
 

package/lib/pool.js

@@ -653,6 +653,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 +702,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 +718,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,

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.
 
 //-----------------------------------------------------------------------------
 //
@@ -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/thin/connection.js

@@ -85,6 +85,9 @@ class ThinConnectionImpl extends ConnectionImpl {
       // immediate close of open socket on failure
       // exception won't be thrown to user
       this.nscon.disconnect(sqlNetConstants.NSFIMM);
+      // If connection is associated with a pool, we release it
+      if (this._pool)
+        await this._pool.release(this);
     }
   }
 
@@ -299,13 +302,20 @@ class ThinConnectionImpl extends ConnectionImpl {
     }
 
     // process the type code.
+    let tempPrecision, tempScale;
     switch (attrType) {
       case constants.TNS_OBJ_TDS_TYPE_NUMBER:
-        metaData.precision = buf.readInt8();
-        metaData.scale = buf.readInt8();
+        tempPrecision = buf.readInt8();
+        tempScale = buf.readInt8();
+        if (tempPrecision || tempScale) {
+          metaData.precision = tempPrecision;
+          metaData.scale = tempScale;
+        }
         return types.DB_TYPE_NUMBER;
       case constants.TNS_OBJ_TDS_TYPE_FLOAT:
-        metaData.precision = buf.readInt8();
+        tempPrecision = buf.readInt8();
+        if (tempPrecision)
+          metaData.precision = tempPrecision;
         return types.DB_TYPE_NUMBER;
       case constants.TNS_OBJ_TDS_TYPE_VARCHAR:
       case constants.TNS_OBJ_TDS_TYPE_CHAR:
@@ -433,11 +443,24 @@ class ThinConnectionImpl extends ConnectionImpl {
         case
           when data_type in
             ('CHAR', 'NCHAR', 'VARCHAR2', 'NVARCHAR2', 'RAW')
-          then data_length
+            then data_length
           else 0
         end,
-        nvl(data_precision, 0),
-        nvl(data_scale, 0)
+        case
+          when data_precision is null and data_scale is null
+            then 0
+          when data_precision is null
+            then 38
+          else data_precision
+        end,
+        case
+          when data_precision is null and data_scale is null
+              and data_type = 'NUMBER'
+            then -127
+          when data_scale is null
+            then 0
+          else data_scale
+        end
       from all_tab_cols
       where owner = :owner
         and table_name = :name
@@ -670,10 +693,36 @@ class ThinConnectionImpl extends ConnectionImpl {
         this._partialDbObjectTypes.push(attr.typeClass);
       }
     } else {
-      attr.type = types.getTypeByColumnTypeName(attrInfo.dataType);
-      attr.maxSize = attrInfo.maxSize;
-      attr.precision = attrInfo.dataPrecision;
-      attr.scale = attrInfo.dataScale;
+      if (attrInfo.dataType === 'INTEGER' || attrInfo.dataType === 'SMALLINT') {
+        attr.type = types.DB_TYPE_NUMBER;
+        attr.precision = 38;
+        attr.scale = 0;
+      } else if (attrInfo.dataType === 'REAL') {
+        attr.type = types.DB_TYPE_NUMBER;
+        attr.precision = 63;
+        attr.scale = -127;
+      } else if (attrInfo.dataType === 'DOUBLE PRECISION' || attrInfo.dataType === 'FLOAT') {
+        attr.type = types.DB_TYPE_NUMBER;
+        // the database sends type name "FLOAT" instead of type name "REAL"
+        // when looking at table metadata but not when examining database
+        // object attribute metadata so account for that here
+        if (attrInfo.dataPrecision != null || attrInfo.dataPrecision != undefined)
+          attr.precision = Number(attrInfo.dataPrecision);
+        else
+          attr.precision = 126;
+        attr.scale = -127;
+      } else {
+        attr.type = types.getTypeByColumnTypeName(attrInfo.dataType);
+        if (attrInfo.maxSize != null || attrInfo.maxSize != undefined) {
+          const tempMaxSize = Number(attrInfo.maxSize);
+          if (tempMaxSize)
+            attr.maxSize = tempMaxSize;
+        }
+        if (attr.type === types.DB_TYPE_NUMBER) {
+          attr.precision = Number(attrInfo.dataPrecision);
+          attr.scale = Number(attrInfo.dataScale);
+        }
+      }
     }
     attributes.push(attr);
   }
@@ -772,6 +821,7 @@ class ThinConnectionImpl extends ConnectionImpl {
     this.remoteAddress = '';
     this.comboKey = null; // used in changePassword API
     this.tpcContext = null;
+    this._sessionlessData = null;
 
     this.nscon = new nsi();
     finalizationRegistry.register(this, this.nscon);
@@ -1233,6 +1283,55 @@ class ThinConnectionImpl extends ConnectionImpl {
       errors.throwErr(errors.ERR_UNKNOWN_TRANSACTION_STATE, message.state);
     }
   }
+  //---------------------------------------------------------------------------
+  // Ensure no sessionless transaction was started through server procedure
+  //---------------------------------------------------------------------------
+  _validateSessionlessState() {
+    if (this._sessionlessData?.startedOnServer) {
+      errors.throwErr(errors.ERR_SESSIONLESS_DIFFERING_METHODS);
+    }
+  }
+
+  //---------------------------------------------------------------------------
+  // Begin/Resume a sessionless transaction with provided transactionId
+  //---------------------------------------------------------------------------
+  async startSessionlessTransaction(transactionId, timeout, flags,
+    deferRoundTrip) {
+    this._validateSessionlessState();
+    if (this._sessionlessData)
+      errors.throwErr(errors.ERR_SESSIONLESS_ALREADY_ACTIVE);
+    const message = new messages.TransactionSwitchMessage(this);
+    message.xid = {
+      globalTransactionId: transactionId,
+      branchQualifier: "",
+      formatId: constants.TNS_TPC_TRANS_SESSIONLESS_FORMAT
+    };
+    message.timeout = timeout;
+    message.operation = constants.TNS_TPC_TXN_START;
+    message.flags = constants.TNS_TPC_TRANS_SESSIONLESS | flags;
+    if (deferRoundTrip) {
+      message.messageType = constants.TNS_MSG_TYPE_PIGGYBACK;
+      this._sessionlessData = {
+        piggyback: message,
+        pending: true
+      };
+    } else {
+      await this._protocol._processMessage(message);
+    }
+  }
+
+  //---------------------------------------------------------------------------
+  // Suspend the active sessionless transaction
+  //---------------------------------------------------------------------------
+  async suspendSessionlessTransaction() {
+    this._validateSessionlessState();
+    if (!this._sessionlessData)
+      errors.throwErr(errors.ERR_SESSIONLESS_INACTIVE);
+    const message = new messages.TransactionSwitchMessage(this);
+    message.operation = constants.TNS_TPC_TXN_DETACH;
+    message.flags = constants.TNS_TPC_TRANS_SESSIONLESS;
+    await this._protocol._processMessage(message);
+  }
 
 
   //---------------------------------------------------------------------------
@@ -1273,6 +1372,14 @@ class ThinConnectionImpl extends ConnectionImpl {
     return this.internalName;
   }
 
+  //---------------------------------------------------------------------------
+  // Returns the Logical Transaction ID (ltxid) associated with the connection.
+  // Used with Oracle Database Transaction Guard feature.
+  //---------------------------------------------------------------------------
+  getLTXID() {
+    return this._ltxid;
+  }
+
   //---------------------------------------------------------------------------
   // Returns the Oracle Database domain name associated with the connection.
   //---------------------------------------------------------------------------

package/lib/thin/dbObject.js

@@ -55,10 +55,10 @@ class DbObjectPickleBuffer extends GrowableBuffer {
   // Reads the next byte and checks to see if the value is atomically null. If
   // not, the byte is returned to the buffer for further processing.
   //---------------------------------------------------------------------------
-  getIsAtomicNull() {
+  getIsAtomicNull(isCollection) {
     const value = this.readUInt8();
     if (value === constants.TNS_OBJ_ATOMIC_NULL ||
-        value === constants.TNS_NULL_LENGTH_INDICATOR) {
+      (isCollection && value === constants.TNS_NULL_LENGTH_INDICATOR)) {
       return true;
     }
     this.pos -= 1;
@@ -365,7 +365,7 @@ class ThinDbObjectImpl extends DbObjectImpl {
   // Unpacks a single value and returns it.
   //---------------------------------------------------------------------------
   _unpackValue(buf, type, typeClass) {
-    let isNull, obj, value;
+    let isNull, obj, value, isCollection;
     switch (type) {
       case types.DB_TYPE_NUMBER:
         return buf.readOracleNumber();
@@ -396,14 +396,16 @@ class ThinDbObjectImpl extends DbObjectImpl {
         return buf.readBool();
       case types.DB_TYPE_OBJECT:
       case types.DB_TYPE_XMLTYPE:
-        isNull = buf.getIsAtomicNull();
+        obj = new ThinDbObjectImpl(typeClass);
+        isCollection = obj._objType.isCollection ||
+          this._objType.isCollection;
+        isNull = buf.getIsAtomicNull(isCollection);
         if (isNull)
           return null;
-        obj = new ThinDbObjectImpl(typeClass);
         if (obj._objType.isXmlType) {
           return readXML(obj._objType._connection, buf.readBytesWithLength());
         }
-        if (obj._objType.isCollection || this._objType.isCollection) {
+        if (isCollection) {
           obj.packedData = Buffer.from(buf.readBytesWithLength());
         } else {
           obj._unpackDataFromBuf(buf);

package/lib/thin/lob.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
+// Copyright (c) 2022, 2025, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -220,10 +220,9 @@ class ThinLobImpl extends LobImpl {
     const options = {
       operation: constants.TNS_LOB_OP_CREATE_TEMP,
       sourceLobImpl: this,
-      amount: constants.TNS_DURATION_SESSION,
       destOffset: dbType._oraTypeNum,
       sourceOffset: dbType._csfrm,
-      sendAmount: true
+      destLength: constants.TNS_DURATION_SESSION
     };
     await this._sendMessage(options);
     await this._getChunkSizeAsync();