oracledb 7.0.0 → 26.0.0

package/lib/thin/protocol/messages/notification.js

@@ -0,0 +1,281 @@
+// Copyright (c) 2026, Oracle and/or its affiliates.
+
+//-----------------------------------------------------------------------------
+//
+// 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
+//
+//    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.
+//
+//-----------------------------------------------------------------------------
+
+'use strict';
+
+const constants = require("../constants.js");
+const errors = require("../../../errors.js");
+const pubConstants = require("../../../constants.js");
+const AqBaseMessage = require("./aqBase.js");
+const { BaseBuffer } = require("../../../impl/datahandlers/buffer.js");
+const { ThinMsgPropsImpl } = require("../../aq.js");
+
+class NotifyMessage extends AqBaseMessage {
+
+  /**
+   * Creates a notify protocol message used on the dedicated listener channel.
+   */
+  constructor(connection, subscr) {
+    super(connection);
+    this.functionCode = constants.TNS_FUNC_NOTIFY;
+    this.subscr = subscr;
+    this.clientId = null;
+    this.namespace = subscr.namespace;
+    this._processingOac = false;
+  }
+
+  /**
+   * Decodes the notification message and its OAC records.
+   */
+  decode(buf) {
+    if (this._processingOac) {
+      this._processOacRecords(buf);
+    } else {
+      super.decode(buf);
+    }
+  }
+
+  /**
+   * Processes all available OAC notification records.
+   */
+  _processOacRecords(buf) {
+    while (!this.endOfResponse) {
+      this._processOac(buf);
+    }
+    // Normal OAC completion does not stop a live notification listener. The
+    // EMON channel is a persistent stream and continues waiting for more
+    // packets until unsubscribe, deregistration, STOP_NOTIF, or failure.
+    this._processingOac = false;
+  }
+
+  /**
+   * Processes a single TTC message for notifications.
+   */
+  processMessage(buf, messageType) {
+
+    // Notification supports OAC messages only.
+    if (messageType === constants.TNS_MSG_TYPE_OAC) {
+      this._processingOac = true;
+      this._processOacRecords(buf);
+    } else {
+      errors.throwErr(errors.ERR_UNEXPECTED_MESSAGE_TYPE, messageType, buf.pos,
+        buf.packetNum);
+    }
+  }
+
+  /**
+   * Processes one notification record returned by the server.
+   */
+  _processOac(buf) {
+    buf.savePoint();
+    const notification = {
+      regId: BigInt(this.subscr.regId || 0),
+      registered: true
+    };
+
+    // first part is the notification header
+    const messageType = buf.readUB4();
+    if (messageType === constants.TNS_SUBSCR_STOP_NOTIF) {
+      // STOP_NOTIF is terminal for this subscription. Report it as a
+      // deregistration event and retire the public subscription entry.
+      notification.type = pubConstants.SUBSCR_EVENT_TYPE_DEREG;
+      notification.registered = false;
+      this.subscr._retire();
+      this.endOfResponse = true;
+      this.subscr._invokeCallback(notification);
+      return;
+    }
+    buf.skipUB4();                             // error code
+    buf.skipUB4();                             // registration id
+    const queueName = buf.readStrAndLength();
+    if (queueName) {
+      notification.queueName = queueName;
+    }
+    const consumerName = buf.readStrAndLength();
+    if (consumerName) {
+      notification.consumerName = consumerName;
+    }
+    const msgId = buf.readBytesAndLength();
+    if (msgId) {
+      notification.msgId = Buffer.from(msgId);
+    }
+
+    // second part is the message properties
+    this._processAqMsgProps(buf, notification);
+    buf.readBytesAndLength();                  // JMS message properties
+
+    // third part is the payload (not for AQ without currently unsupported flag)
+    let payload = null;
+    if (this.namespace !== pubConstants.SUBSCR_NAMESPACE_AQ) {
+      buf.skipUB4();                           // payload type
+      buf.skipUB4();                           // payload flags
+      buf.skipUB4();                           // chunk number
+      payload = buf.readBytesAndLength();
+      buf.readBytesAndLength();                // DB object/JSON payload
+    }
+    this._processNotificationPayload(payload, notification);
+
+    // invoke the callback with the notification that was created
+    this.subscr._invokeCallback(notification);
+  }
+
+  /**
+   * Processes AQ message properties, including extension key/value pairs.
+   */
+  _processAqMsgProps(buf, notification) {
+    const numProps = buf.readUB4();
+    if (numProps > 0) {
+      const propsImpl = new ThinMsgPropsImpl();
+      buf.skipUB1();                           // invalid length
+      this._processMsgProps(buf, propsImpl);
+      if (propsImpl.originalMsgId) {
+        notification.originalMsgId = Buffer.from(propsImpl.originalMsgId);
+      }
+      if (propsImpl.senderAgentName) {
+        notification.senderAgentName = propsImpl.senderAgentName.toString();
+      }
+      if (propsImpl.senderAgentAddress) {
+        notification.senderAgentAddress =
+          propsImpl.senderAgentAddress.toString();
+      }
+      notification.senderAgentProtocol = propsImpl.senderAgentProtocol;
+    }
+  }
+
+  /**
+   * Processes the notification payload and populates callback data.
+   */
+  _processNotificationPayload(payload, notification) {
+
+    // payload is ignored for AQ notification
+    if (this.namespace === pubConstants.SUBSCR_NAMESPACE_AQ) {
+      notification.type = pubConstants.SUBSCR_EVENT_TYPE_AQ;
+      return;
+    }
+
+    // Empty payload for DB/query change means the registration is discarded.
+    // Retire the public subscription immediately so Thin does not retain a
+    // callback for a registration that can no longer deliver notifications.
+    // readBytesAndLength() returns undefined for a zero-length payload.
+    if (payload == null) {
+      notification.type = pubConstants.SUBSCR_EVENT_TYPE_DEREG;
+      notification.registered = false;
+      this.subscr._retire();
+      this.endOfResponse = true;
+      return;
+    }
+
+    // process payload for DB/query change notification
+    if (this.subscr.qos & pubConstants.SUBSCR_QOS_DEREG_NFY) {
+      notification.registered = false;
+      this.subscr._retire();
+      this.endOfResponse = true;
+    }
+
+    const payloadBuf = new BaseBuffer(payload);
+    payloadBuf.readUInt16BE();                 // version
+    payloadBuf.readUInt32BE();                 // registration id
+    notification.type = payloadBuf.readUInt32BE();
+    const dbNameLen = payloadBuf.readUInt16BE();
+    if (dbNameLen > 0) {
+      notification.dbName = payloadBuf.readBytes(dbNameLen).toString();
+    }
+    notification.txId = Buffer.from(payloadBuf.readBytes(8));
+    payloadBuf.skipBytes(6);                   // SCN
+    if (notification.type === pubConstants.SUBSCR_EVENT_TYPE_OBJ_CHANGE) {
+      notification.tables = [];
+      this._processTables(payloadBuf, notification.tables);
+    } else if (notification.type ===
+        pubConstants.SUBSCR_EVENT_TYPE_QUERY_CHANGE) {
+      notification.queries = [];
+      this._processQueries(payloadBuf, notification.queries);
+    }
+  }
+
+  /**
+   * Processes query-level notification entries.
+   */
+  _processQueries(buf, queries) {
+    const numQueries = buf.readUInt16BE();
+    for (let i = 0; i < numQueries; i++) {
+      const id = buf.readBytes(8).readBigUInt64BE(0);   // query id
+      const operation = buf.readUInt32BE();
+      const query = {
+        id,
+        operation,
+        tables: []
+      };
+      this._processTables(buf, query.tables);
+      queries.push(query);
+    }
+  }
+
+  /**
+   * Processes row-level notification entries.
+   */
+  _processRows(buf, rows) {
+    const numRows = buf.readUInt16BE();
+    for (let i = 0; i < numRows; i++) {
+      const operation = buf.readUInt32BE();
+      const rowIdLen = buf.readUInt16BE();
+      const rowId = buf.readBytes(rowIdLen).toString();
+      rows.push({ operation, rowid: rowId });
+    }
+  }
+
+  /**
+   * Processes table-level notification entries.
+   */
+  _processTables(buf, tables) {
+    const numTables = buf.readUInt16BE();
+    for (let i = 0; i < numTables; i++) {
+      const operation = buf.readUInt32BE();
+      const tableNameLen = buf.readUInt16BE();
+      const name = buf.readBytes(tableNameLen).toString();
+      buf.readUInt32BE();                      // object num
+      const table = { operation, name, rows: [] };
+      if ((operation & pubConstants.CQN_OPCODE_ALL_ROWS) === 0) {
+        this._processRows(buf, table.rows);
+      }
+      tables.push(table);
+    }
+  }
+
+  /**
+   * Writes the initial notify request payload to the wire buffer.
+   */
+  encode(buf) {
+    buf._dataFlags = constants.TNS_DATA_FLAGS_END_OF_REQUEST;
+    this.writeFunctionHeader(buf);
+    buf.writeUB4(this.clientId.length);
+    buf.writeBytesWithLength(this.clientId);
+    buf.writeUInt8(constants.TNS_INIT_KPNDRREQ);
+    buf.writeUB4(0);
+  }
+
+}
+
+module.exports = NotifyMessage;

package/lib/thin/protocol/messages/subscribe.js

@@ -0,0 +1,181 @@
+// Copyright (c) 2026, Oracle and/or its affiliates.
+
+//-----------------------------------------------------------------------------
+//
+// 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
+//
+//    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.
+//
+//-----------------------------------------------------------------------------
+
+'use strict';
+
+const constants = require("../constants.js");
+const Message = require("./base.js");
+const pubConstants = require("../../../constants.js");
+
+class SubscrMessage extends Message {
+
+  /**
+   * Creates a subscribe protocol message.
+   */
+  constructor(connection, subscr) {
+    super(connection);
+    this.functionCode = constants.TNS_FUNC_SUBSCRIBE;
+    this.subscr = subscr;
+    this.registrationId = 0n;
+    this.clientId = null;
+    this.opCode = constants.TNS_SUBSCR_OP_REGISTER;
+  }
+
+  /**
+   * Processes the return parameters for the subscribe request.
+   */
+  processReturnParameter(buf) {
+    let numValues = buf.readUB4();             // out parameters (kpnrl)
+    for (let i = 0; i < numValues; i++) {
+      buf.skipUB4();
+    }
+    for (let i = 0; i < numValues; i++) {
+      buf.skipUB4();                           // registration id (short)
+    }
+    numValues = buf.readUB4();                 // out parameters (kpngrl)
+    for (let i = 0; i < numValues; i++) {
+      this.registrationId = buf.readUB8BigInt();
+      if (buf.caps.ttcFieldVersion >= constants.TNS_CCAP_FIELD_VERSION_12_1) {
+        buf.readBytesAndLength();              // subscriber name (ignored)
+      }
+    }
+    if (buf.caps.ttcFieldVersion >= constants.TNS_CCAP_FIELD_VERSION_12_1) {
+      numValues = buf.readUB4();               // num database instances
+      for (let i = 0; i < numValues; i++) {
+        buf.readBytesAndLength();
+      }
+      numValues = buf.readUB4();               // num listener addresses
+      for (let i = 0; i < numValues; i++) {
+        buf.readBytesAndLength();
+      }
+      const clientId = buf.readBytesAndLength();
+      this.clientId = clientId ? Buffer.from(clientId) : null;
+    }
+  }
+
+  /**
+   * Writes the subscribe register/unregister payload to the wire buffer.
+   */
+  encode(buf) {
+    let groupingType;
+    let usernameBytes;
+    let qos = constants.TNS_SUBSCR_QOS_SECURE;
+    let flags = this.subscr.operations;
+
+    // determine the QOS flags to send
+    if (this.subscr.qos & pubConstants.SUBSCR_QOS_RELIABLE) {
+      qos |= constants.TNS_SUBSCR_QOS_RELIABLE;
+    }
+    if (this.subscr.qos & pubConstants.SUBSCR_QOS_DEREG_NFY) {
+      qos |= constants.TNS_SUBSCR_QOS_PURGE_ON_NTFN;
+    }
+
+    // determine the operations flags to send
+    if (this.subscr.qos & pubConstants.SUBSCR_QOS_QUERY) {
+      flags |= constants.TNS_SUBSCR_FLAGS_QUERY;
+    }
+    if (this.subscr.qos & pubConstants.SUBSCR_QOS_ROWIDS) {
+      flags |= constants.TNS_SUBSCR_FLAGS_INCLUDE_ROWIDS;
+    }
+
+    // determine the grouping type to send; default cannot be sent unless
+    // grouping class is also set
+    if (this.subscr.groupingClass === 0) {
+      groupingType = 0;
+    } else {
+      groupingType = this.subscr.groupingType;
+    }
+
+    // write the message
+    this.writeFunctionHeader(buf);
+    buf.writeUInt8(this.opCode);
+    buf.writeUB4(constants.TNS_SUBSCR_MODE_CLIENT_INITIATED);
+    if (this.connection._user) {
+      usernameBytes = Buffer.from(this.connection._user);
+      buf.writeUInt8(1);                       // pointer (username)
+      buf.writeUB4(usernameBytes.length);
+    } else {
+      buf.writeUInt8(0);                       // pointer (username)
+      buf.writeUB4(0);                         // username length
+    }
+    if (this.clientId) {
+      buf.writeUInt8(1);                       // pointer (location)
+      buf.writeUB4(this.clientId.length);
+    } else {
+      buf.writeUInt8(0);                       // pointer (location)
+      buf.writeUB4(0);                         // location array length
+    }
+    buf.writeUInt8(1);                         // pointer (registration)
+    buf.writeUB4(1);                           // num registrations
+    buf.writeUB2(1);                           // raw presentation
+    buf.writeUB2(6);                           // version for client notif
+    buf.writeUInt8(0);                         // pointer (namespace out attrs)
+    buf.writeUInt8(1);                         // pointer (num elems array)
+    buf.writeUInt8(0);                         // pointer (generic out attrs)
+    buf.writeUInt8(1);                         // pointer (num elems array)
+    if (buf.caps.ttcFieldVersion >= constants.TNS_CCAP_FIELD_VERSION_12_1) {
+      buf.writeUInt8(1);                       // pointer (kpninst)
+      buf.writeUInt8(1);                       // pointer (kpninstl)
+      buf.writeUInt8(1);                       // pointer (kpngcret)
+      buf.writeUInt8(1);                       // pointer (kpngcretl)
+      buf.writeUInt8(1);                       // pointer (client id)
+      buf.writeUB4(constants.TNS_SUBSCR_CLIENT_ID_LEN);
+      buf.writeUInt8(1);                       // pointer (client id length)
+    }
+    if (usernameBytes) {
+      buf.writeBytesWithLength(usernameBytes);
+    }
+    if (this.clientId) {
+      buf.writeBytesWithLength(this.clientId);
+    }
+    buf.writeUB4(this.subscr.namespace);
+    if (this.subscr.name) {
+      const nameBytes = Buffer.from(this.subscr.name);
+      buf.writeUB4(nameBytes.length);
+      buf.writeBytesWithLength(nameBytes);
+    } else {
+      buf.writeUB4(0);
+    }
+    buf.writeUB4(0);                           // context length
+    buf.writeUB4(0);                           // payload type
+    buf.writeUB4(qos);
+    buf.writeUB4(0);                           // payload callback len (JMS)
+    buf.writeUB4(this.subscr.timeout);
+    buf.writeUB4(0);                           // kpdnsd
+    buf.writeUB4(flags);
+    buf.writeUB4(0);                           // change lag
+    buf.writeUB4(0);                           // change registration id
+    buf.writeUInt8(this.subscr.groupingClass);
+    buf.writeUB4(this.subscr.groupingValue);
+    buf.writeUInt8(groupingType);
+    buf.writeUB4(0);                           // grouping class start time
+    buf.writeSB4(0);                           // grouping repeat count
+    buf.writeUB8BigInt(this.registrationId);
+  }
+
+}
+
+module.exports = SubscrMessage;

package/lib/thin/protocol/messages/withData.js

@@ -318,7 +318,8 @@ class MessageWithData extends Message {
     ) {
       const useLocalTime = (oraTypeNum === constants.TNS_DATA_TYPE_DATE ||
         oraTypeNum === constants.TNS_DATA_TYPE_TIMESTAMP);
-      colValue = buf.readOracleDate(useLocalTime);
+      const useDbTz = oraTypeNum === constants.TNS_DATA_TYPE_TIMESTAMP_LTZ;
+      colValue = buf.readOracleDate(useLocalTime, useDbTz);
     } else if (oraTypeNum === constants.TNS_DATA_TYPE_ROWID) {
       if (!this.inFetch) {
         colValue = buf.readStr(constants.CSFRM_IMPLICIT);
@@ -425,8 +426,11 @@ class MessageWithData extends Message {
     return colValue;
   }
 
+  /**
+   * Processes execute return parameters, including keyword/value pairs and
+   * registration data, and optional array DML row counts.
+   */
   processReturnParameter(buf) {
-    let keywordNum = 0;
     let keyTextValue;
     let numParams = buf.readUB2();              // al8o4l (ignored)
 
@@ -447,16 +451,18 @@ class MessageWithData extends Message {
       if (numBytes > 0) {
         buf.skipBytesChunked();
       }
-      keywordNum = buf.readUB2();               // keyword num
+      const keywordNum = buf.readUB2();         // keyword num
       if (keywordNum === constants.TNS_KEYWORD_NUM_CURRENT_SCHEMA) {
         this.connection.currentSchema = keyTextValue;
       } else if (keywordNum === constants.TNS_KEYWORD_NUM_EDITION) {
         this.connection._edition = keyTextValue;
+      } else if (keywordNum === constants.TNS_KEYWORD_NUM_TXN_PRIORITY) {
+        this.connection._txnPriority = keyTextValue;
       }
     }
     numBytes = buf.readUB2();                   // registration
     if (numBytes > 0) {
-      buf.skip(numBytes);
+      buf.skipBytes(numBytes);
     }
     if (this.arrayDmlRowCounts) {
       const numRows = buf.readUB4();
@@ -500,13 +506,20 @@ class MessageWithData extends Message {
       // LOBs always require define and they change the type that is actually
       // returned by the server
       for (const variable of resultSet.statement.queryVars) {
-        if (variable.type === types.DB_TYPE_CLOB ||
-            variable.type === types.DB_TYPE_NCLOB ||
-            variable.type === types.DB_TYPE_BLOB ||
-            variable.type === types.DB_TYPE_JSON ||
-            variable.type === types.DB_TYPE_VECTOR) {
+        // Use the original database type here. The variable type may already
+        // have been changed to the requested define type, such as LONG_RAW for
+        // a BLOB fetched as a Buffer, but the original BLOB still requires the
+        // special define handling below.
+        const dbType = variable.fetchInfo.dbType;
+        if (dbType === types.DB_TYPE_CLOB ||
+            dbType === types.DB_TYPE_NCLOB ||
+            dbType === types.DB_TYPE_BLOB ||
+            dbType === types.DB_TYPE_JSON ||
+            dbType === types.DB_TYPE_VECTOR) {
           if (variable.type !== variable.fetchInfo.fetchType) {
             variable.type = variable.fetchInfo.fetchType;
+          }
+          if (dbType !== variable.fetchInfo.fetchType) {
             variable.maxSize = constants.TNS_MAX_LONG_LENGTH;
           }
           if (!resultSet.statement.noPrefetch) {
@@ -755,7 +768,7 @@ class MessageWithData extends Message {
       buf.writeDbObject(value);
     } else {
       const message = `Binding data of type ${variable.type}`;
-      errors.throwErr(errors.ERR_NOT_IMPLEMENTED, message);
+      errors.throwNotImplemented(message);
     }
   }
 

package/lib/thin/protocol/packet.js

@@ -144,9 +144,8 @@ class ReadPacket extends BaseBuffer {
    */
 
   constructor(nsi, caps) {
-    super();
+    super(undefined, caps);
     this.nsi = nsi;
-    this.caps = caps;
     this.chunkedBytesBuf = new ChunkedBytesBuffer();
   }
 
@@ -530,12 +529,11 @@ class ReadPacket extends BaseBuffer {
 class WritePacket extends BaseBuffer {
 
   constructor(nsi, caps, protocol) {
-    super(nsi.sAtts.sdu);
+    super(nsi.sAtts.sdu, caps);
     this.size = this.maxSize;
     this.isLargeSDU = nsi.sAtts.version >= constants.TNS_VERSION_MIN_LARGE_SDU;
     this.protocol = protocol;
     this.packetType = constants.TNS_PACKET_TYPE_DATA;
-    this.caps = caps;
     this.nsi = nsi;
     this._dataFlags = 0;
     this.tokenNum = 0;

package/lib/thin/protocol/protocol.js

@@ -253,10 +253,13 @@ class Protocol {
       if (traceEnabled) {
         traceContext.operation = `oracledb.${message.constructor.name}`;
         traceInstance.onBeginRoundTrip(traceContext);
-        if (traceContext.userContext?.traceParent) {
-          // The traceParent is set from instrumentation module.
-          message.connection.appContext('CLIENTCONTEXT',
-            [{ ora$opentelem$tracectx: traceContext.userContext.traceParent }]);
+
+        const { traceParent, traceState } = traceContext.userContext ?? {};
+        if (traceParent) {
+          const state = traceState ? `tracestate: ${traceState}\r\n` : '';
+          message.connection.appContext('CLIENTCONTEXT', [{
+            ora$opentelem$tracectx: `traceparent: ${traceParent}\r\n${state}`
+          }]);
         }
       }
       await this._encodeMessage(message);

package/lib/thin/resultSet.js

@@ -39,7 +39,12 @@ class ThinResultSetImpl extends ResultSetImpl {
   // OAL8 RPC if needed; otherwise, the simpler OFETCH RPC is used.
   //---------------------------------------------------------------------------
   async _fetchMoreRows(options) {
-    const cls = (this.statement.requiresFullExecute) ? ExecuteMessage : FetchMessage;
+    // prepare the prefetch value for execute
+    options.prefetchRows = this.options.prefetchRows;
+
+    // execute/fetch
+    const cls = (this.statement.requiresFullExecute) ?
+      ExecuteMessage : FetchMessage;
     const message = new cls(this.connection, this.statement, options, this);
     await this.connection._protocol._processMessage(message);
     this.statement.requiresFullExecute = false;
@@ -58,18 +63,18 @@ class ThinResultSetImpl extends ResultSetImpl {
   }
 
   //---------------------------------------------------------------------------
-  // Returns the statement to cache so that it can be used later
-  //---------------------------------------------------------------------------
-  close() {
-    this.connection._returnStatement(this.statement);
-  }
-
-  //---------------------------------------------------------------------------
-  // Returns rows fetched to the common layer in array format
+  // Returns rows fetched to the common layer in array format. The caller
+  // guarantees that numRowsFetched does not exceed the rows remaining in the
+  // statement buffer. This method consumes those rows by advancing
+  // bufferRowIndex.
   //---------------------------------------------------------------------------
   _processRows(numRowsFetched) {
     const rows = [];
+
+    // Index of the first unconsumed row in the statement buffer
     const bufferRowIndex = this.statement.bufferRowIndex;
+
+    // Get the rows
     for (let row = bufferRowIndex; row < bufferRowIndex + numRowsFetched; row++) {
       const rowObj = [];
       for (let col = 0; col < this.statement.numQueryVars; col++) {
@@ -77,7 +82,12 @@ class ThinResultSetImpl extends ResultSetImpl {
       }
       rows.push(rowObj);
     }
+
+    // Consume the rows returned above; numRowsFetched is never greater than
+    // (bufferRowCount - bufferRowIndex) when this method is called
     this.statement.bufferRowIndex += numRowsFetched;
+
+    // An empty buffer is reset so that the next fetch starts at index zero
     if (this.statement.bufferRowIndex === this.statement.bufferRowCount) {
       this.statement.bufferRowCount = 0;
       this.statement.bufferRowIndex = 0;
@@ -85,6 +95,13 @@ class ThinResultSetImpl extends ResultSetImpl {
     return rows;
   }
 
+  //---------------------------------------------------------------------------
+  // Returns the statement to cache so that it can be used later
+  //---------------------------------------------------------------------------
+  close() {
+    this.connection._returnStatement(this.statement);
+  }
+
   //---------------------------------------------------------------------------
   // getRows()
   //
@@ -92,20 +109,23 @@ class ThinResultSetImpl extends ResultSetImpl {
   // the common layer for processing.
   //---------------------------------------------------------------------------
   async getRows(numRows, options) {
-    options.fetchArraySize = numRows || this.options.fetchArraySize;
-    options.prefetchRows = this.options.prefetchRows;
-    if (this.statement.bufferRowCount - this.statement.bufferRowIndex >= options.fetchArraySize)
-      return this._processRows(options.fetchArraySize);
+    const numRowsRequested = numRows || this.options.fetchArraySize;
+
+    // Number of rows currently available, starting at bufferRowIndex
+    const rowsInBuffer = this.statement.bufferRowCount -
+      this.statement.bufferRowIndex;
+    if (rowsInBuffer >= numRowsRequested)
+      return this._processRows(numRowsRequested);
 
     // We fetch for the required number of rows
-    options.fetchArraySize = options.fetchArraySize - (this.statement.bufferRowCount - this.statement.bufferRowIndex);
-    const prevBufferRowCount = this.statement.bufferRowCount;
-    if (this.statement.moreRowsToFetch && options.fetchArraySize > 0)
+    if (this.statement.moreRowsToFetch) {
+      options.fetchArraySize = numRowsRequested - rowsInBuffer;
       await this._fetchMoreRows(options);
-    options.fetchArraySize = numRows || this.options.fetchArraySize;
-    const numRowsFetched = this.statement.bufferRowCount - this.statement.bufferRowIndex;
-    if (prevBufferRowCount === this.statement.bufferRowCount)
-      this.statement.bufferRowCount = 0;
+    }
+
+    // All rows currently remaining in the buffer are returned in this path
+    const numRowsFetched = this.statement.bufferRowCount -
+      this.statement.bufferRowIndex;
 
     // process the rows fetched
     return this._processRows(numRowsFetched);