mysql2 3.20.0 → 3.20.1-canary.2bdc12a4

package/lib/commands/execute.js

@@ -43,11 +43,15 @@ class Execute extends Command {
     this._connection = connection;
     this.options = Object.assign({}, connection.config, this._executeOptions);
     this._setTimeout();
+    const clientFlags =
+      connection.config.clientFlags & (connection.serverCapabilityFlags || 0);
     const executePacket = new Packets.Execute(
       this.statement.id,
       this.parameters,
       connection.config.charsetNumber,
-      connection.config.timezone
+      connection.config.timezone,
+      this._executeOptions.attributes,
+      clientFlags
     );
     //For reasons why this try-catch is here, please see
     // https://github.com/sidorares/node-mysql2/pull/689

package/lib/commands/query.js

@@ -53,9 +53,13 @@ class Query extends Command {
     this.options = Object.assign({}, connection.config, this._queryOptions);
     this._setTimeout();
 
+    const clientFlags =
+      connection.config.clientFlags & (connection.serverCapabilityFlags || 0);
     const cmdPacket = new Packets.Query(
       this.sql,
-      connection.config.charsetNumber
+      connection.config.charsetNumber,
+      this._queryOptions.attributes,
+      clientFlags
     );
     connection.writePacket(cmdPacket.toPacket(1));
     return Query.prototype.resultsetHeader;

package/lib/connection_config.js

@@ -239,6 +239,7 @@ class ConnectionConfig {
       'TRANSACTIONS',
       'SESSION_TRACK',
       'CONNECT_ATTRS',
+      'CLIENT_QUERY_ATTRIBUTES',
     ];
     if (options && options.multipleStatements) {
       defaultFlags.push('MULTI_STATEMENTS');

package/lib/constants/client.js

@@ -31,6 +31,7 @@ exports.CONNECT_ATTRS = 0x00100000; /* permits connection attributes */
 exports.PLUGIN_AUTH_LENENC_CLIENT_DATA = 0x00200000; /* Understands length-encoded integer for auth response data in Protocol::HandshakeResponse41. */
 exports.CAN_HANDLE_EXPIRED_PASSWORDS = 0x00400000; /* Announces support for expired password extension. */
 exports.SESSION_TRACK = 0x00800000; /* Can set SERVER_SESSION_STATE_CHANGED in the Status Flags and send session-state change data after a OK packet. */
+exports.CLIENT_QUERY_ATTRIBUTES = 0x08000000; /* support query attributes in COM_QUERY and COM_STMT_EXECUTE */
 
 exports.SSL_VERIFY_SERVER_CERT = 0x40000000;
 exports.REMEMBER_OPTIONS = 0x80000000;

package/lib/constants/cursor.js

@@ -5,4 +5,5 @@ module.exports = {
   READ_ONLY: 1,
   FOR_UPDATE: 2,
   SCROLLABLE: 3,
+  PARAMETER_COUNT_AVAILABLE: 8,
 };

package/lib/packets/encode_parameter.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const Types = require('../constants/types');
+const Packet = require('../packets/packet');
+
+function isJSON(value) {
+  return (
+    Array.isArray(value) ||
+    value.constructor === Object ||
+    (typeof value.toJSON === 'function' && !Buffer.isBuffer(value))
+  );
+}
+
+function toParameter(value, encoding, timezone) {
+  let type = Types.VAR_STRING;
+  let length;
+  let writer = function (value) {
+    // eslint-disable-next-line no-invalid-this
+    return Packet.prototype.writeLengthCodedString.call(this, value, encoding);
+  };
+  if (value !== null) {
+    switch (typeof value) {
+      case 'undefined':
+        throw new TypeError('Bind parameters must not contain undefined');
+
+      case 'number':
+        type = Types.DOUBLE;
+        length = 8;
+        writer = Packet.prototype.writeDouble;
+        break;
+
+      case 'boolean':
+        value = value | 0;
+        type = Types.TINY;
+        length = 1;
+        writer = Packet.prototype.writeInt8;
+        break;
+
+      case 'object':
+        if (Object.prototype.toString.call(value) === '[object Date]') {
+          type = Types.DATETIME;
+          length = 12;
+          writer = function (value) {
+            // eslint-disable-next-line no-invalid-this
+            return Packet.prototype.writeDate.call(this, value, timezone);
+          };
+        } else if (isJSON(value)) {
+          value = JSON.stringify(value);
+          type = Types.JSON;
+        } else if (Buffer.isBuffer(value)) {
+          length = Packet.lengthCodedNumberLength(value.length) + value.length;
+          writer = Packet.prototype.writeLengthCodedBuffer;
+        }
+        break;
+
+      default:
+        value = value.toString();
+    }
+  } else {
+    value = '';
+    type = Types.NULL;
+  }
+  if (!length) {
+    length = Packet.lengthCodedStringLength(value, encoding);
+  }
+  return { value, type, length, writer };
+}
+
+module.exports = { toParameter, isJSON };

package/lib/packets/execute.js

@@ -2,83 +2,27 @@
 
 const CursorType = require('../constants/cursor');
 const CommandCodes = require('../constants/commands');
+const ClientConstants = require('../constants/client');
 const Types = require('../constants/types');
 const Packet = require('../packets/packet');
 const CharsetToEncoding = require('../constants/charset_encodings.js');
-
-function isJSON(value) {
-  return (
-    Array.isArray(value) ||
-    value.constructor === Object ||
-    (typeof value.toJSON === 'function' && !Buffer.isBuffer(value))
-  );
-}
-
-/**
- * Converts a value to an object describing type, String/Buffer representation and length
- * @param {*} value
- */
-function toParameter(value, encoding, timezone) {
-  let type = Types.VAR_STRING;
-  let length;
-  let writer = function (value) {
-    // eslint-disable-next-line no-invalid-this
-    return Packet.prototype.writeLengthCodedString.call(this, value, encoding);
-  };
-  if (value !== null) {
-    switch (typeof value) {
-      case 'undefined':
-        throw new TypeError('Bind parameters must not contain undefined');
-
-      case 'number':
-        type = Types.DOUBLE;
-        length = 8;
-        writer = Packet.prototype.writeDouble;
-        break;
-
-      case 'boolean':
-        value = value | 0;
-        type = Types.TINY;
-        length = 1;
-        writer = Packet.prototype.writeInt8;
-        break;
-
-      case 'object':
-        if (Object.prototype.toString.call(value) === '[object Date]') {
-          type = Types.DATETIME;
-          length = 12;
-          writer = function (value) {
-            // eslint-disable-next-line no-invalid-this
-            return Packet.prototype.writeDate.call(this, value, timezone);
-          };
-        } else if (isJSON(value)) {
-          value = JSON.stringify(value);
-          type = Types.JSON;
-        } else if (Buffer.isBuffer(value)) {
-          length = Packet.lengthCodedNumberLength(value.length) + value.length;
-          writer = Packet.prototype.writeLengthCodedBuffer;
-        }
-        break;
-
-      default:
-        value = value.toString();
-    }
-  } else {
-    value = '';
-    type = Types.NULL;
-  }
-  if (!length) {
-    length = Packet.lengthCodedStringLength(value, encoding);
-  }
-  return { value, type, length, writer };
-}
+const { toParameter } = require('./encode_parameter.js');
 
 class Execute {
-  constructor(id, parameters, charsetNumber, timezone) {
+  constructor(
+    id,
+    parameters,
+    charsetNumber,
+    timezone,
+    attributes,
+    clientFlags
+  ) {
     this.id = id;
     this.parameters = parameters;
     this.encoding = CharsetToEncoding[charsetNumber];
     this.timezone = timezone;
+    this.attributes = attributes;
+    this.clientFlags = clientFlags || 0;
   }
 
   static fromPacket(packet, encoding) {
@@ -145,39 +89,48 @@ class Execute {
     return { stmtId, flags, iterationCount, values };
   }
 
-  toPacket() {
-    // TODO: don't try to calculate packet length in advance, allocate some big buffer in advance (header + 256 bytes?)
-    // and copy + reallocate if not enough
-    // 0 + 4 - length, seqId
-    // 4 + 1 - COM_EXECUTE
-    // 5 + 4 - stmtId
-    // 9 + 1 - flags
-    // 10 + 4 - iteration-count (always 1)
-    let length = 14;
-    let parameters;
-    if (this.parameters && this.parameters.length > 0) {
-      length += Math.floor((this.parameters.length + 7) / 8);
-      length += 1; // new-params-bound-flag
-      length += 2 * this.parameters.length; // type byte for each parameter if new-params-bound-flag is set
-      parameters = this.parameters.map((value) =>
-        toParameter(value, this.encoding, this.timezone)
-      );
-      length += parameters.reduce(
-        (accumulator, parameter) => accumulator + parameter.length,
-        0
-      );
-    }
-    const buffer = Buffer.allocUnsafe(length);
-    const packet = new Packet(0, buffer, 0, length);
+  _serializeToBuffer(buffer) {
+    const useQueryAttributes =
+      this.clientFlags & ClientConstants.CLIENT_QUERY_ATTRIBUTES;
+
+    const attrNames =
+      useQueryAttributes && this.attributes ? Object.keys(this.attributes) : [];
+    const numParams = this.parameters ? this.parameters.length : 0;
+    const numAttrs = attrNames.length;
+    const totalParams = numParams + numAttrs;
+
+    const packet = new Packet(0, buffer, 0, buffer.length);
     packet.offset = 4;
     packet.writeInt8(CommandCodes.STMT_EXECUTE);
     packet.writeInt32(this.id);
-    packet.writeInt8(CursorType.NO_CURSOR); // flags
+
+    let cursorFlags = CursorType.NO_CURSOR;
+    if (useQueryAttributes) {
+      cursorFlags |= CursorType.PARAMETER_COUNT_AVAILABLE;
+    }
+    packet.writeInt8(cursorFlags);
     packet.writeInt32(1); // iteration-count, always 1
-    if (parameters) {
+
+    if (useQueryAttributes) {
+      packet.writeLengthCodedNumber(totalParams);
+    }
+
+    if (totalParams > 0) {
+      const bindParams =
+        numParams > 0
+          ? this.parameters.map((v) =>
+              toParameter(v, this.encoding, this.timezone)
+            )
+          : [];
+      const attrParams = attrNames.map((name) =>
+        toParameter(this.attributes[name], this.encoding, this.timezone)
+      );
+      const allParams = bindParams.concat(attrParams);
+
+      // null bitmap
       let bitmap = 0;
       let bitValue = 1;
-      parameters.forEach((parameter) => {
+      allParams.forEach((parameter) => {
         if (parameter.type === Types.NULL) {
           bitmap += bitValue;
         }
@@ -191,24 +144,34 @@ class Execute {
       if (bitValue !== 1) {
         packet.writeInt8(bitmap);
       }
-      // TODO: explain meaning of the flag
-      // afaik, if set n*2 bytes with type of parameter are sent before parameters
-      // if not, previous execution types are used (TODO prooflink)
+
       packet.writeInt8(1); // new-params-bound-flag
-      // Write parameter types
-      parameters.forEach((parameter) => {
-        packet.writeInt8(parameter.type); // field type
-        packet.writeInt8(0); // parameter flag
-      });
-      // Write parameter values
-      parameters.forEach((parameter) => {
+
+      // types (and names for attributes)
+      for (let i = 0; i < allParams.length; i++) {
+        packet.writeInt8(allParams[i].type);
+        packet.writeInt8(0); // unsigned flag
+        if (useQueryAttributes) {
+          const name = i < numParams ? '' : attrNames[i - numParams];
+          packet.writeLengthCodedString(name, this.encoding);
+        }
+      }
+
+      // values
+      allParams.forEach((parameter) => {
         if (parameter.type !== Types.NULL) {
           parameter.writer.call(packet, parameter.value);
         }
       });
     }
+
     return packet;
   }
+
+  toPacket() {
+    const p = this._serializeToBuffer(Packet.MockBuffer());
+    return this._serializeToBuffer(Buffer.allocUnsafe(p.offset));
+  }
 }
 
 module.exports = Execute;

package/lib/packets/query.js

@@ -4,24 +4,99 @@ const Packet = require('../packets/packet.js');
 const CommandCode = require('../constants/commands.js');
 const StringParser = require('../parsers/string.js');
 const CharsetToEncoding = require('../constants/charset_encodings.js');
+const ClientConstants = require('../constants/client.js');
+const Types = require('../constants/types.js');
+const { toParameter } = require('./encode_parameter.js');
 
 class Query {
-  constructor(sql, charsetNumber) {
+  constructor(sql, charsetNumber, attributes, clientFlags) {
     this.query = sql;
     this.charsetNumber = charsetNumber;
     this.encoding = CharsetToEncoding[charsetNumber];
+    this.attributes = attributes;
+    this.clientFlags = clientFlags || 0;
   }
 
-  toPacket() {
-    const buf = StringParser.encode(this.query, this.encoding);
-    const length = 5 + buf.length;
-    const buffer = Buffer.allocUnsafe(length);
-    const packet = new Packet(0, buffer, 0, length);
+  serializeToBuffer(buffer) {
+    const useQueryAttributes =
+      this.clientFlags & ClientConstants.CLIENT_QUERY_ATTRIBUTES;
+    const sqlBuf = StringParser.encode(this.query, this.encoding);
+    const packet = new Packet(0, buffer, 0, buffer.length);
     packet.offset = 4;
     packet.writeInt8(CommandCode.QUERY);
-    packet.writeBuffer(buf);
+
+    if (useQueryAttributes) {
+      const attrs = this.attributes;
+      const names = attrs ? Object.keys(attrs) : [];
+      const paramCount = names.length;
+
+      packet.writeLengthCodedNumber(paramCount);
+      packet.writeLengthCodedNumber(1); // parameter_set_count, always 1
+
+      if (paramCount > 0) {
+        const parameters = names.map((name) =>
+          toParameter(attrs[name], this.encoding, 'local')
+        );
+
+        // null bitmap
+        let bitmap = 0;
+        let bitValue = 1;
+        parameters.forEach((parameter) => {
+          if (parameter.type === Types.NULL) {
+            bitmap += bitValue;
+          }
+          bitValue *= 2;
+          if (bitValue === 256) {
+            packet.writeInt8(bitmap);
+            bitmap = 0;
+            bitValue = 1;
+          }
+        });
+        if (bitValue !== 1) {
+          packet.writeInt8(bitmap);
+        }
+
+        packet.writeInt8(1); // new_params_bind_flag
+
+        // types and names
+        for (let i = 0; i < paramCount; i++) {
+          packet.writeInt8(parameters[i].type);
+          packet.writeInt8(0); // unsigned flag
+          packet.writeLengthCodedString(names[i], this.encoding);
+        }
+
+        // values
+        parameters.forEach((parameter) => {
+          if (parameter.type !== Types.NULL) {
+            parameter.writer.call(packet, parameter.value);
+          }
+        });
+      }
+    }
+
+    packet.writeBuffer(sqlBuf);
     return packet;
   }
+
+  toPacket() {
+    const useQueryAttributes =
+      this.clientFlags & ClientConstants.CLIENT_QUERY_ATTRIBUTES;
+
+    if (!useQueryAttributes) {
+      const buf = StringParser.encode(this.query, this.encoding);
+      const length = 5 + buf.length;
+      const buffer = Buffer.allocUnsafe(length);
+      const packet = new Packet(0, buffer, 0, length);
+      packet.offset = 4;
+      packet.writeInt8(CommandCode.QUERY);
+      packet.writeBuffer(buf);
+      return packet;
+    }
+
+    // dry run to calculate required buffer length
+    const p = this.serializeToBuffer(Packet.MockBuffer());
+    return this.serializeToBuffer(Buffer.allocUnsafe(p.offset));
+  }
 }
 
 module.exports = Query;

package/lib/packets/resultset_header.js

@@ -39,7 +39,7 @@ class ResultSetHeader {
     if (isSet('SESSION_TRACK') && packet.offset < packet.end) {
       this.info = packet.readLengthCodedString(encoding);
 
-      if (this.serverStatus && ServerSatusFlags.SERVER_SESSION_STATE_CHANGED) {
+      if (this.serverStatus & ServerSatusFlags.SERVER_SESSION_STATE_CHANGED) {
         // session change info record - see
         // https://dev.mysql.com/doc/internals/en/packet-OK_Packet.html#cs-sect-packet-ok-sessioninfo
         let len =

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mysql2",
-  "version": "3.20.0",
+  "version": "3.20.1-canary.2bdc12a4",
   "description": "fast mysql driver. Implements core protocol, prepared statements, ssl and compression in native JS",
   "main": "index.js",
   "typings": "typings/mysql/index",

package/typings/mysql/index.d.ts

@@ -8,6 +8,8 @@ import {
   Query as BaseQuery,
   QueryOptions,
   QueryError,
+  ExecuteValues,
+  QueryValues,
 } from './lib/protocol/sequences/Query.js';
 import {
   PoolCluster as BasePoolCluster,
@@ -35,6 +37,8 @@ export {
   PoolNamespace,
   QueryOptions,
   QueryError,
+  ExecuteValues,
+  QueryValues,
   PrepareStatementInfo,
 };
 

package/typings/mysql/lib/protocol/sequences/Query.d.ts

@@ -43,6 +43,13 @@ export interface QueryOptions {
    */
   values?: QueryValues;
 
+  /**
+   * Query attributes sent alongside the query (MySQL 8.0.25+).
+   * Requires the `component_query_attributes` server component to be read via
+   * `mysql_query_attribute_string()`.
+   */
+  attributes?: Record<string, string | number | boolean | null | Buffer | Date>;
+
   /**
    * This overrides the namedPlaceholders option set at the connection level.
    */