oracledb 6.1.0 → 6.2.0

package/README.md

@@ -1,10 +1,10 @@
-# node-oracledb version 6.1.0
+# node-oracledb version 6.2.0
 
 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.1.0 to connect Node.js 14.6, or later, to Oracle
+Use node-oracledb 6.2.0 to connect Node.js 14.6, or later, to Oracle
 Database.  Older versions of node-oracledb may work with older versions of
 Node.js.
 

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

@@ -0,0 +1 @@
+oracledb-6.2.0-darwin-x64.node v16.20.2 fe16239d5a7ceb588ae0e0766e74da2d20fb7af9 20785f251426f274f4216369b9259908a103384d Wed, 27 Sep 2023 05:56:04 GMT

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

@@ -0,0 +1 @@
+fe16239d5a7ceb588ae0e0766e74da2d20fb7af9

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

@@ -0,0 +1 @@
+oracledb-6.2.0-linux-arm64.node v18.15.0 fe16239d5a7ceb588ae0e0766e74da2d20fb7af9 20785f251426f274f4216369b9259908a103384d Wed, 27 Sep 2023 06:02:23 GMT

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

@@ -0,0 +1 @@
+oracledb-6.2.0-linux-x64.node v16.19.1 fe16239d5a7ceb588ae0e0766e74da2d20fb7af9 20785f251426f274f4216369b9259908a103384d Thu, 28 Sep 2023 16:23:40 GMT

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

@@ -0,0 +1 @@
+oracledb-6.2.0-win32-x64.node v16.19.0 fe16239d5a7ceb588ae0e0766e74da2d20fb7af9 20785f251426f274f4216369b9259908a103384d Wed, 27 Sep 2023 10:36:18 GMT

package/examples/dbconfig.js

@@ -30,7 +30,7 @@
  *   to the database.  Production applications should consider using
  *   External Authentication to avoid hard coded credentials.
  *
- *   To create a database user see
+ *   To create a database user, see
  *   https://blogs.oracle.com/sql/post/how-to-create-users-grant-them-privileges-and-remove-them-in-oracle-database
  *
  *   Applications can set the connectString value to an Easy Connect
@@ -46,8 +46,8 @@
  *   Commonly just the host_name and service_name are needed
  *   e.g. "localhost/orclpdb1" or "example.com/XEPDB1"
  *
- *   The Easy Connect syntax was enhanced in Oracle Database 19c to
- *   allow more options, refer to the documentation:
+ *   The Easy Connect syntax supports lots of options. To know more, please
+ *   refer to the latest Oracle documentation on Easy Connect syntax:
  *   https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-B0437826-43C1-49EC-A94D-B650B6A4A6EE
  *
  *   If using a tnsnames.ora file, the file can be in a default
@@ -66,17 +66,10 @@
  *   creating a pool should not be set when externalAuth is true.
  *
  * TROUBLESHOOTING
- *   Errors like:
- *     ORA-12541: TNS:no listener
- *   or
- *     ORA-12154: TNS:could not resolve the connect identifier specified
- *   indicate connectString is invalid.
- *
- *   The error:
- *     ORA-12514: TNS:listener does not currently know of requested in connect descriptor
- *   indicates connectString is invalid.  You are reaching a computer
- *   with Oracle installed but the service name isn't known.
- *   Use 'lsnrctl services' on the database server to find available services
+ *   Refer to the Error Handling section in node-oracledb documentation
+ *   to understand the different types of errors in both the Thin and Thick
+ *   modes of node-oracledb:
+ *   https://node-oracledb.readthedocs.io/en/latest/user_guide/exception_handling.html#errors-in-thin-and-thick-modes
  *
  *****************************************************************************/
 

package/lib/connection.js

@@ -1074,7 +1074,7 @@ class Connection extends EventEmitter {
   //
   // Returns the health status of the connection. If this function returns
   // false, the caller should close the connection.
-  // ---------------------------------------------------------------------------
+  //---------------------------------------------------------------------------
   isHealthy() {
     return (this._impl !== undefined && !this._closing &&
       this._impl.isHealthy());

package/lib/dbObject.js

@@ -319,6 +319,15 @@ class BaseDbObject {
     return this._objType.schema;
   }
 
+  //---------------------------------------------------------------------------
+  // packageName
+  //
+  // Property for the packageName of the database object type.
+  //---------------------------------------------------------------------------
+  get packageName() {
+    return this._objType.packageName;
+  }
+
   //---------------------------------------------------------------------------
   // setElement()
   //

package/lib/errors.js

@@ -466,7 +466,7 @@ function assertArgCount(args, minArgCount, maxArgCount) {
 //-----------------------------------------------------------------------------
 // assertParamPropBool()
 //
-// Asserts that the property value of a parmeter is a boolean value (or
+// Asserts that the property value of a parameter is a boolean value (or
 // undefined).
 //-----------------------------------------------------------------------------
 function assertParamPropBool(obj, parameterNum, propName) {
@@ -479,7 +479,7 @@ function assertParamPropBool(obj, parameterNum, propName) {
 //-----------------------------------------------------------------------------
 // assertParamPropFunction()
 //
-// Asserts that the property value of a parmeter is a function (or undefined).
+// Asserts that the property value of a parameter is a function (or undefined).
 //-----------------------------------------------------------------------------
 function assertParamPropFunction(obj, parameterNum, propName) {
   if (obj[propName] !== undefined) {
@@ -491,7 +491,7 @@ function assertParamPropFunction(obj, parameterNum, propName) {
 //-----------------------------------------------------------------------------
 // assertParamPropInt()
 //
-// Asserts that the property value of a parmeter is an integer value (or
+// Asserts that the property value of a parameter is an integer value (or
 // undefined).
 //-----------------------------------------------------------------------------
 function assertParamPropInt(obj, parameterNum, propName) {
@@ -504,7 +504,7 @@ function assertParamPropInt(obj, parameterNum, propName) {
 //-----------------------------------------------------------------------------
 // assertParamPropUnsignedInt()
 //
-// Asserts that the property value of a parmeter is a positive integer value
+// Asserts that the property value of a parameter is a positive integer value
 // (or undefined).
 //-----------------------------------------------------------------------------
 function assertParamPropUnsignedInt(obj, parameterNum, propName) {
@@ -517,7 +517,7 @@ function assertParamPropUnsignedInt(obj, parameterNum, propName) {
 //-----------------------------------------------------------------------------
 // assertParamPropString()
 //
-// Asserts that the property value of a parmeter is a function (or undefined).
+// Asserts that the property value of a parameter is a string value (or undefined).
 //-----------------------------------------------------------------------------
 function assertParamPropString(obj, parameterNum, propName) {
   if (obj[propName] !== undefined) {
@@ -529,7 +529,7 @@ function assertParamPropString(obj, parameterNum, propName) {
 //-----------------------------------------------------------------------------
 // assertParamPropValue()
 //
-// Asserts that the property value of a parmeter passes the specified
+// Asserts that the property value of a parameter passes the specified
 // condition.
 //-----------------------------------------------------------------------------
 function assertParamPropValue(condition, parameterNum, propName) {
@@ -540,7 +540,7 @@ function assertParamPropValue(condition, parameterNum, propName) {
 //-----------------------------------------------------------------------------
 // assertParamValue()
 //
-// Asserts that the parmeter value passes the specified condition.
+// Asserts that the parameter value passes the specified condition.
 //-----------------------------------------------------------------------------
 function assertParamValue(condition, parameterNum) {
   assert(condition, ERR_INVALID_PARAMETER_VALUE, parameterNum);

package/lib/oracledb.js

@@ -69,22 +69,26 @@ const defaultPoolAlias = 'default';
 let _initOracleClientArgs;
 
 // Load the Oracledb binary
-function _initCLib() {
+function _initCLib(options) {
   /*global __non_webpack_require__*/  // quieten eslint
   const requireBinary = (typeof __non_webpack_require__ === 'function') ? __non_webpack_require__ : require; // See Issue 1156
-
   const binaryLocations = [
     '../' + nodbUtil.RELEASE_DIR + '/' + nodbUtil.BINARY_FILE,  // pre-built binary
-    '../' + nodbUtil.RELEASE_DIR + '/' + 'oracledb.node',       // binary built from source
-    '../build/Debug/oracledb.node',                             // debug binary
+    '../' + nodbUtil.RELEASE_DIR + '/' + nodbUtil.BUILD_FILE,   // binary built from source
+    '../build/Debug/' + nodbUtil.BUILD_FILE,                    // debug binary
     // Paths for Webpack.
     // Note: to use node-oracledb Thick mode, you will need a Webpack copy plugin to
     // copy 'node_modules/oracledb/build/' to the output directory,
     // see https://github.com/oracle/node-oracledb/issues/1156
     // If you want to use only node-oracledb Thin mode, a copy plugin is not needed.
     './node_modules/oracledb/' + nodbUtil.RELEASE_DIR + '/' + nodbUtil.BINARY_FILE,
-    './node_modules/oracledb/' + nodbUtil.RELEASE_DIR + '/' + 'oracledb.node'
+    './node_modules/oracledb/' + nodbUtil.RELEASE_DIR + '/' + nodbUtil.BUILD_FILE
   ];
+
+  if (options.binaryDir !== undefined) {
+    binaryLocations.splice(0, 0, options.binaryDir + '/' + nodbUtil.BINARY_FILE,
+      options.binaryDir + '/' + nodbUtil.BUILD_FILE);
+  }
   let oracledbCLib;
   for (let i = 0; i < binaryLocations.length; i++) {
     try {
@@ -682,12 +686,13 @@ function initOracleClient(arg1) {
     errors.assertParamPropString(options, 1, "configDir");
     errors.assertParamPropString(options, 1, "errorUrl");
     errors.assertParamPropString(options, 1, "driverName");
+    errors.assertParamPropString(options, 1, "binaryDir");
   }
   if (settings.thinDriverInitialized) {
     errors.throwErr(errors.ERR_THIN_CONNECTION_ALREADY_CREATED);
   }
   if (_initOracleClientArgs === undefined) {
-    const oracledbCLib = _initCLib();
+    const oracledbCLib = _initCLib(options);
     if (options.driverName === undefined)
       options.driverName = constants.DEFAULT_DRIVER_NAME + " thk";
     if (options.errorUrl === undefined)

package/lib/sodaCollection.js

@@ -188,6 +188,16 @@ class SodaCollection {
     return doc;
   }
 
+  //---------------------------------------------------------------------------
+  // listIndexes()
+  //
+  //   To obtain all indices from the collection
+  //---------------------------------------------------------------------------
+  async listIndexes() {
+    const arr = await this._impl.listIndexes();
+    return arr.map(i => JSON.parse(i));
+  }
+
   //---------------------------------------------------------------------------
   // metaData()
   //
@@ -262,6 +272,7 @@ nodbUtil.wrapFns(SodaCollection.prototype,
   "insertManyAndGet",
   "insertOne",
   "insertOneAndGet",
+  "listIndexes",
   "save",
   "saveAndGet",
   "truncate");

package/lib/sodaOperation.js

@@ -94,6 +94,22 @@ class SodaOperation {
     }
   }
 
+
+  //---------------------------------------------------------------------------
+  // lock()
+  //
+  //  Pessimistic locking - similar to SELECT FOR UPDATE, these documents
+  //  cannot be updated by other threads until an explicit commit/rollback is
+  //  called.  With autoCommit set to true is applicable only for one immediate
+  //  operation and is not recommended in this context
+  //---------------------------------------------------------------------------
+  lock()  {
+    errors.assertArgCount(arguments, 0, 0);
+    this._options.lock = true;
+    return this;
+  }
+
+
   //---------------------------------------------------------------------------
   // replaceOne()
   //

package/lib/thin/connection.js

@@ -59,23 +59,29 @@ class ThinConnectionImpl extends ConnectionImpl {
    * @return {Promise}
    */
   async close() {
-    if (this._protocol.txnInProgress) {
-      await this.rollback();
-    }
-    this._protocol.callTimeout = 0;      // not applicable for close
-    if (this._drcpEnabled) {
-      await this._sessRelease();
-      this._drcpEstablishSession = true;
-    }
+    try {
+      if (this._protocol.txnInProgress) {
+        await this.rollback();
+      }
+      this._protocol.callTimeout = 0;      // not applicable for close
+      if (this._drcpEnabled) {
+        await this._sessRelease();
+        this._drcpEstablishSession = true;
+      }
 
-    if (this._pool && !this._dropSess) {
-      await this._pool.release(this);
-    } else {
-      if (!this._drcpEnabled) {
-        const message = new messages.LogOffMessage(this);
-        await this._protocol._processMessage(message);
+      if (this._pool && !this._dropSess) {
+        await this._pool.release(this);
+      } else {
+        if (!this._drcpEnabled) {
+          const message = new messages.LogOffMessage(this);
+          await this._protocol._processMessage(message);
+        }
+        this.nscon.disconnect();
       }
-      this.nscon.disconnect();
+    } catch (err) {
+      // immediate close of open socket on failure
+      // exception won't be thrown to user
+      this.nscon.disconnect(sqlNetConstants.NSFIMM);
     }
   }
 
@@ -153,6 +159,98 @@ class ThinConnectionImpl extends ConnectionImpl {
     }
   }
 
+  //---------------------------------------------------------------------------
+  // _execute()
+  //
+  // Calls the RPC that executes a SQL statement and returns the results.
+  //---------------------------------------------------------------------------
+  async _execute(statement, numIters, binds, options, executeManyFlag) {
+
+    // perform binds
+    const numBinds = statement.bindInfoList.length;
+    const numVars = binds.length;
+    if (numBinds !== numVars && (numVars === 0 || !binds[0].name)) {
+      errors.throwErr(errors.ERR_WRONG_NUMBER_OF_POSITIONAL_BINDS, numBinds, numVars);
+    }
+    for (let i = 0; i < binds.length; i++) {
+      await this._bind(statement, binds[i], i + 1);
+    }
+    if (statement.isPlSql && (options.batchErrors || options.dmlRowCounts)) {
+      errors.throwErr(errors.ERR_EXEC_MODE_ONLY_FOR_DML);
+    }
+
+    // send database request
+    const message = new messages.ExecuteMessage(this, statement, options);
+    message.numExecs = numIters;
+    message.arrayDmlRowCounts = options.dmlRowCounts;
+    message.batchErrors = options.batchErrors;
+    if (statement.isPlSql && statement.requiresFullExecute) {
+      message.numExecs = 1;
+      await this._protocol._processMessage(message);
+      statement.requiresFullExecute = false;
+      message.numExecs = numIters - 1;
+      message.offset = 1;
+    }
+    if (message.numExecs > 0) {
+      await this._protocol._processMessage(message);
+      statement.requiresFullExecute = false;
+    }
+
+    // if a define is required, send an additional request to the database
+    if (statement.requiresDefine && statement.sql) {
+      statement.requiresFullExecute = true;
+      await this._protocol._processMessage(message);
+      statement.requiresFullExecute = false;
+      statement.requiresDefine = false;
+    }
+
+    // process results
+    const result = {};
+    if (statement.numQueryVars > 0) {
+      result.resultSet = message.resultSet;
+    } else {
+      statement.bufferRowIndex = 0;
+      const outBinds = thinUtil.getOutBinds(statement, numIters,
+        executeManyFlag);
+      if (outBinds) {
+        result.outBinds = outBinds;
+      }
+      if (executeManyFlag) {
+        if (!statement.isPlSql) {
+          result.rowsAffected = statement.rowCount;
+          delete statement.rowCount;
+        }
+        if (options.dmlRowCounts) {
+          result.dmlRowCounts = options.dmlRowCounts;
+        }
+        if (options.batchErrors) {
+          result.batchErrors = options.batchErrors;
+        }
+      } else {
+        if (statement.isPlSql && options.implicitResultSet) {
+          result.implicitResults = options.implicitResultSet;
+        }
+        if (statement.lastRowid) {
+          result.lastRowid = statement.lastRowid;
+          delete statement.lastRowid;
+        }
+        if (statement.isPlSql) {
+          if (statement.rowCount) {
+            result.rowsAffected = statement.rowCount;
+          }
+        } else {
+          result.rowsAffected = statement.rowCount || 0;
+        }
+        if (statement.rowCount) {
+          delete statement.rowCount;
+        }
+      }
+      this._returnStatement(statement);
+    }
+
+    return result;
+  }
+
   //---------------------------------------------------------------------------
   // _parseElementType()
   //
@@ -772,26 +870,6 @@ class ThinConnectionImpl extends ConnectionImpl {
     return resultSet;
   }
 
-  //---------------------------------------------------------------------------
-  // Prepares the sql given by user and binds the value to the statement object
-  //---------------------------------------------------------------------------
-  async _prepareAndBind(sql, binds, options, isParse = false) {
-    const stmt = this._prepare(sql, options);
-    let position = 0;
-    if (!isParse) {
-      const numBinds = stmt.bindInfoList.length;
-      const numVars = binds.length;
-      if (numBinds !== numVars && (numVars === 0 || !binds[0].name)) {
-        errors.throwErr(errors.ERR_WRONG_NUMBER_OF_POSITIONAL_BINDS, numBinds, numVars);
-      }
-      for (const variable of binds) {
-        await this._bind(stmt, variable, position + 1);
-        position += 1;
-      }
-    }
-    return stmt;
-  }
-
   //---------------------------------------------------------------------------
   // Clears the statement cache for the connection
   //---------------------------------------------------------------------------
@@ -812,139 +890,46 @@ class ThinConnectionImpl extends ConnectionImpl {
   }
 
   //---------------------------------------------------------------------------
-  // Parses the sql given by User
-  // calls the OAL8 RPC that parses the SQL statement and returns the metadata
-  // information for a statment.
+  // getStatementInfo()
+  //
+  // Parses the SQL statement and returns information about the statement.
   //---------------------------------------------------------------------------
   async getStatementInfo(sql) {
     const options = {};
     const result = {};
-    const statement = await this._prepareAndBind(sql, null, options, true);
+    const statement = this._prepare(sql, options);
     options.connection = this;
-    // parse the statement (but not for DDL which doesn't support it)
-    if (!statement.isDdl) {
-      const message = new messages.ExecuteMessage(this, statement, options);
-      message.parseOnly = true;
-      await this._protocol._processMessage(message);
-    }
-    if (statement.numQueryVars > 0) {
-      result.metaData = thinUtil.getMetadataMany(statement.queryVars);
-    }
-    result.bindNames = Array.from(statement.bindInfoDict.keys());
-    result.statementType = statement.statementType;
-    return result;
-  }
-
-  //---------------------------------------------------------------------------
-  // Prepares the sql given by the user,
-  // calls the OAL8 RPC that executes a SQL statement and returns the results.
-  //---------------------------------------------------------------------------
-  async execute(sql, numIters, binds, options, executeManyFlag) {
-    const result = {};
-    if (executeManyFlag) {
-      return await this.executeMany(sql, numIters, binds, options);
-    }
-    const statement = await this._prepareAndBind(sql, binds, options);
-
-    // send the initial request to the database
-    const message = new messages.ExecuteMessage(this, statement, options);
-    message.numExecs = 1;
-    await this._protocol._processMessage(message);
-    statement.requiresFullExecute = false;
-
-    // if a define is required, send an additional request to the database
-    if (statement.requiresDefine && statement.sql) {
-      statement.requiresFullExecute = true;
-      await this._protocol._processMessage(message);
-      statement.requiresFullExecute = false;
-      statement.requiresDefine = false;
-    }
-
-    // process message results
-    if (statement.numQueryVars > 0) {
-      result.resultSet = message.resultSet;
-    } else {
-      statement.bufferRowIndex = 0;
-      const bindVars = thinUtil.getBindVars(statement);
-      const outBinds = thinUtil.getExecuteOutBinds(bindVars);
-      if (outBinds) {
-        result.outBinds = outBinds;
-      }
-      if (statement.isPlSql) {
-        if (options.implicitResultSet) {
-          result.implicitResults = options.implicitResultSet;
-        }
-      }
-      if (statement.lastRowid) {
-        result.lastRowid = statement.lastRowid;
-        delete statement.lastRowid;
-      }
-      if (statement.isPlSql) {
-        if (statement.rowCount) {
-          result.rowsAffected = statement.rowCount;
-        }
-      } else {
-        result.rowsAffected = statement.rowCount || 0;
+    try {
+      if (!statement.isDdl) {
+        const message = new messages.ExecuteMessage(this, statement, options);
+        message.parseOnly = true;
+        await this._protocol._processMessage(message);
       }
-      if (statement.rowCount) {
-        delete statement.rowCount;
+      if (statement.numQueryVars > 0) {
+        result.metaData = thinUtil.getMetadataMany(statement.queryVars);
       }
+      result.bindNames = Array.from(statement.bindInfoDict.keys());
+      result.statementType = statement.statementType;
+      return result;
+    } finally {
       this._returnStatement(statement);
     }
-
-    return result;
   }
 
   //---------------------------------------------------------------------------
-  // executeMany()
+  // execute()
   //
-  // Prepares the sql given by the user, calls the OAL8 RPC that executes a SQL
-  // statement multiple times and returns the results.
+  // Calls the RPC that executes a SQL statement and returns the results.
   //---------------------------------------------------------------------------
-  async executeMany(sql, numIters, binds, options) {
-    const statement = await this._prepareAndBind(sql, binds, options);
-    if (statement.isPlSql && (options.batchErrors || options.dmlRowCounts)) {
-      errors.throwErr(errors.ERR_EXEC_MODE_ONLY_FOR_DML);
-    }
-
-    // send database request
-    const message = new messages.ExecuteMessage(this, statement, options);
-    message.numExecs = numIters;
-    message.arrayDmlRowCounts = options.dmlRowCounts;
-    message.batchErrors = options.batchErrors;
-    if (statement.isPlSql && statement.requiresFullExecute) {
-      message.numExecs = 1;
-      await this._protocol._processMessage(message);
-      statement.requiresFullExecute = false;
-      message.numExecs = numIters - 1;
-      message.offset = 1;
-    }
-    if (message.numExecs > 0) {
-      await this._protocol._processMessage(message);
-    }
-
-    // process results
-    const returnObj = {};
-    statement.bufferRowIndex = 0;
-    const bindVars = thinUtil.getBindVars(statement);
-    const outBinds = thinUtil.getExecuteManyOutBinds(bindVars, numIters);
-    if (outBinds) {
-      returnObj.outBinds = outBinds;
-    }
-    const rowsAffected = !statement.isPlSql ? statement.rowCount : undefined;
-    if (rowsAffected) {
-      returnObj.rowsAffected = rowsAffected;
-      delete statement.rowCount;
-    }
-    if (options.dmlRowCounts) {
-      returnObj.dmlRowCounts = options.dmlRowCounts;
-    }
-    if (options.batchErrors) {
-      returnObj.batchErrors = options.batchErrors;
+  async execute(sql, numIters, binds, options, executeManyFlag) {
+    const statement = this._prepare(sql, options);
+    try {
+      return await this._execute(statement, numIters, binds, options,
+        executeManyFlag);
+    } catch (err) {
+      this._returnStatement(statement);
+      throw err;
     }
-    this._returnStatement(statement);
-
-    return returnObj;
   }
 
   //---------------------------------------------------------------------------

package/lib/thin/dbObject.js

@@ -367,7 +367,10 @@ class ThinDbObjectImpl extends DbObjectImpl {
       case types.DB_TYPE_NCHAR:
         return buf.readStr(constants.CSFRM_NCHAR);
       case types.DB_TYPE_RAW:
-        return Buffer.from(buf.readBytesWithLength());
+        value = buf.readBytesWithLength();
+        if (value !== null)
+          value = Buffer.from(value);
+        return value;
       case types.DB_TYPE_BINARY_DOUBLE:
         return buf.readBinaryDouble();
       case types.DB_TYPE_BINARY_FLOAT: