Merge branch 'sidorares:master' into release-idle-connection

Author: yq

CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[email protected].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

Changelog.md

@@ -1,3 +1,15 @@
+2.3.3 ( 14/11/2021 )
+  - no changes compared to 2.3.3-rc.0
+
+2.3.3-rc.0 ( 5/11/2021 )
+  - fix ColumnDefinition.db is broken when 
+    encoding is not utf-8                         #1423                 
+  - typeCast: Fix field.length to be number       #1427, #1426
+  - initiall support for coverage reporting in CI #1425
+  - fix performance regression for results with   #1445, #1432
+    large (300+) number of columns                
+                                                  
+
 2.3.2 ( 16/10/2021 )
   - fix regression causing typeCast + JSON field
     to error                                      #1418, #1420

README.md

@@ -6,7 +6,9 @@
 [![Node.js Version][node-version-image]][node-version-url]
 [![Linux Build][travis-image]][travis-url]
 [![Windows Build][appveyor-image]][appveyor-url]
-[![License][license-image]][license-url]
+[![License][license-image]][license-url]  
+
+[简体中文 Simplified Chinese](./documentation_zh-cn/)
 
 > MySQL client for Node.js with focus on performance. Supports prepared statements, non-utf8 encodings, binary log protocol, compression, ssl [much more](https://github.com/sidorares/node-mysql2/tree/master/documentation)
 

documentation/Authentication-Switch.md

@@ -1,16 +1,46 @@
 # Authentication switch request
 
-During connection phase the server may ask client to switch to a different auth method.
-If `authSwitchHandler` connection config option is set it must be a function that receive
-switch request data and respond via callback. Note that if `mysql_native_password` method is
-requested it will be handled internally according to [Authentication::Native41]( https://dev.mysql.com/doc/internals/en/secure-password-authentication.html#packet-Authentication::Native41) and
-`authSwitchHandler` won't be invoked. `authSwitchHandler` MAY be called multiple times if
-plugin algorithm requires multiple roundtrips of data exchange between client and server.
-First invocation always has `({pluginName, pluginData})` signature, following calls - `({pluginData})`.
-The client respond with opaque blob matching requested plugin via `callback(null, data: Buffer)`.
+During the connection phase the server may ask the client to switch to a different auth method.
+If the `authPlugins` connection config option is set, it must be an object where each key
+is the name of a potential authentication plugin requested by the server, and the corresponding
+value must be a function that optionally receives the connection config options and returns
+another function, which in turn, optionally receives the switch request data.
+
+The plugin is loaded with a `({user,password,...})` signature, and each call has a `(pluginData)`
+signature. Each call should make the plugin return any additional authentication data (`Buffer`)
+that should be sent back to the server, either synchronously or asynchronously using a `Promise`,
+or should yield an error accordingly.
 
 Example: (imaginary `ssh-key-auth` plugin) pseudo code
 
+```js
+const conn = mysql.createConnection({
+  user: 'test_user',
+  password: 'test',
+  database: 'test_database',
+  authPlugins: {
+    'ssh-key-auth': function ({password}) {
+      return function (pluginData) {
+        return getPrivate(key)
+          .then(key => {
+            const response = encrypt(key, password, pluginData);
+            // continue handshake by sending response data
+            return response;
+          })
+          .catch(err => {
+            // throw error to propagate error to connect/changeUser handlers
+          });
+      };
+    }
+  }
+});
+```
+
+There is also a deprecated API where if a `authSwitchHandler` connection config option is set
+it must be a function that receives switch request data and responds via a callback. In this case,
+the first invocation always has a `({pluginName, pluginData})` signature, following calls - `({pluginData})`.
+The client replies with an opaque blob matching the requested plugin via `callback(null, data: Buffer)`.
+
 ```js
 const conn = mysql.createConnection({
   user: 'test_user',
@@ -33,4 +63,47 @@ const conn = mysql.createConnection({
 });
 ```
 
-Initial handshake always performed using `mysql_native_password` plugin. This will be possible to override in the future versions.
+The initial handshake is always performed using `mysql_native_password` plugin. This will be possible to override in future versions.
+
+Note that if the `mysql_native_password` method is requested it will be handled internally according
+to [Authentication::Native41]( https://dev.mysql.com/doc/internals/en/secure-password-authentication.html#packet-Authentication::Native41)
+and no `authPlugins` function or the `authSwitchHandler` will be invoked.
+
+These MAY be called multiple times if the plugin algorithm requires multiple roundtrips of data
+exchange between client and server.
+
+## Multi-factor authentication
+
+If the user requires multi-factor authentication in the server, the client will receive a `AuthNextFactor`
+request, which is similar in structure to the regular authentication switch request and contains the name
+and possible initial data for the additional authentication factor plugin (up to 3). Additional passwords
+can be provided using the connection config options - `password2` and `password3`. Again, for each
+authentication factor, multiple roundtrips of data exchange can be required by the plugin algoritm.
+
+```js
+const conn = mysql.createConnection({
+  user: 'test_user',
+  password: 'secret1',
+  password2: 'secret2',
+  password3: 'secret3',
+  database: 'test_database',
+  authPlugins: {
+    // password1 === password
+    'auth-plugin1': function ({password1}) {
+      return function (serverPluginData) {
+        return clientPluginData(password1, serverPluginData);
+      };
+    },
+    'auth-plugin2': function ({password2}) {
+      return function (serverPluginData) {
+        return clientPluginData(password2, serverPluginData);
+      };
+    },
+    'auth-plugin3': function ({password3}) {
+      return function (serverPluginData) {
+        return clientPluginData(password3, serverPluginData);
+      };
+    }
+  }
+});
+```

documentation/Prepared-Statements.md

@@ -13,9 +13,12 @@ connection.execute('select 1 + ? + ? as result', [5, 6], (err, rows) => {
 // close cached statement for 'select 1 + ? + ? as result'. noop if not in cache
 connection.unprepare('select 1 + ? + ? as result');
 ```
+Note that `connection.execute()` will cache the prepared statement for better performance, remove the cache with `connection.unprepare()` when you're done.
 
 ## Manual prepare / execute
 
+Manually prepared statements doesn't comes with LRU cache and SHOULD be closed using `statement.close()` instead of `connection.unprepare()`.
+
 ```js
 connection.prepare('select ? + ? as tests', (err, statement) => {
   // statement.parameters - array of column definitions, length === number of params, here 2
@@ -27,6 +30,7 @@ connection.prepare('select ? + ? as tests', (err, statement) => {
     // -> [ { tests: 3 } ]
   });
 
+  // don't use connection.unprepare(), it won't work!
   // note that there is no callback here. There is no statement close ack at protocol level.
   statement.close();
 });

documentation/Readme.md

@@ -41,7 +41,7 @@ You need to check corresponding field's zeroFill flag and convert to string manu
   - [Wire protocol documentation](http://dev.mysql.com/doc/internals/en/client-server-protocol.html)
   - [node-mysql](https://github.com/mysqljs/mysql) - Most popular node.js mysql client library
   - [node-mariasql](https://github.com/mscdex/node-mariasql/) - Bindings to libmariasql. One of the fastest clients
-  - [node-libmysqlclident](https://github.com/Sannis/node-mysql-libmysqlclient) - Bindings to libmysqlclient
+  - [node-libmysqlclient](https://github.com/Sannis/node-mysql-libmysqlclient) - Bindings to libmysqlclient
   - [go-mysql](https://github.com/siddontang/go-mysql) - MySQL Go client (prepared statements, binlog protocol, server)
 
 ## Benchmarks