mysql2 2.2.2 → 2.3.0

package/Changelog.md

@@ -1,3 +1,29 @@
+2.3.0
+  - Add PoolCluster promise wrappers               #1369, #1363
+  - support for connect and query timeouts         #1364
+  - add missing query() method on PoolCluster      #1362
+  - fix incorrect parsing of passwords 
+    containing ":"                                 #1357
+  - handle errors generated by asynchronous 
+    authentication plugins                         #1354
+  - add proper handshake fatal error handling      #1352
+  - fix tests to work with the latest MySQL 
+    server versions (up to 8.0.25)                 #1338
+  - expose SQL query in errors                     #1295
+  - typing and readme docs for rowAsArray          #1288
+  - allow unnamed placeholders even if the 
+    namedPlaceholders flag is enabled              #1251
+  - better ESM support                             #1217
+  
+2.2.5 ( 21/09/2020 )
+  - typings: add ResultSetHeader                   #1213
+
+2.2.4 ( 21/09/2020 )
+  - use bundled types/mysql instead of dependency  #1211
+
+2.2.3 ( 21/09/2020 )
+  - use github:types/mysql as base for types       #1208
+
 2.2.2 ( 19/09/2020 )
   - Add the authPlugins types to ConnectionOptions #1206
 

package/README.md

@@ -216,6 +216,32 @@ con.promise().query("SELECT 1")
   .then( () => con.end());
 ```
 
+## Array results
+
+If you have two columns with the same name, you might want to get results as an array rather than an object to prevent them from clashing. This is a deviation from the [Node MySQL][node-mysql] library.
+
+For example: `select 1 as foo, 2 as foo`.
+
+You can enable this setting at either the connection level (applies to all queries), or at the query level (applies only to that specific query).
+
+### Connection Option
+```js
+const con = mysql.createConnection(
+  { host: 'localhost', database: 'test', user: 'root', rowsAsArray: true }
+);
+
+```
+
+### Query Option
+
+```js
+con.query({ sql: 'select 1 as foo, 2 as foo', rowsAsArray: true }, function(err, results, fields) {
+  console.log(results) // will be an array of arrays rather than an array of objects
+  console.log(fields) // these are unchanged
+});
+
+```
+
 ## API and Configuration
 
 MySQL2 is mostly API compatible with [Node MySQL][node-mysql]. You should check their API documentation to see all available API options.

package/index.d.ts

@@ -4,8 +4,8 @@ import {
   PoolConnection as PromisePoolConnection
 } from './promise';
 
-import * as mysql from 'mysql';
-export * from 'mysql';
+import * as mysql from './typings/mysql';
+export * from './typings/mysql';
 
 export interface Connection extends mysql.Connection {
   execute<
@@ -14,6 +14,7 @@ export interface Connection extends mysql.Connection {
       | mysql.RowDataPacket[]
       | mysql.OkPacket
       | mysql.OkPacket[]
+      | mysql.ResultSetHeader
   >(
     sql: string,
     callback?: (
@@ -28,6 +29,7 @@ export interface Connection extends mysql.Connection {
       | mysql.RowDataPacket[]
       | mysql.OkPacket
       | mysql.OkPacket[]
+      | mysql.ResultSetHeader
   >(
     sql: string,
     values: any | any[] | { [param: string]: any },
@@ -43,6 +45,7 @@ export interface Connection extends mysql.Connection {
       | mysql.RowDataPacket[]
       | mysql.OkPacket
       | mysql.OkPacket[]
+      | mysql.ResultSetHeader
   >(
     options: mysql.QueryOptions,
     callback?: (
@@ -57,6 +60,7 @@ export interface Connection extends mysql.Connection {
       | mysql.RowDataPacket[]
       | mysql.OkPacket
       | mysql.OkPacket[]
+      | mysql.ResultSetHeader
   >(
     options: mysql.QueryOptions,
     values: any | any[] | { [param: string]: any },
@@ -81,6 +85,7 @@ export interface Pool extends mysql.Connection {
       | mysql.RowDataPacket[]
       | mysql.OkPacket
       | mysql.OkPacket[]
+      | mysql.ResultSetHeader
   >(
     sql: string,
     callback?: (
@@ -95,6 +100,7 @@ export interface Pool extends mysql.Connection {
       | mysql.RowDataPacket[]
       | mysql.OkPacket
       | mysql.OkPacket[]
+      | mysql.ResultSetHeader
   >(
     sql: string,
     values: any | any[] | { [param: string]: any },
@@ -110,6 +116,7 @@ export interface Pool extends mysql.Connection {
       | mysql.RowDataPacket[]
       | mysql.OkPacket
       | mysql.OkPacket[]
+      | mysql.ResultSetHeader
   >(
     options: mysql.QueryOptions,
     callback?: (
@@ -124,6 +131,7 @@ export interface Pool extends mysql.Connection {
       | mysql.RowDataPacket[]
       | mysql.OkPacket
       | mysql.OkPacket[]
+      | mysql.ResultSetHeader
   >(
     options: mysql.QueryOptions,
     values: any | any[] | { [param: string]: any },
@@ -142,11 +150,14 @@ export interface Pool extends mysql.Connection {
   on(event: 'enqueue', listener: () => any): this;
   promise(promiseImpl?: PromiseConstructor): PromisePool;
 }
-    
-type authPlugins =
-    (pluginMetadata: { connection: Connection; command: string }) =>
-        (pluginData: Buffer) => Promise<string>;
-    
+
+type authPlugins = (pluginMetadata: {
+  connection: Connection;
+  command: string;
+}) => (
+  pluginData: Buffer
+) => Promise<string> | string | Buffer | Promise<Buffer> | null;
+
 export interface ConnectionOptions extends mysql.ConnectionOptions {
   charsetNumber?: number;
   compress?: boolean;
@@ -167,7 +178,7 @@ export interface ConnectionOptions extends mysql.ConnectionOptions {
   queueLimit?: number;
   waitForConnections?: boolean;
   authPlugins?: {
-      [key: string]: authPlugins;
+    [key: string]: authPlugins;
   };
 }
 

package/index.js

@@ -14,6 +14,7 @@ exports.connect = exports.createConnection;
 exports.Connection = Connection;
 
 const Pool = require('./lib/pool.js');
+const PoolCluster = require('./lib/pool_cluster.js');
 
 exports.createPool = function(config) {
   const PoolConfig = require('./lib/pool_config.js');
@@ -29,6 +30,8 @@ exports.createQuery = Connection.createQuery;
 
 exports.Pool = Pool;
 
+exports.PoolCluster = PoolCluster;
+
 exports.createServer = function(handler) {
   const Server = require('./lib/server.js');
   const s = new Server();

package/lib/commands/auth_switch.js

@@ -1,3 +1,8 @@
+// This file was modified by Oracle on July 5, 2021.
+// Errors generated by asynchronous authentication plugins are now being
+// handled and subsequently emitted at the command level.
+// Modifications copyright (c) 2021, Oracle and/or its affiliates.
+
 'use strict';
 
 const Packets = require('../packets/index.js');
@@ -17,6 +22,14 @@ function warnLegacyAuthSwitch() {
   );
 }
 
+function authSwitchPluginError(error, command) {
+  // Authentication errors are fatal
+  error.code = 'AUTH_SWITCH_PLUGIN_ERROR';
+  error.fatal = true;
+
+  command.emit('error', error);
+}
+
 function authSwitchRequest(packet, connection, command) {
   const { pluginName, pluginData } = Packets.AuthSwitchRequest.fromPacket(
     packet
@@ -34,8 +47,7 @@ function authSwitchRequest(packet, connection, command) {
     warnLegacyAuthSwitch();
     legacySwitchHandler({ pluginName, pluginData }, (err, data) => {
       if (err) {
-        connection.emit('error', err);
-        return;
+        return authSwitchPluginError(err, command);
       }
       connection.writePacket(new Packets.AuthSwitchResponse(data).toPacket());
     });
@@ -54,10 +66,12 @@ function authSwitchRequest(packet, connection, command) {
     if (data) {
       connection.writePacket(new Packets.AuthSwitchResponse(data).toPacket());
     }
+  }).catch(err => {
+    authSwitchPluginError(err, command);
   });
 }
 
-function authSwitchRequestMoreData(packet, connection) {
+function authSwitchRequestMoreData(packet, connection, command) {
   const { data } = Packets.AuthSwitchRequestMoreData.fromPacket(packet);
 
   if (connection.config.authSwitchHandler) {
@@ -65,8 +79,7 @@ function authSwitchRequestMoreData(packet, connection) {
     warnLegacyAuthSwitch();
     legacySwitchHandler({ pluginData: data }, (err, data) => {
       if (err) {
-        connection.emit('error', err);
-        return;
+        return authSwitchPluginError(err, command);
       }
       connection.writePacket(new Packets.AuthSwitchResponse(data).toPacket());
     });
@@ -82,6 +95,8 @@ function authSwitchRequestMoreData(packet, connection) {
     if (data) {
       connection.writePacket(new Packets.AuthSwitchResponse(data).toPacket());
     }
+  }).catch(err => {
+    authSwitchPluginError(err, command);
   });
 }
 

package/lib/commands/client_handshake.js

@@ -1,3 +1,8 @@
+// This file was modified by Oracle on June 17, 2021.
+// Handshake errors are now maked as fatal and the corresponding events are
+// emitted in the command instance itself.
+// Modifications copyright (c) 2021, Oracle and/or its affiliates.
+
 'use strict';
 
 const Command = require('./command.js');
@@ -151,20 +156,28 @@ class ClientHandshake extends Command {
         }
         return ClientHandshake.prototype.handshakeResult;
       } catch (err) {
+        // Authentication errors are fatal
+        err.code = 'AUTH_SWITCH_PLUGIN_ERROR';
+        err.fatal = true;
+
         if (this.onResult) {
           this.onResult(err);
         } else {
-          connection.emit('error', err);
+          this.emit('error', err);
         }
         return null;
       }
     }
     if (marker !== 0) {
       const err = new Error('Unexpected packet during handshake phase');
+      // Unknown handshake errors are fatal
+      err.code = 'HANDSHAKE_UNKNOWN_ERROR';
+      err.fatal = true;
+
       if (this.onResult) {
         this.onResult(err);
       } else {
-        connection.emit('error', err);
+        this.emit('error', err);
       }
       return null;
     }

package/lib/commands/command.js

@@ -26,6 +26,7 @@ class Command extends EventEmitter {
     }
     if (packet && packet.isError()) {
       const err = packet.asError(connection.clientEncoding);
+      err.sql = this.sql || this.query;
       if (this.onResult) {
         this.onResult(err);
         this.emit('end');

package/lib/commands/execute.js

@@ -15,6 +15,8 @@ class Execute extends Command {
     this.onResult = callback;
     this.parameters = options.values;
     this.insertId = 0;
+    this.timeout = options.timeout;
+    this.queryTimeout = null;
     this._rows = [];
     this._fields = [];
     this._result = [];
@@ -35,6 +37,7 @@ class Execute extends Command {
   start(packet, connection) {
     this._connection = connection;
     this.options = Object.assign({}, connection.config, this._executeOptions);
+    this._setTimeout();
     const executePacket = new Packets.Execute(
       this.statement.id,
       this.parameters,
@@ -96,6 +99,8 @@ Execute.prototype.resultsetHeader = Query.prototype.resultsetHeader;
 Execute.prototype._findOrCreateReadStream =
   Query.prototype._findOrCreateReadStream;
 Execute.prototype._streamLocalInfile = Query.prototype._streamLocalInfile;
+Execute.prototype._setTimeout = Query.prototype._setTimeout;
+Execute.prototype._handleTimeoutError = Query.prototype._handleTimeoutError;
 Execute.prototype.row = Query.prototype.row;
 Execute.prototype.stream = Query.prototype.stream;
 

package/lib/commands/query.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const process = require('process');
+const Timers = require('timers');
 
 const Readable = require('stream').Readable;
 
@@ -21,6 +22,8 @@ class Query extends Command {
     this._queryOptions = options;
     this.namedPlaceholders = options.namedPlaceholders || false;
     this.onResult = callback;
+    this.timeout = options.timeout;
+    this.queryTimeout = null;
     this._fieldCount = 0;
     this._rowParser = null;
     this._fields = [];
@@ -48,6 +51,8 @@ class Query extends Command {
     }
     this._connection = connection;
     this.options = Object.assign({}, connection.config, this._queryOptions);
+    this._setTimeout();
+
     const cmdPacket = new Packets.Query(
       this.sql,
       connection.config.charsetNumber
@@ -58,6 +63,15 @@ class Query extends Command {
 
   done() {
     this._unpipeStream();
+    // if all ready timeout, return null directly
+    if (this.timeout && !this.queryTimeout) {
+      return null;
+    }
+    // else clear timer
+    if (this.queryTimeout) {
+      Timers.clearTimeout(this.queryTimeout);
+      this.queryTimeout = null;
+    }
     if (this.onResult) {
       let rows, fields;
       if (this._resultIndex === 0) {
@@ -272,6 +286,34 @@ class Query extends Command {
     });
     return stream;
   }
+
+  _setTimeout() {
+    if (this.timeout) {
+      const timeoutHandler = this._handleTimeoutError.bind(this);
+      this.queryTimeout = Timers.setTimeout(
+        timeoutHandler,
+        this.timeout
+      );
+    }
+  }
+
+  _handleTimeoutError() {
+    if (this.queryTimeout) {
+      Timers.clearTimeout(this.queryTimeout);
+      this.queryTimeout = null;
+    }
+    
+    const err = new Error('Query inactivity timeout');
+    err.errorno = 'PROTOCOL_SEQUENCE_TIMEOUT';
+    err.code = 'PROTOCOL_SEQUENCE_TIMEOUT';
+    err.syscall = 'query';
+
+    if (this.onResult) {
+      this.onResult(err);
+    } else {
+      this.emit('error', err);
+    }
+  }
 }
 
 Query.prototype.catch = Query.prototype.then;

package/lib/connection.js

@@ -1,3 +1,13 @@
+// This file was modified by Oracle on June 1, 2021.
+// The changes involve new logic to handle an additional ERR Packet sent by
+// the MySQL server when the connection is closed unexpectedly.
+// Modifications copyright (c) 2021, Oracle and/or its affiliates.
+
+// This file was modified by Oracle on June 17, 2021.
+// The changes involve logic to ensure the socket connection is closed when
+// there is a fatal error.
+// Modifications copyright (c) 2021, Oracle and/or its affiliates.
+
 'use strict';
 
 const Net = require('net');
@@ -100,9 +110,10 @@ class Connection extends EventEmitter {
     if (!this.config.isServer) {
       handshakeCommand = new Commands.ClientHandshake(this.config.clientFlags);
       handshakeCommand.on('end', () => {
-        // this happens when handshake finishes early and first packet is error
-        // and not server hello ( for example, 'Too many connactions' error)
-        if (!handshakeCommand.handshake) {
+        // this happens when handshake finishes early either because there was
+        // some fatal error or the server sent an error packet instead of
+        // an hello packet (for example, 'Too many connactions' error)
+        if (!handshakeCommand.handshake || this._fatalError || this._protocolError) {
           return;
         }
         this._handshakePacket = handshakeCommand.handshake;
@@ -188,7 +199,7 @@ class Connection extends EventEmitter {
     if (this.connectTimeout) {
       Timers.clearTimeout(this.connectTimeout);
       this.connectTimeout = null;
-    }    
+    }
     // prevent from emitting 'PROTOCOL_CONNECTION_LOST' after EPIPE or ECONNRESET
     if (this._fatalError) {
       return;
@@ -224,6 +235,10 @@ class Connection extends EventEmitter {
     if (bubbleErrorToConnection || this._pool) {
       this.emit('error', err);
     }
+    // close connection after emitting the event in case of a fatal error
+    if (err.fatal) {
+      this.close();
+    }
   }
 
   write(buffer) {
@@ -368,6 +383,14 @@ class Connection extends EventEmitter {
   }
 
   protocolError(message, code) {
+    // Starting with MySQL 8.0.24, if the client closes the connection
+    // unexpectedly, the server will send a last ERR Packet, which we can
+    // safely ignore.
+    // https://dev.mysql.com/worklog/task/?id=12999
+    if (this._closing) {
+      return;
+    }
+
     const err = new Error(message);
     err.fatal = true;
     err.code = code || 'PROTOCOL_ERROR';
@@ -415,10 +438,18 @@ class Connection extends EventEmitter {
       }
     }
     if (!this._command) {
-      this.protocolError(
-        'Unexpected packet while no commands in the queue',
-        'PROTOCOL_UNEXPECTED_PACKET'
-      );
+      const marker = packet.peekByte();
+      // If it's an Err Packet, we should use it.
+      if (marker === 0xff) {
+        const error = Packets.Error.fromPacket(packet);
+        this.protocolError(error.message, error.code);
+      } else {
+        // Otherwise, it means it's some other unexpected packet.
+        this.protocolError(
+          'Unexpected packet while no commands in the queue',
+          'PROTOCOL_UNEXPECTED_PACKET'
+        );
+      }
       this.close();
       return;
     }
@@ -488,6 +519,11 @@ class Connection extends EventEmitter {
   _resolveNamedPlaceholders(options) {
     let unnamed;
     if (this.config.namedPlaceholders || options.namedPlaceholders) {
+      if (Array.isArray(options.values)) {
+        // if an array is provided as the values, assume the conversion is not necessary.
+        // this allows the usage of unnamed placeholders even if the namedPlaceholders flag is enabled.
+        return
+      }
       if (convertNamedPlaceholders === null) {
         convertNamedPlaceholders = require('named-placeholders')();
       }

package/lib/connection_config.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const urlParse = require('url').parse;
+const { URL } = require('url');
 const ClientConstants = require('./constants/client');
 const Charsets = require('./constants/charsets');
 let SSLProfiles = null;
@@ -232,29 +232,23 @@ class ConnectionConfig {
   }
 
   static parseUrl(url) {
-    url = urlParse(url, true);
+    const parsedUrl = new URL(url);
     const options = {
-      host: url.hostname,
-      port: url.port,
-      database: url.pathname.substr(1)
+      host: parsedUrl.hostname,
+      port: parsedUrl.port,
+      database: parsedUrl.pathname.substr(1),
+      user: parsedUrl.username,
+      password: parsedUrl.password
     };
-    if (url.auth) {
-      const auth = url.auth.split(':');
-      options.user = auth[0];
-      options.password = auth[1];
-    }
-    if (url.query) {
-      for (const key in url.query) {
-        const value = url.query[key];
-        try {
-          // Try to parse this as a JSON expression first
-          options[key] = JSON.parse(value);
-        } catch (err) {
-          // Otherwise assume it is a plain string
-          options[key] = value;
-        }
+    parsedUrl.searchParams.forEach((value, key) => {
+      try {
+        // Try to parse this as a JSON expression first
+        options[key] = JSON.parse(value);
+      } catch (err) {
+        // Otherwise assume it is a plain string
+        options[key] = value;
       }
-    }
+    });
     return options;
   }
 }

package/lib/constants/errors.js

@@ -1,3 +1,8 @@
+// This file was modified by Oracle on June 1, 2021.
+// An entry was created for a new error reported by the MySQL server due to
+// client inactivity.
+// Modifications copyright (c) 2021, Oracle and/or its affiliates.
+
 'use strict';
 
 // copy from https://raw.githubusercontent.com/mysqljs/mysql/7770ee5bb13260c56a160b91fe480d9165dbeeba/lib/protocol/constants/errors.js
@@ -994,6 +999,7 @@ exports.ER_INNODB_FT_AUX_NOT_HEX_ID = 1879;
 exports.ER_OLD_TEMPORALS_UPGRADED = 1880;
 exports.ER_INNODB_FORCED_RECOVERY = 1881;
 exports.ER_AES_INVALID_IV = 1882;
+exports.ER_CLIENT_INTERACTION_TIMEOUT = 4031;
 
 // Lookup-by-number table
 exports[1] = 'EE_CANTCREATEFILE';
@@ -1982,3 +1988,4 @@ exports[1879] = 'ER_INNODB_FT_AUX_NOT_HEX_ID';
 exports[1880] = 'ER_OLD_TEMPORALS_UPGRADED';
 exports[1881] = 'ER_INNODB_FORCED_RECOVERY';
 exports[1882] = 'ER_AES_INVALID_IV';
+exports[4031] = 'ER_CLIENT_INTERACTION_TIMEOUT';

package/lib/packets/index.js

@@ -1,3 +1,8 @@
+// This file was modified by Oracle on June 1, 2021.
+// A utility method was introduced to generate an Error instance from a
+// binary server packet.
+// Modifications copyright (c) 2021, Oracle and/or its affiliates.
+
 'use strict';
 
 const process = require('process');
@@ -122,6 +127,20 @@ class Error {
     packet._name = 'Error';
     return packet;
   }
+
+  static fromPacket(packet) {
+    packet.readInt8(); // marker
+    const code = packet.readInt16();
+    packet.readString(1, 'ascii'); // sql state marker
+    // The SQL state of the ERR_Packet which is always 5 bytes long.
+    // https://dev.mysql.com/doc/dev/mysql-server/8.0.11/page_protocol_basic_dt_strings.html#sect_protocol_basic_dt_string_fix
+    packet.readString(5, 'ascii'); // sql state (ignore for now)
+    const message = packet.readNullTerminatedString('utf8');
+    const error = new Error();
+    error.message = message;
+    error.code = code;
+    return error;
+  }
 }
 
 exports.Error = Error;

package/lib/packets/packet.js

@@ -1,3 +1,8 @@
+// This file was modified by Oracle on June 1, 2021.
+// A comment describing some changes in the strict default SQL mode regarding
+// non-standard dates was introduced.
+// Modifications copyright (c) 2021, Oracle and/or its affiliates.
+
 'use strict';
 
 const ErrorCodeToName = require('../constants/errors.js');
@@ -274,6 +279,11 @@ class Packet {
       if (length > 10) {
         ms = this.readInt32() / 1000;
       }
+      // NO_ZERO_DATE mode and NO_ZERO_IN_DATE mode are part of the strict
+      // default SQL mode used by MySQL 8.0. This means that non-standard
+      // dates like '0000-00-00' become NULL. For older versions and other
+      // possible MySQL flavours we still need to account for the
+      // non-standard behaviour.
       if (y + m + d + H + M + S + ms === 0) {
         return INVALID_DATE;
       }