oracledb 6.9.0 → 7.0.0

package/lib/connection.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2016, 2025, Oracle and/or its affiliates.
+// Copyright (c) 2016, 2026, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -44,6 +44,11 @@ const settings = require('./settings.js');
 const transformer = require('./transformer.js');
 const types = require('./types.js');
 const oson = require('./impl/datahandlers/oson.js');
+const traceHandler = require('./traceHandler.js');
+const EndUserSecurityContext = require('./endUserSecurityContext.js');
+
+const APP_CONTEXT_KEY_MAX_BYTES = 128;
+const APP_CONTEXT_VALUE_MAX_BYTES = 4 * 1000;
 
 // global mapping of subscriptions; these cannot be tied to a particular
 // connection or pool since subscriptions can be created with one connection
@@ -58,7 +63,7 @@ const defaultNumberConverter = (v) => (v === null) ? null : parseFloat(v);
 //
 // 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.
+// converters are invoked when retrieving DBObject values.
 //---------------------------------------------------------------------------
 function _determineDbObjTypeConverter(metadata, options) {
   // clear any previous converter functions that may have been
@@ -290,6 +295,9 @@ class Connection extends EventEmitter {
     // function identifying an object type
     if (bindUnit.type !== undefined) {
       if (typeof bindUnit.type === 'string') {
+        if (this._impl.pipelineMode) {
+          errors.throwErr(errors.ERR_PIPELINE_DBOBJECTS_NOT_SUPPORTED);
+        }
         bindInfo.type = types.DB_TYPE_OBJECT;
         bindInfo.typeClass = await this._getDbObjectClassForName(bindUnit.type);
         bindInfo.objType = bindInfo.typeClass._objType;
@@ -369,6 +377,8 @@ class Connection extends EventEmitter {
     }
     if (bindInfo.type === types.DB_TYPE_OBJECT &&
         bindInfo.typeClass === undefined) {
+      if (this._impl.pipelineMode)
+        errors.throwErr(errors.ERR_PIPELINE_DBOBJECTS_NOT_SUPPORTED);
       bindInfo.typeClass = await this._getDbObjectClass(value._objType);
       bindInfo.objType = bindInfo.typeClass._objType;
     }
@@ -827,7 +837,13 @@ 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);
+        traceHandler.getTraceInstance()?.onPoolRelease(this._pool);
+      } else {
+        await this._impl.close(options);
+      }
     } finally {
       this._closing = false;
     }
@@ -839,7 +855,12 @@ class Connection extends EventEmitter {
       }
     }
     this._dbObjectClasses.clear();
-    this.emit('_afterConnClose');
+  }
+
+  async _commit() {
+    errors.assertArgCount(arguments, 0, 0);
+    errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
+    await this._impl.commit();
   }
 
   //---------------------------------------------------------------------------
@@ -848,9 +869,7 @@ class Connection extends EventEmitter {
   // Commits the current transaction.
   //---------------------------------------------------------------------------
   async commit() {
-    errors.assertArgCount(arguments, 0, 0);
-    errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
-    await this._impl.commit();
+    await this._commit.apply(this, arguments);
   }
 
   //---------------------------------------------------------------------------
@@ -938,6 +957,27 @@ class Connection extends EventEmitter {
     return decoder.decode();
   }
 
+  setEndUserSecurityContext(context) {
+    errors.assertArgCount(arguments, 1, 1);
+    errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
+
+    if (typeof this.protocol !== 'string' || this.protocol !== 'TCPS') {
+      errors.throwErr(errors.ERR_END_USER_SECURITY_CONTEXT_REQUIRES_TCPS);
+    }
+
+    errors.assertParamValue(
+      context instanceof EndUserSecurityContext,
+      1
+    );
+
+    this._impl.setEndUserSecurityContext(context);
+  }
+
+  clearEndUserSecurityContext() {
+    errors.assertArgCount(arguments, 0, 0);
+    errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
+    this._impl.clearEndUserSecurityContext();
+  }
 
   //---------------------------------------------------------------------------
   // encode()
@@ -949,12 +989,7 @@ class Connection extends EventEmitter {
     return encoder.encode(transformer.transformJsonValue(value), this._impl._osonMaxFieldNameSize);
   }
 
-  //---------------------------------------------------------------------------
-  // execute()
-  //
-  // Executes a SQL statement and returns the results.
-  //---------------------------------------------------------------------------
-  async execute(sql, a2, a3) {
+  async _processExecuteArgs(sql, a2, a3) {
     const numIters = 1;
     let binds = [];
     let options = {};
@@ -989,50 +1024,100 @@ class Connection extends EventEmitter {
     }
     this._addDefaultsToExecOpts(options);
 
+    return {sql, numIters, binds, options, executeManyFlag: false};
+  }
+
+  async _execute() {
+
+    // process arguments
+    const { sql, numIters, binds, options, executeManyFlag } =
+    await this._processExecuteArgs.apply(this, arguments);
+
     // perform actual execute
     let result;
     try {
       if (this._impl._callLevelTraceData) {
         this._impl._callLevelTraceData.statement = sql;
       }
-      result = await this._impl.execute(sql, numIters, binds, options, false);
+      result = await this._impl.execute(sql, numIters, binds, options,
+        executeManyFlag);
     } catch (err) {
       if (err.errorNum === 1406)
         errors.throwErr(errors.ERR_INSUFFICIENT_BUFFER_FOR_BINDS);
       throw err;
     }
 
-    // convert ORA errors to NJS
+    return await this._transformExecuteResult(result, options);
+  }
+
+  //---------------------------------------------------------------------------
+  // execute()
+  //
+  // Executes a SQL statement and returns the results.
+  //---------------------------------------------------------------------------
+  async execute() {
+    return await this._execute.apply(this, arguments);
+  }
+
+  async _handleFetchForExecuteInPipeline(result, options) {
     if (result.warning) {
       result.warning = errors.transformErr(result.warning);
     }
 
-    // process queries; if a result set is not desired, fetch all of the rows
-    // from the result set and then destroy the result set
     if (result.resultSet !== undefined) {
-      const resultSet = new ResultSet();
-      resultSet._setup(this, result.resultSet);
-      result.metaData = resultSet._impl.metaData;
-      if (options.resultSet) {
-        result.resultSet = resultSet;
-      } else {
+      // just close resultSet for pipelineOp.opType 'execute'
+      // To fetch rows, 'fetch*' used instead in pipeline mode
+      await result.resultSet.close();
+      delete result.resultSet;
+    }
+
+    this._processOutBinds(result, options);
+    await this._processImplicitResults(result, options);
+  }
+
+  async _handleFetchInPipeline(result, resultSet, fetchOpPipeline) {
+    let shouldClose = false;
+    try {
+      if (fetchOpPipeline.opType === 'fetchOne') {
+        const row = await resultSet._getRow();
+        result.rows = row ? [row] : [];
+        shouldClose = true;
+      } else if (fetchOpPipeline.opType === 'fetchMany') {
+        if (fetchOpPipeline.numRows === 0)
+          result.rows = [];
+        else {
+          const maxRows = resultSet._impl.maxRows;
+          const rowsToFetch = (maxRows > 0) ?
+            Math.min(fetchOpPipeline.numRows, maxRows) :
+            fetchOpPipeline.numRows;
+          result.rows = await resultSet._doGetRows(rowsToFetch);
+        }
+        shouldClose = true;
+      } else
+      // fallback to fetchAll
         result.rows = await resultSet._getAllRows();
-        delete result.resultSet;
-      }
+    } finally {
+      if (shouldClose)
+        await resultSet._close();
+      delete result.resultSet;
     }
+  }
 
-    // process output binds
+  _processOutBinds(result, options) {
     if (result.outBinds !== undefined) {
       for (const [key, value] of Object.entries(result.outBinds)) {
         const val = this._transformOutBind(value, options);
         result.outBinds[key] = val;
       }
     }
+  }
 
-    // process implicit results; ensure all implicit results have their fetch
-    // array size fixed, or, if a result set is not requested, that all rows
-    // are fetched
+  async _processImplicitResults(result, options, fetchOpPipeline) {
     if (result.implicitResults) {
+      if (fetchOpPipeline) {
+        delete result.implicitResults;
+        return;
+      }
       for (const [key, impl] of Object.entries(result.implicitResults)) {
         const resultSet = new ResultSet();
         resultSet._setup(this, impl);
@@ -1043,16 +1128,47 @@ class Connection extends EventEmitter {
         }
       }
     }
+  }
+
+  async _transformExecuteResult(result, options, fetchOpPipeline) {
+    // convert ORA errors to NJS
+    if (result.warning) {
+      result.warning = errors.transformErr(result.warning);
+    }
+
+    // process queries; if a result set is not desired, fetch all of the rows
+    // from the result set and then destroy the result set
+    if (result.resultSet !== undefined) {
+      const resultSet = new ResultSet();
+      resultSet._setup(this, result.resultSet);
+      result.metaData = resultSet._impl.metaData;
+      if (!fetchOpPipeline) {
+        if (options.resultSet) {
+          result.resultSet = resultSet;
+        } else {
+          // for fetchAll, _getAllRows() get rows from buffered rows and
+          // then perform as many round trips as are required to
+          // complete the fetch
+          result.rows = await resultSet._getAllRows();
+          delete result.resultSet;
+        }
+      } else {
+        await this._handleFetchInPipeline(result, resultSet, fetchOpPipeline);
+      }
+    }
+
+    // process output binds
+    this._processOutBinds(result, options);
+
+    // process implicit results; ensure all implicit results have their fetch
+    // array size fixed, or, if a result set is not requested, that all rows
+    // are fetched
+    await this._processImplicitResults(result, options, fetchOpPipeline);
 
     return (result);
   }
 
-  //---------------------------------------------------------------------------
-  // executeMany()
-  //
-  // Executes a SQL statement multiple times and returns the results.
-  //---------------------------------------------------------------------------
-  async executeMany(sql, bindsOrNumIters, a3) {
+  async _processExecuteManyArgs(sql, bindsOrNumIters, userOptions) {
     let options = {};
     let binds = [];
     let numIters;
@@ -1060,7 +1176,7 @@ class Connection extends EventEmitter {
     errors.assertArgCount(arguments, 2, 3);
     errors.assertParamValue(typeof sql === 'string', 1);
     if (arguments.length == 3) {
-      options = this._verifyExecOpts(a3, true);
+      options = this._verifyExecOpts(userOptions, true);
     }
     this._addDefaultsToExecOpts(options);
     if (typeof bindsOrNumIters === 'number') {
@@ -1079,9 +1195,24 @@ class Connection extends EventEmitter {
     }
     errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
 
-    const result = await this._impl.execute(sql, numIters, binds, options,
-      true);
+    if (this._impl._callLevelTraceData) {
+      this._impl._callLevelTraceData.statement = sql;
+    }
+
+    return {sql, numIters, binds, options, executeManyFlag: true};
+  }
+
+  async _executeMany() {
+    const { sql, numIters, binds, options, executeManyFlag }
+    = await this._processExecuteManyArgs.apply(this, arguments);
+
+    const result = await this._impl.execute(sql, numIters, binds,
+      options, executeManyFlag);
 
+    return this._transformExecuteManyResult(result, options);
+  }
+
+  _transformExecuteManyResult(result, options) {
     // convert ORA warnings to NJS
     if (result.warning) {
       result.warning = errors.transformErr(result.warning);
@@ -1100,6 +1231,15 @@ class Connection extends EventEmitter {
     return result;
   }
 
+  //---------------------------------------------------------------------------
+  // executeMany()
+  //
+  // Executes a SQL statement multiple times and returns the results.
+  //---------------------------------------------------------------------------
+  async executeMany() {
+    return await this._executeMany.apply(this, arguments);
+  }
+
   //---------------------------------------------------------------------------
   // externalName
   //
@@ -1135,6 +1275,23 @@ class Connection extends EventEmitter {
     return this._impl && this._impl.getDbName();
   }
 
+  //---------------------------------------------------------------------------
+  // pdbName (READONLY)
+  //
+  // Property for identifying the container associated with connection.
+  //---------------------------------------------------------------------------
+  get pdbName() {
+    return this._impl && this._impl.getPdbName();
+  }
+
+  //---------------------------------------------------------------------------
+  // dbUniqueName (READONLY)
+  //
+  // Property for identifying the DB_UNIQUE_NAME of the Oracle Database.
+  //---------------------------------------------------------------------------
+  get dbUniqueName() {
+    return this._impl && this._impl.getDbUniqueName();
+  }
   //---------------------------------------------------------------------------
   // hostName (READONLY)
   //
@@ -1457,7 +1614,7 @@ class Connection extends EventEmitter {
   //---------------------------------------------------------------------------
   // resumeSessionlessTransaction()
   //
-  // Resume an existing sessionlesss transaction using given transactionId
+  // Resume an existing sessionless transaction using given transactionId
   //---------------------------------------------------------------------------
   async resumeSessionlessTransaction(transactionId, options = {}) {
     errors.assertArgCount(arguments, 1, 2);
@@ -1777,6 +1934,157 @@ class Connection extends EventEmitter {
     await this._impl.tpcRollback(normalizedXid);
   }
 
+  //---------------------------------------------------------------------------
+  // directPathLoad()
+  //
+  // Performs a direct path load into the specified table.
+  //---------------------------------------------------------------------------
+  async directPathLoad(schema, table, columns, data) {
+    errors.assertArgCount(arguments, 4, 5);
+    errors.assertParamValue(typeof schema === 'string', 1);
+    errors.assertParamValue(typeof table === 'string', 2);
+    errors.assertParamValue(Array.isArray(columns) && columns.length, 3);
+    if (!Array.isArray(data) || !data.every(Array.isArray))
+      errors.throwErr(errors.ERR_DPL_INVALID_ROW_DATA);
+    errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
+    return await this._impl.directPathLoad(schema, table, columns, data);
+  }
+
+  _createFetchTypeHandler(fetchLobs) {
+    if (fetchLobs) {
+      // Returning undefined → default behavior → LOB locators
+      return undefined;
+    }
+    // Auto-fetch LOBs
+    return (metadata) => {
+      switch (metadata.dbType) {
+        case types.DB_TYPE_CLOB:
+        case types.DB_TYPE_NCLOB:
+          return { type: types.DB_TYPE_VARCHAR };
+
+        case types.DB_TYPE_BLOB:
+          return { type: types.DB_TYPE_RAW };
+
+        default:
+          return undefined;
+      }
+    };
+  }
+
+  async _runPipelineOpWithoutPipelining(resultImpl) {
+    const op = resultImpl.op;
+    const opType = op.opType;
+    let res = {};
+    if (opType === 'commit') {
+      res = await this._commit();
+    } else if (opType === 'execute') {
+      res = await this._execute(op.statement, op.parameters, op.options);
+      if (res.rows) {
+        res.rows = undefined;
+      }
+    } else if (opType === 'executeMany')
+      res = await this._executeMany(op.statement, op.parameters, op.options);
+    else if (['fetchOne', 'fetchMany', 'fetchAll'].includes(opType)) {
+
+      // 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);
+      let shouldClose = false;
+      try {
+        res = await this._execute(op.statement, op.parameters, op.options);
+        if (opType === 'fetchOne') {
+          const row = await res.resultSet._getRow();
+          res.rows = row ? [row] : [];
+          shouldClose = true;
+        } else if (opType === 'fetchMany') {
+          if (op.numRows === 0) {
+            res.rows = [];
+          } else {
+            const maxRows = res.resultSet._impl.maxRows;
+            const rowsToFetch = (maxRows > 0) ?
+              Math.min(op.numRows, maxRows) :
+              op.numRows;
+            res.rows = await res.resultSet._doGetRows(rowsToFetch);
+          }
+          shouldClose = true;
+        } else if (opType === 'fetchAll') {
+          res.rows = await res.resultSet._getAllRows();
+        }
+      } finally {
+        if (shouldClose)
+          await res.resultSet._close();
+        delete res.resultSet;
+      }
+    } else
+      errors.throwErr(errors.ERR_PIPELINE_OPERATION_NOT_SUPPORTED, opType);
+    resultImpl.result = res;
+  }
+
+  async _runPipelineWithoutPipelining(resultsImpl, continueOnError) {
+    const savedCallTimeout = this.callTimeout;
+    try {
+
+      // For consistency with protocol-level pipelining, do not enforce
+      // call timeout while executing the fallback non-pipelined flow.
+      if (savedCallTimeout > 0)
+        this.callTimeout = 0;
+      for (const resultImpl of resultsImpl) {
+        try {
+          await this._runPipelineOpWithoutPipelining(resultImpl);
+        } catch (err) {
+          if (!continueOnError)
+            throw (err);
+          resultImpl.error = err;
+        }
+      }
+      return this._buildPipelineResults(resultsImpl);
+    } finally {
+      if (savedCallTimeout > 0)
+        this.callTimeout = savedCallTimeout;
+    }
+  }
+
+  _buildPipelineResults(resultsImpl) {
+    const results = [];
+    for (let i = 0; i < resultsImpl.length; i++) {
+      results[i] = resultsImpl[i].result;
+      if (resultsImpl[i].error) {
+        if (!results[i]) results[i] = {};
+        results[i].error = resultsImpl[i].error;
+      }
+    }
+    return results;
+  }
+
+  //---------------------------------------------------------------------------
+  // runPipeline()
+  //
+  // It runs the list of operations and returns an result array.
+  //---------------------------------------------------------------------------
+  async runPipeline(pipeline, continueOnError = false) {
+    errors.assertArgCount(arguments, 1, 2);
+    errors.assertParamValue(typeof continueOnError === 'boolean', 2);
+    errors.assertParamValue(pipeline?.constructor?.name === 'Pipeline', 1);
+    // validate connection state
+    errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
+    const results = [];
+    for (const op of pipeline.operations) {
+      // sample result (will be filled with corresponding operation result,
+      // like rows, rowsAffected, metadata, error)
+      results.push({op, result: {}});
+    }
+
+    // Use protocol-level pipelining only when the server supports it and
+    // when there is more than one operation to benefit from batching.
+    if (this._impl.supportsPipelining() && pipeline.operations.length > 1)
+      return await this._impl.runPipelineWithPipelining(this, results,
+        continueOnError);
+    else
+      return await this._runPipelineWithoutPipelining(results,
+        continueOnError);
+  }
+
   //---------------------------------------------------------------------------
   // unsubscribe()
   //
@@ -1796,6 +2104,75 @@ class Connection extends EventEmitter {
     }, 0);
   }
 
+  //---------------------------------------------------------------------------
+  // appContext()
+  //
+  // Add Application Context, keyValues identified by name, namespaceName.
+  //---------------------------------------------------------------------------
+  appContext(namespaceName, keyValues) {
+    errors.assertArgCount([namespaceName, keyValues], 2, 2);
+    errors.assertParamValue(typeof namespaceName === 'string', 1);
+    if (namespaceName.length === 0) {
+      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) {
+      errors.assertParamValue(nodbUtil.isObject(entry) && !Array.isArray(entry), 2);
+      const entries = Object.entries(entry);
+      const [entryKey, entryValue] = entries[0] ?? [];
+
+      errors.assert(entries.length === 1 &&
+        typeof entryKey === 'string' &&
+        typeof entryValue === 'string',
+      errors.ERR_APP_CONTEXT_INVALID_KEY_VALUE,
+      typeof entryKey,
+      typeof entryValue);
+
+      const keyLength = Buffer.byteLength(entryKey);
+      errors.assert(keyLength <= APP_CONTEXT_KEY_MAX_BYTES,
+        errors.ERR_APP_CONTEXT_KEY_TOO_LONG,
+        keyLength,
+        APP_CONTEXT_KEY_MAX_BYTES);
+
+      const valueLength = Buffer.byteLength(entryValue);
+      errors.assert(valueLength <= APP_CONTEXT_VALUE_MAX_BYTES,
+        errors.ERR_APP_CONTEXT_VALUE_TOO_LONG,
+        valueLength,
+        APP_CONTEXT_VALUE_MAX_BYTES);
+    }
+
+    this._impl.appContext(namespaceName, keyValues);
+  }
+
+  //---------------------------------------------------------------------------
+  // clearAppContext()
+  //
+  // Clears the Application Context, keyValues identified by name.
+  //---------------------------------------------------------------------------
+  clearAppContext(namespaceName) {
+    errors.assertArgCount([namespaceName], 1, 1);
+    errors.assertParamValue(typeof namespaceName === 'string', 1);
+    this._impl.clearAppContext(namespaceName);
+  }
+
+  //---------------------------------------------------------------------------
+  // Symbol.asyncDispose
+  //
+  // Implement explicit resource management.
+  //---------------------------------------------------------------------------
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
+
 }
 
 // adjust functions to support the old callback style and to serialize calls
@@ -1811,12 +2188,14 @@ nodbUtil.wrapFns(Connection.prototype,
   "close",
   "commit",
   "createLob",
+  "directPathLoad",
   "execute",
   "executeMany",
   "getDbObjectClass",
   "getQueue",
   "getStatementInfo",
   "ping",
+  "runPipeline",
   "resumeSessionlessTransaction",
   "rollback",
   "shutdown",