oracledb 5.4.0 → 6.0.0

package/lib/poolStatistics.js

@@ -1,16 +1,24 @@
-// Copyright (c) 2021, 2022, Oracle and/or its affiliates.
+// Copyright (c) 2021, 2023, Oracle and/or its affiliates.
+
 //-----------------------------------------------------------------------------
 //
-// You may not use the identified files except in compliance with the Apache
-// License, Version 2.0 (the "License.")
+// 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
-// http://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.
+//    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.
 //
@@ -18,6 +26,8 @@
 
 'use strict';
 
+const settings = require('./settings.js');
+
 //-----------------------------------------------------------------------------
 // class PoolStatistics
 //  collection of statistics metrics for Pool object
@@ -68,14 +78,18 @@ class PoolStatistics {
     this.stmtCacheSize = pool.stmtCacheSize;
     this.user = pool.user;
     this.threadPoolSize = process.env.UV_THREADPOOL_SIZE;
+    this.thin = settings.thin;
   }
 
   //---------------------------------------------------------------------------
   // logStatistics()
-  //  To print the statistics metrics of the pool
+  //
+  // To print the statistics metrics of the pool
   //---------------------------------------------------------------------------
   logStatistics() {
-    console.log('\nPool statistics:');
+    console.log('\nDriver:');
+    console.log('...thin mode:', this.thin);
+    console.log('Pool statistics:');
     console.log('...gathered at:', new Date(this.gatheredDate).toISOString());
     console.log('...up time (milliseconds):', this.upTime);
     console.log('...up time from last reset (milliseconds)',

package/lib/queryStream.js

@@ -2,16 +2,23 @@
 
 //-----------------------------------------------------------------------------
 //
-// You may not use the identified files except in compliance with the Apache
-// License, Version 2.0 (the "License.")
+// 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
-// http://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.
+//    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.
 //
@@ -48,7 +55,7 @@ class QueryStream extends Readable {
           this.once('_doneFetching', resolve));
       }
       try {
-        await rs._close();
+        await rs._impl.close();
       } catch (closeErr) {
         cb(closeErr);
         return;

package/lib/resultset.js

@@ -1,17 +1,24 @@
-// Copyright (c) 2016, 2022, Oracle and/or its affiliates.
+// Copyright (c) 2016, 2023, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
-// You may not use the identified files except in compliance with the Apache
-// License, Version 2.0 (the "License.")
+// 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
-// http://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.
+//    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.
 //
@@ -20,220 +27,317 @@
 'use strict';
 
 const QueryStream = require('./queryStream.js');
+const BaseDbObject = require('./dbObject.js');
 const nodbUtil = require('./util.js');
+const constants = require('./constants.js');
+const Lob = require('./lob.js');
+const errors = require('./errors.js');
 
-//-----------------------------------------------------------------------------
-// close()
-//   Close the result set and make it unusable for further operations.
-//-----------------------------------------------------------------------------
-async function close() {
-  nodbUtil.checkArgCount(arguments, 0, 0);
+class ResultSet {
 
-  if (this._convertedToStream) {
-    throw new Error(nodbUtil.getErrorMessage('NJS-042'));
+  constructor() {
+    this._rowCache = [];
+    this._processingStarted = false;
+    this._convertedToStream = false;
+    this._allowGetRowCall = false;
+    this._isActive = false;
   }
 
-  this._processingStarted = true;
-  await this._close();
-}
+  //---------------------------------------------------------------------------
+  // _getAllRows()
+  //
+  // Return all of the rows in the result set.
+  //---------------------------------------------------------------------------
+  async _getAllRows() {
+
+    try {
+
+      // retain initial values of the maximum number of rows to fetch and the
+      // number of rows to fetch from the database at a single time
+      let maxRows = this._impl.maxRows;
+      let fetchArraySize = this._impl.fetchArraySize;
+
+      // fetch all rows
+      let rowsFetched = [];
+      while (true) {    // eslint-disable-line
+        if (maxRows > 0 && fetchArraySize >= maxRows) {
+          fetchArraySize = maxRows;
+        }
+        const rows = await this._getRows(fetchArraySize);
+        if (rows) {
+          await this._processRows(rows, true);
+          rowsFetched = rowsFetched.concat(rows);
+        }
+        if (rows.length == maxRows || rows.length < fetchArraySize) {
+          break;
+        }
+        if (maxRows > 0) {
+          maxRows -= rows.length;
+        }
+      }
 
+      return rowsFetched;
 
-//-----------------------------------------------------------------------------
-// getRow()
-//   Returns a single row to the caller from the result set, if one is
-// available. Rows are buffered in a JavaScript array in order to avoid trips
-// through the thread pool that would be required if implemented in C.
-//-----------------------------------------------------------------------------
-async function getRow() {
-  nodbUtil.checkArgCount(arguments, 0, 0);
+    } finally {
+      await this._impl.close();
+      delete this._impl;
+    }
 
-  if (this._convertedToStream && !this._allowGetRowCall) {
-    throw new Error(nodbUtil.getErrorMessage('NJS-042'));
   }
 
-  this._allowGetRowCall = false;
-  this._processingStarted = true;
-
-  if (this._rowCache.length == 0) {
-    this._rowCache = await this._getRows(this._fetchArraySize, false, false);
+  //---------------------------------------------------------------------------
+  // _getRows()
+  //
+  // Return up to the specified number of rows from the result set. If nested
+  // cursors are possible, setup the execute options so that they can be
+  // examined within the implementation's setup routine.
+  //---------------------------------------------------------------------------
+  async _getRows(numRows) {
+    let options = {};
+    if (this._impl.nestedCursorIndices.length > 0) {
+      options = {
+        connection: this._connection,
+        outFormat: this._impl.outFormat,
+        fetchArraySize: this._impl.fetchArraySize,
+        dbObjectAsPojo: this._impl.dbObjectAsPojo,
+        maxRows: this._impl.maxRows,
+        fetchTypeMap: this._impl.fetchTypeMap
+      };
+    }
+    return await this._impl.getRows(numRows, options);
   }
-  return this._rowCache.shift();
-}
-
-
-//-----------------------------------------------------------------------------
-// getRows()
-//   Check to see if any rows are in the JS buffer (which could result from
-// interspersed calls to getRow() and getRows()). If no rows are in the buffer
-// buffer, the call is just proxied to the C layer. Otherwise, rows are pulled
-// from the buffer and potentially concatenated with rows from a call to
-// getRows().
-//-----------------------------------------------------------------------------
-async function getRows(numRows) {
-  let rowsNeeded;
-
-  nodbUtil.checkArgCount(arguments, 0, 1);
 
-  if (arguments.length == 0) {
-    numRows = 0;
-  } else {
-    nodbUtil.assert(Number.isInteger(numRows), 'NJS-005', 1);
-    nodbUtil.assert(numRows >= 0, 'NJS-005', 1);
-  }
+  //---------------------------------------------------------------------------
+  // _processRows()
+  //
+  // Process rows returned by the implementation. This will transform result
+  // set and LOB implementations into user facing objects. It will also perform
+  // any fetched that are needed (if a result set is undesirable)
+  //---------------------------------------------------------------------------
+  async _processRows(rows, expandNestedCursors) {
+
+    // transform any nested cursors into user facing objects
+    for (const i of this._impl.nestedCursorIndices) {
+      for (let j = 0; j < rows.length; j++) {
+        const val = rows[j][i];
+        if (val) {
+          const resultSet = new ResultSet();
+          resultSet._setup(this._connection, val);
+          this._impl.metaData[i].metaData = val.metaData;
+          if (expandNestedCursors) {
+            rows[j][i] = await resultSet._getAllRows();
+          } else {
+            rows[j][i] = resultSet;
+          }
+        }
+      }
+    }
 
-  if (this._convertedToStream) {
-    throw new Error(nodbUtil.getErrorMessage('NJS-042'));
-  }
+    // transform any LOBs into user facing objects
+    for (const i of this._impl.lobIndices) {
+      for (let j = 0; j < rows.length; j++) {
+        const val = rows[j][i];
+        if (val) {
+          const lob = rows[j][i] = new Lob();
+          lob._setup(val, true);
+        }
+      }
+    }
 
-  this._processingStarted = true;
+    // transform any database objects into user facing objects
+    for (const i of this._impl.dbObjectIndices) {
+      const dbObjectClass = this._impl.metaData[i].dbTypeClass;
+      for (let j = 0; j < rows.length; j++) {
+        const val = rows[j][i];
+        if (val) {
+          const obj = rows[j][i] = Object.create(dbObjectClass.prototype);
+          obj._impl = val;
+          if (this._impl.dbObjectAsPojo) {
+            rows[j][i] = obj._toPojo();
+          } else if (obj.isCollection) {
+            rows[j][i] = new Proxy(obj, BaseDbObject._collectionProxyHandler);
+          }
+        }
+      }
+    }
 
-  if (numRows == 0) {
-    let requestedRows = this._rowCache;
+    // run any conversion functions, if applicable
+    // NOTE: we mark the connection as no longer in progress before making
+    // calls to the converter function; this is needed to allow calls against
+    // the database (like getting LOB data) to succeed, as this code is running
+    // in the middle of a call to connection.execute() or resultSet.getRows()
+    for (const i of this._impl.converterIndices) {
+      const fn = this._impl.metaData[i].converter;
+      this._connection._impl._inProgress = false;
+      try {
+        for (let j = 0; j < rows.length; j++) {
+          let result = fn(rows[j][i]);
+          if (result instanceof Promise) {
+            result = await result;
+          }
+          rows[j][i] = result;
+        }
+      } finally {
+        this._connection._impl._inProgress = true;
+      }
+    }
 
-    const fetchArraySize = this._fetchArraySize;
-    while (true) {  // eslint-disable-line
-      let rows = await this._getRows(fetchArraySize, false, false);
-      if (rows)
-        requestedRows = requestedRows.concat(rows);
-      if (rows.length < fetchArraySize)
-        break;
+    // create objects, if desired
+    if (this._impl.outFormat === constants.OUT_FORMAT_OBJECT) {
+      for (let i = 0; i < rows.length; i++) {
+        const origRow = rows[i];
+        const newRow = rows[i] = {};
+        const metaData = this._impl.metaData;
+        for (let j = 0; j < metaData.length; j++) {
+          newRow[metaData[j].name] = origRow[j];
+        }
+      }
     }
-    return requestedRows;
-  }
 
-  if (this._rowCache.length === 0) {
-    return await this._getRows(numRows, false, false);
   }
 
-  rowsNeeded = numRows - this._rowCache.length;
-  if (rowsNeeded <= 0) {
-    return this._rowCache.splice(0, numRows);
-  } else {
-    const rows = await this._getRows(rowsNeeded, false, false);
-    const requestedRows = this._rowCache.concat(rows);
-    this._rowCache = [];
-    return requestedRows;
+  //---------------------------------------------------------------------------
+  // _setup()
+  //
+  // Setup a result set.
+  // ---------------------------------------------------------------------------
+  _setup(connection, resultSetImpl) {
+    this._connection = connection;
+    this._impl = resultSetImpl;
   }
-}
-
 
-class ResultSet {
+  //---------------------------------------------------------------------------
+  // close()
+  //
+  // Close the result set and make it unusable for further operations.
+  //---------------------------------------------------------------------------
+  async close() {
+    errors.assertArgCount(arguments, 0, 0);
+    errors.assert(this._impl && this._connection._impl, errors.ERR_INVALID_RS);
 
-  constructor() {
-    this._rowCache = [];
-    this._processingStarted = false;
-    this._convertedToStream = false;
-    this._allowGetRowCall = false;
-    this._isActive = false;
-  }
+    if (this._convertedToStream) {
+      errors.throwErr(errors.ERR_CANNOT_INVOKE_RS_METHODS);
+    }
 
-  _extend(oracledb) {
-    this._oracledb = oracledb;
-    this.close = nodbUtil.callbackify(nodbUtil.preventConcurrent(nodbUtil.serialize(close), 'NJS-017'));
-    this.getRow = nodbUtil.callbackify(nodbUtil.preventConcurrent(nodbUtil.serialize(getRow), 'NJS-017'));
-    this.getRows = nodbUtil.callbackify(nodbUtil.preventConcurrent(nodbUtil.serialize(getRows), 'NJS-017'));
+    this._processingStarted = true;
+    const resultSetImpl = this._impl;
+    delete this._impl;
+    await resultSetImpl.close();
   }
 
-  _getConnection() {
-    let connection = this._parentObj;
-    while (!(connection instanceof this._oracledb.Connection))
-      connection = connection._parentObj;
-    return connection;
-  }
+  //---------------------------------------------------------------------------
+  // getRow()
+  //
+  // Returns a single row to the caller from the result set, if one is
+  // available. Rows are buffered in a JavaScript array in order to avoid trips
+  // through the thread pool that would be required if implemented in C.
+  //---------------------------------------------------------------------------
+  async getRow() {
+    errors.assertArgCount(arguments, 0, 0);
+    errors.assert(this._impl && this._connection._impl, errors.ERR_INVALID_RS);
+
+    if (this._convertedToStream && !this._allowGetRowCall) {
+      errors.throwErr(errors.ERR_CANNOT_INVOKE_RS_METHODS);
+    }
 
-  async _getAllRows(executeOpts, metaDataObj, isNested) {
+    this._allowGetRowCall = false;
+    this._processingStarted = true;
 
-    // assign result set metadata to the object; this is either a top-level
-    // result object that is returned to the user or a metadata object for a
-    // nested cursor or empty (for implicit results which don't provide
-    // metadata to the caller)
-    if (metaDataObj && !metaDataObj.metaData) {
-      metaDataObj.metaData = this.metaData;
+    if (this._rowCache.length == 0) {
+      const rows = await this._getRows(this._impl.fetchArraySize);
+      await this._processRows(rows, false);
+      this._rowCache = rows;
     }
+    return this._rowCache.shift();
+  }
 
-    // determine value of maxRows to use
-    let maxRows = this._oracledb.maxRows;
-    if (executeOpts && executeOpts.maxRows !== undefined) {
-      maxRows = executeOpts.maxRows;
+  //---------------------------------------------------------------------------
+  // getRows()
+  //
+  // Check to see if any rows are in the JS buffer (which could result from
+  // interspersed calls to getRow() and getRows()). If no rows are in the
+  // buffer, the call is just proxied to the implementation layer. Otherwise,
+  // rows are pulled from the buffer and potentially concatenated with rows
+  // from calls to the implementation's getRows().
+  //---------------------------------------------------------------------------
+  async getRows(numRows) {
+    let rowsNeeded;
+
+    errors.assertArgCount(arguments, 0, 1);
+    errors.assert(this._impl && this._connection._impl, errors.ERR_INVALID_RS);
+
+    if (arguments.length == 0) {
+      numRows = 0;
+    } else {
+      errors.assertParamValue(Number.isInteger(numRows) && numRows >= 0, 1);
     }
 
-    // determine value of outFormat to use
-    let outFormat = this._oracledb.outFormat;
-    if (executeOpts && executeOpts.outFormat !== undefined) {
-      outFormat = executeOpts.outFormat;
+    if (this._convertedToStream) {
+      errors.throwErr(errors.ERR_CANNOT_INVOKE_RS_METHODS);
     }
 
-    // determine the nested cursor indices to use, allowing for both
-    // OUT_FORMAT_ARRAY and OUT_FORMAT_OBJECT formats
-    const nestedCursorMetaDataObjs = [];
-    const nestedCursorIndices = this._nestedCursorIndices;
-    for (let i = 0; i < nestedCursorIndices.length; i++) {
-      nestedCursorMetaDataObjs[i] =
-        metaDataObj.metaData[nestedCursorIndices[i]];
-      if (outFormat == this._oracledb.OUT_FORMAT_OBJECT) {
-        nestedCursorIndices[i] = nestedCursorMetaDataObjs[i].name;
+    this._processingStarted = true;
+
+    let requestedRows;
+    if (numRows == 0) {
+      requestedRows = this._rowCache;
+      const fetchArraySize = this._impl.fetchArraySize;
+      while (true) {  // eslint-disable-line
+        const rows = await this._getRows(fetchArraySize);
+        if (rows) {
+          await this._processRows(rows, false);
+          requestedRows = requestedRows.concat(rows);
+        }
+        if (rows.length < fetchArraySize)
+          break;
       }
+      return requestedRows;
     }
 
-    // process all rows; transform nested cursors into arrays of rows by
-    // fetching them
-    let rowsFetched = [];
-    let fetchArraySize = this._fetchArraySize;
-    let closeOnFetch = false;
-    const closeOnAllRowsFetched = !isNested && nestedCursorIndices.length === 0;
-    while (true) {    // eslint-disable-line
-      if (maxRows > 0 && fetchArraySize >= maxRows) {
-        fetchArraySize = maxRows;
-        closeOnFetch = closeOnAllRowsFetched;
-      }
-      const rows = await this._getRows(fetchArraySize, closeOnFetch,
-        closeOnAllRowsFetched);
-      if (nestedCursorIndices) {
-        for (let i = 0; i < rows.length; i++) {
-          const row = rows[i];
-          for (let j = 0; j < nestedCursorIndices.length; j++) {
-            const val = row[nestedCursorIndices[j]];
-            if (val) {
-              row[nestedCursorIndices[j]] =
-                  await val._getAllRows(executeOpts,
-                    nestedCursorMetaDataObjs[j], true);
-            }
-          }
-        }
-      }
-      if (rows) {
-        rowsFetched = rowsFetched.concat(rows);
-      }
-      if (rows.length == maxRows || rows.length < fetchArraySize) {
-        break;
-      }
-      if (maxRows > 0) {
-        maxRows -= rows.length;
+    if (this._rowCache.length === 0) {
+      requestedRows = await this._getRows(numRows);
+      await this._processRows(requestedRows, false);
+    } else {
+      rowsNeeded = numRows - this._rowCache.length;
+      if (rowsNeeded <= 0) {
+        requestedRows = this._rowCache.splice(0, numRows);
+      } else {
+        const rows = await this._getRows(rowsNeeded);
+        await this._processRows(rows, false);
+        requestedRows = this._rowCache.concat(rows);
+        this._rowCache = [];
       }
     }
 
-    // if the cursor was not automatically closed (in order to ensure that
-    // nested cursors could be fetched), close it now that all rows have been
-    // fetched
-    if (!closeOnAllRowsFetched) {
-      await this._close();
-    }
-    return rowsFetched;
+    return requestedRows;
   }
 
-  _getDbObjectClassJS(schema, name) {
-    return this._connection._getDbObjectClassJS(schema, name);
+  //---------------------------------------------------------------------------
+  // metaData()
+  //
+  // Property returning the metadata associated with the result set.
+  //---------------------------------------------------------------------------
+  get metaData() {
+    if (this._impl) {
+      return this._impl.metaData;
+    }
+    return undefined;
   }
 
+  //---------------------------------------------------------------------------
+  // toQueryStream()
+  //
+  // Converts a result set to a QueryStream object.
+  //---------------------------------------------------------------------------
   toQueryStream() {
-    nodbUtil.checkArgCount(arguments, 0, 0);
+    errors.assertArgCount(arguments, 0, 0);
 
     if (this._processingStarted) {
-      throw new Error(nodbUtil.getErrorMessage('NJS-041'));
+      errors.throwErr(errors.ERR_CANNOT_CONVERT_RS_TO_STREAM);
     }
 
     if (this._convertedToStream) {
-      throw new Error(nodbUtil.getErrorMessage('NJS-043'));
+      errors.throwErr(errors.ERR_RS_ALREADY_CONVERTED);
     }
 
     this._convertedToStream = true;
@@ -241,7 +345,24 @@ class ResultSet {
     return new QueryStream(this);
   }
 
+  [Symbol.asyncIterator]() {
+    const resultSet = this;
+    return {
+      async next() {
+        const row = await resultSet.getRow();
+        return {value: row, done: row === undefined};
+      },
+      return() {
+        return {done: true};
+      }
+    };
+  }
+
 }
 
+nodbUtil.wrapFns(ResultSet.prototype, errors.ERR_BUSY_RS,
+  "close",
+  "getRow",
+  "getRows");
 
 module.exports = ResultSet;