mysql2 3.6.4 → 3.7.0

package/README.md

@@ -1,49 +1,72 @@
-## MySQL 2
+[npm-image]: https://img.shields.io/npm/v/mysql2.svg
+[npm-url]: https://npmjs.com/package/mysql2
+[node-version-image]: https://img.shields.io/node/v/mysql2.svg
+[node-version-url]: https://nodejs.org/en/download
+[downloads-image]: https://img.shields.io/npm/dm/mysql2.svg
+[downloads-url]: https://npmjs.com/package/mysql2
+[license-url]: https://github.com/sidorares/node-mysql2/blob/master/License
+[license-image]: https://img.shields.io/npm/l/mysql2.svg?maxAge=2592000
+[node-mysql]: https://github.com/mysqljs/mysql
+[mysqljs]: https://github.com/mysqljs
+[mysql-native]: https://github.com/sidorares/nodejs-mysql-native
+[sidorares]: https://github.com/sidorares
+[TooTallNate]: https://gist.github.com/TooTallNate
+[starttls.js]: https://gist.github.com/TooTallNate/848444
+[node-mariasql]: https://github.com/mscdex/node-mariasql
+[contributors]: https://github.com/sidorares/node-mysql2/graphs/contributors
+[contributing]: https://github.com/sidorares/node-mysql2/blob/master/Contributing.md
+[docs-base]: https://sidorares.github.io/node-mysql2/docs
+[docs-base-zh-CN]: https://sidorares.github.io/node-mysql2/zh-CN/docs
+[docs-base-pt-BR]: https://sidorares.github.io/node-mysql2/pt-BR/docs
+[docs-prepared-statements]: https://sidorares.github.io/node-mysql2/docs/documentation/prepared-statements
+[docs-mysql-server]: https://sidorares.github.io/node-mysql2/docs/documentation/mysql-server
+[docs-promise-wrapper]: https://sidorares.github.io/node-mysql2/docs/documentation/promise-wrapper
+[docs-authentication-switch]: https://sidorares.github.io/node-mysql2/docs/documentation/authentication-switch
+[docs-streams]: https://sidorares.github.io/node-mysql2/docs/documentation/extras
+[docs-typescript-docs]: https://sidorares.github.io/node-mysql2/docs/documentation/typescript-examples
+[docs-qs-pooling]: https://sidorares.github.io/node-mysql2/docs#using-connection-pools
+[docs-qs-first-query]: https://sidorares.github.io/node-mysql2/docs#first-query
+[docs-qs-using-prepared-statements]: https://sidorares.github.io/node-mysql2/docs#using-prepared-statements
+[docs-examples]: https://sidorares.github.io/node-mysql2/docs/examples
+[docs-faq]: https://sidorares.github.io/node-mysql2/docs/faq
+[docs-documentation]: https://sidorares.github.io/node-mysql2/docs/documentation
+[docs-contributing]: https://sidorares.github.io/node-mysql2/docs/contributing/website
+
+# MySQL2
 
-[![Greenkeeper badge](https://badges.greenkeeper.io/sidorares/node-mysql2.svg)](https://greenkeeper.io/)
 [![NPM Version][npm-image]][npm-url]
 [![NPM Downloads][downloads-image]][downloads-url]
 [![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]
 
-English | [简体中文](./documentation/zh-cn/) | [Português (BR)](./documentation/pt-br/)
+[English][docs-base] | [简体中文][docs-base-zh-CN] | [Português (BR)][docs-base-pt-BR]
 
-> MySQL client for Node.js with focus on performance. Supports prepared statements, non-utf8 encodings, binary log protocol, compression, ssl [much more](./documentation/en).
+> MySQL client for Node.js with focus on performance. Supports prepared statements, non-utf8 encodings, binary log protocol, compression, ssl [much more][docs-documentation].
 
-__Table of contents__
+**Table of Contents**
 
-  - [History and Why MySQL2](#history-and-why-mysql2)
-  - [Installation](#installation)
-  - [First Query](#first-query)
-  - [Using Prepared Statements](#using-prepared-statements)
-  - [Using connection pools](#using-connection-pools)
-  - [Using Promise Wrapper](#using-promise-wrapper)
-  - [Array Results](#array-results)
-    - [Connection Level](#connection-level)
-    - [Query Level](#query-level)
-  - [API and Configuration](#api-and-configuration)
-  - [Documentation](#documentation)
-  - [Acknowledgements](#acknowledgements)
-  - [Contributing](#contributing)
+- [History and Why MySQL2](#history-and-why-mysql2)
+- [Installation](#installation)
+- [Documentation](#documentation)
+- [Acknowledgements](#acknowledgements)
+- [Contributing](#contributing)
 
 ## History and Why MySQL2
 
-MySQL2 project is a continuation of [MySQL-Native][mysql-native]. Protocol parser code was rewritten from scratch and api changed to match popular [mysqljs/mysql][node-mysql]. MySQL2 team is working together with [mysqljs/mysql][node-mysql] team to factor out shared code and move it under [mysqljs][node-mysql] organisation.
+MySQL2 project is a continuation of [MySQL-Native][mysql-native]. Protocol parser code was rewritten from scratch and api changed to match popular [Node MySQL][node-mysql]. MySQL2 team is working together with [Node MySQL][node-mysql] team to factor out shared code and move it under [mysqljs][mysqljs] organization.
 
-MySQL2 is mostly API compatible with [mysqljs][node-mysql] and supports majority of features. MySQL2 also offers these additional features:
+MySQL2 is mostly API compatible with [Node MySQL][node-mysql] and supports majority of features. MySQL2 also offers these additional features:
 
- - Faster / Better Performance
- - [Prepared Statements](./documentation/en/Prepared-Statements.md)
- - MySQL Binary Log Protocol
- - [MySQL Server](./documentation/en/MySQL-Server.md)
- - Extended support for Encoding and Collation
- - [Promise Wrapper](./documentation/en/Promise-Wrapper.md)
- - Compression
- - SSL and [Authentication Switch](./documentation/en/Authentication-Switch.md)
- - [Custom Streams](./documentation/en/Extras.md)
- - [Pooling](#using-connection-pools)
+- Faster / Better Performance
+- [Prepared Statements][docs-prepared-statements]
+- MySQL Binary Log Protocol
+- [MySQL Server][docs-mysql-server]
+- Extended support for Encoding and Collation
+- [Promise Wrapper][docs-promise-wrapper]
+- Compression
+- SSL and [Authentication Switch][docs-authentication-switch]
+- [Custom Streams][docs-streams]
+- [Pooling][docs-qs-pooling]
 
 ## Installation
 
@@ -59,235 +82,27 @@ If you are using TypeScript, you will need to install `@types/node`.
 npm install --save-dev @types/node
 ```
 
-> For TypeScript documentation and examples, see [here](./documentation/en/TypeScript-Examples.md).
-
-## First Query
-```js
-// get the client
-const mysql = require('mysql2');
-
-// create the connection to database
-const connection = mysql.createConnection({
-  host: 'localhost',
-  user: 'root',
-  database: 'test'
-});
-
-// simple query
-connection.query(
-  'SELECT * FROM `table` WHERE `name` = "Page" AND `age` > 45',
-  function(err, results, fields) {
-    console.log(results); // results contains rows returned by server
-    console.log(fields); // fields contains extra meta data about results, if available
-  }
-);
-
-// with placeholder
-connection.query(
-  'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
-  ['Page', 45],
-  function(err, results) {
-    console.log(results);
-  }
-);
-```
-
-## Using Prepared Statements
-
-With MySQL2 you also get the prepared statements. With prepared statements MySQL doesn't have to prepare plan for same query every time, this results in better performance. If you don't know why they are important, please check these discussions:
-
-- [How prepared statements can protect from SQL Injection attacks](http://stackoverflow.com/questions/8263371/how-can-prepared-statements-protect-from-sql-injection-attacks)
-
-MySQL2 provides `execute` helper which will prepare and query the statement. You can also manually prepare / unprepare statement with `prepare` / `unprepare` methods.
-
-```js
-// get the client
-const mysql = require('mysql2');
-
-// create the connection to database
-const connection = mysql.createConnection({
-  host: 'localhost',
-  user: 'root',
-  database: 'test'
-});
-
-// execute will internally call prepare and query
-connection.execute(
-  'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
-  ['Rick C-137', 53],
-  function(err, results, fields) {
-    console.log(results); // results contains rows returned by server
-    console.log(fields); // fields contains extra meta data about results, if available
-
-    // If you execute same statement again, it will be picked from a LRU cache
-    // which will save query preparation time and give better performance
-  }
-);
-```
-
-## Using connection pools
-
-Connection pools help reduce the time spent connecting to the MySQL server by reusing a previous connection, leaving them open instead of closing when you are done with them.
-
-This improves the latency of queries as you avoid all of the overhead that comes with establishing a new connection.
-
-```js
-// get the client
-const mysql = require('mysql2');
-
-// Create the connection pool. The pool-specific settings are the defaults
-const pool = mysql.createPool({
-  host: 'localhost',
-  user: 'root',
-  database: 'test',
-  waitForConnections: true,
-  connectionLimit: 10,
-  maxIdle: 10, // max idle connections, the default value is the same as `connectionLimit`
-  idleTimeout: 60000, // idle connections timeout, in milliseconds, the default value 60000
-  queueLimit: 0,
-  enableKeepAlive: true,
-  keepAliveInitialDelay: 0
-});
-```
-The pool does not create all connections upfront but creates them on demand until the connection limit is reached.
-
-You can use the pool in the same way as connections (using `pool.query()` and `pool.execute()`):
-```js
-// For pool initialization, see above
-pool.query("SELECT `field` FROM `table`", function(err, rows, fields) {
-  // Connection is automatically released when query resolves
-});
-```
-
-Alternatively, there is also the possibility of manually acquiring a connection from the pool and returning it later:
-```js
-// For pool initialization, see above
-pool.getConnection(function(err, conn) {
-  // Do something with the connection
-  conn.query(/* ... */);
-  // Don't forget to release the connection when finished!
-  pool.releaseConnection(conn);
-});
-```
-
-## Using Promise Wrapper
-
-MySQL2 also support Promise API. Which works very well with ES7 async await.
-```js
-async function main() {
-  // get the client
-  const mysql = require('mysql2/promise');
-  // create the connection
-  const connection = await mysql.createConnection({host:'localhost', user: 'root', database: 'test'});
-  // query database
-  const [rows, fields] = await connection.execute('SELECT * FROM `table` WHERE `name` = ? AND `age` > ?', ['Morty', 14]);
-}
-```
-
-MySQL2 use default `Promise` object available in scope. But you can choose which `Promise` implementation you want to use.
-```js
-// get the client
-const mysql = require('mysql2/promise');
-
-// get the promise implementation, we will use bluebird
-const bluebird = require('bluebird');
-
-// create the connection, specify bluebird as Promise
-const connection = await mysql.createConnection({host:'localhost', user: 'root', database: 'test', Promise: bluebird});
-
-// query database
-const [rows, fields] = await connection.execute('SELECT * FROM `table` WHERE `name` = ? AND `age` > ?', ['Morty', 14]);
-```
-
-MySQL2 also exposes a .promise() function on Pools, so you can create a promise/non-promise connections from the same pool.
-```js
-async function main() {
-  // get the client
-  const mysql = require('mysql2');
-  // create the pool
-  const pool = mysql.createPool({host:'localhost', user: 'root', database: 'test'});
-  // now get a Promise wrapped instance of that pool
-  const promisePool = pool.promise();
-  // query database using promises
-  const [rows,fields] = await promisePool.query("SELECT 1");
-}
-```
-
-MySQL2 exposes a .promise() function on Connections, to "upgrade" an existing non-promise connection to use promise.
-```js
-// get the client
-const mysql = require('mysql2');
-// create the connection
-const con = mysql.createConnection(
-  {host:'localhost', user: 'root', database: 'test'}
-);
-con.promise().query("SELECT 1")
-  .then( ([rows,fields]) => {
-    console.log(rows);
-  })
-  .catch(console.log)
-  .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 Level
-```js
-const con = mysql.createConnection(
-  { host: 'localhost', database: 'test', user: 'root', rowsAsArray: true }
-);
-```
-
-### Query Level
-```js
-con.query({ sql: 'select 1 as foo, 2 as foo', rowsAsArray: true }, function(err, results, fields) {
-  console.log(results); // in this query, results will be an array of arrays rather than an array of objects
-  console.log(fields); // fields 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.
-
-One known incompatibility is that `DECIMAL` values are returned as strings whereas in [Node MySQL][node-mysql] they are returned as numbers. This includes the result of `SUM()` and `AVG()` functions when applied to `INTEGER` arguments. This is done deliberately to avoid loss of precision - see https://github.com/sidorares/node-mysql2/issues/935.
-
-If you find any other incompatibility with [Node MySQL][node-mysql], Please report via Issue tracker. We will fix reported incompatibility on priority basis.
+> For TypeScript documentation and examples, see [here][docs-typescript-docs].
 
 ## Documentation
 
-You can find more detailed documentation [here](./documentation/en). You should also check various code [examples](./examples) to understand advanced concepts.
+- [Quickstart][docs-base]
+  - [First Query][docs-qs-first-query], [Using Prepared Statements][docs-qs-using-prepared-statements], [Using Connection Pools][docs-qs-pooling] and more.
+- [Documentation][docs-documentation]
+- [Examples][docs-examples]
+- [FAQ][docs-faq]
 
 ## Acknowledgements
 
-  - Internal protocol is written by @sidorares [MySQL-Native](https://github.com/sidorares/nodejs-mysql-native)
-  - Constants, SQL parameters interpolation, Pooling, `ConnectionConfig` class taken from [node-mysql](https://github.com/mysqljs/mysql)
-  - SSL upgrade code based on @TooTallNate [code](https://gist.github.com/TooTallNate/848444)
-  - Secure connection / compressed connection api flags compatible to [MariaSQL](https://github.com/mscdex/node-mariasql/) client.
-  - [Contributors](https://github.com/sidorares/node-mysql2/graphs/contributors)
+- Internal protocol is written by [@sidorares][sidorares] [MySQL-Native][mysql-native].
+- Constants, SQL parameters interpolation, Pooling, `ConnectionConfig` class taken from [Node MySQL][node-mysql].
+- SSL upgrade code based on [@TooTallNate][TooTallNate] [code][starttls.js].
+- Secure connection / compressed connection api flags compatible to [MariaSQL][node-mariasql] client.
+- [Contributors][contributors].
 
 ## Contributing
 
-Want to improve something in `node-mysql2`. Please check [Contributing.md](https://github.com/sidorares/node-mysql2/blob/master/Contributing.md) for detailed instruction on how to get started.
+Want to improve something in **MySQL2**?  
+Please check [Contributing.md][contributing] for detailed instruction on how to get started.
 
-
-[npm-image]: https://img.shields.io/npm/v/mysql2.svg
-[npm-url]: https://npmjs.org/package/mysql2
-[node-version-image]: http://img.shields.io/node/v/mysql2.svg
-[node-version-url]: http://nodejs.org/download/
-[travis-image]: https://img.shields.io/travis/sidorares/node-mysql2/master.svg?label=linux
-[travis-url]: https://travis-ci.org/sidorares/node-mysql2
-[appveyor-image]: https://img.shields.io/appveyor/ci/sidorares/node-mysql2/master.svg?label=windows
-[appveyor-url]: https://ci.appveyor.com/project/sidorares/node-mysql2
-[downloads-image]: https://img.shields.io/npm/dm/mysql2.svg
-[downloads-url]: https://npmjs.org/package/mysql2
-[license-url]: https://github.com/sidorares/node-mysql2/blob/master/License
-[license-image]: https://img.shields.io/npm/l/mysql2.svg?maxAge=2592000
-[node-mysql]: https://github.com/mysqljs/mysql
-[mysql-native]: https://github.com/sidorares/nodejs-mysql-native
+To contribute in **MySQL2 Documentation**, please visit the [Website Contributing Guidelines][docs-contributing] for detailed instruction on how to get started.

package/lib/commands/query.js

@@ -37,7 +37,7 @@ class Query extends Command {
 
   then() {
     const err =
-      "You have tried to call .then(), .catch(), or invoked await on the result of query that is not a promise, which is a programming error. Try calling con.promise().query(), or require('mysql2/promise') instead of 'mysql2' for a promise-compatible version of the query interface. To learn how to use async/await or Promises check out documentation at https://www.npmjs.com/package/mysql2#using-promise-wrapper, or the mysql2 documentation at https://github.com/sidorares/node-mysql2/tree/master/documentation/en/Promise-Wrapper.md";
+      "You have tried to call .then(), .catch(), or invoked await on the result of query that is not a promise, which is a programming error. Try calling con.promise().query(), or require('mysql2/promise') instead of 'mysql2' for a promise-compatible version of the query interface. To learn how to use async/await or Promises check out documentation at https://sidorares.github.io/node-mysql2/docs#using-promise-wrapper, or the mysql2 documentation at https://sidorares.github.io/node-mysql2/docs/documentation/promise-wrapper";
     // eslint-disable-next-line
     console.log(err);
     throw new Error(err);

package/lib/connection_config.js

@@ -260,11 +260,11 @@ class ConnectionConfig {
   static parseUrl(url) {
     const parsedUrl = new URL(url);
     const options = {
-      host: parsedUrl.hostname,
+      host: decodeURIComponent(parsedUrl.hostname),
       port: parseInt(parsedUrl.port, 10),
-      database: parsedUrl.pathname.slice(1),
-      user: parsedUrl.username,
-      password: parsedUrl.password
+      database: decodeURIComponent(parsedUrl.pathname.slice(1)),
+      user: decodeURIComponent(parsedUrl.username),
+      password: decodeURIComponent(parsedUrl.password),
     };
     parsedUrl.searchParams.forEach((value, key) => {
       try {

package/package.json

@@ -1,23 +1,20 @@
 {
   "name": "mysql2",
-  "version": "3.6.4",
+  "version": "3.7.0",
   "description": "fast mysql driver. Implements core protocol, prepared statements, ssl and compression in native JS",
   "main": "index.js",
-  "directories": {
-    "example": "examples"
-  },
   "typings": "typings/mysql/index",
   "scripts": {
     "lint": "npm run lint:docs && npm run lint:code",
     "lint:code": "eslint index.js promise.js index.d.ts promise.d.ts \"typings/**/*.ts\" \"lib/**/*.js\" \"test/**/*.{js,ts}\" \"benchmarks/**/*.js\"",
-    "lint:docs": "eslint Contributing.md README.md \"documentation/**/*.md\" \"examples/*.js\"",
+    "lint:docs": "eslint Contributing.md README.md",
     "test": "node ./test/run.js",
     "test:builtin-node-runner": "NODE_V8_COVERAGE=./coverage node --test --experimental-test-coverage test/builtin-runner",
     "test:tsc-build": "cd \"test/tsc-build\" && npx tsc -p \"tsconfig.json\"",
     "coverage-test": "c8 -r cobertura -r lcov -r text node ./test/run.js",
     "benchmark": "node ./benchmarks/benchmark.js",
-    "prettier": "prettier --single-quote --trailing-comma none --write \"{lib,examples,test}/**/*.js\"",
-    "prettier:docs": "prettier --single-quote --trailing-comma none --write README.md documentation/*",
+    "prettier": "prettier --single-quote --trailing-comma none --write \"{lib,test}/**/*.js\"",
+    "prettier:docs": "prettier --single-quote --trailing-comma none --write README.md",
     "precommit": "lint-staged",
     "eslint-check": "eslint --print-config .eslintrc | eslint-config-prettier-check",
     "wait-port": "wait-on"
@@ -32,6 +29,7 @@
     "type": "git",
     "url": "https://github.com/sidorares/node-mysql2"
   },
+  "homepage": "https://sidorares.github.io/node-mysql2/docs",
   "keywords": [
     "mysql",
     "client",