mysql2 3.3.3 → 3.3.4

package/README.md

@@ -8,9 +8,9 @@
 [![Windows Build][appveyor-image]][appveyor-url]
 [![License][license-image]][license-url]  
 
-English | [简体中文](./documentation_zh-cn/)
+English | [简体中文](./documentation/zh-cn/) | [Português (BR)](./documentation/pt-br/)
 
-> 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)
+> MySQL client for Node.js with focus on performance. Supports prepared statements, non-utf8 encodings, binary log protocol, compression, ssl [much more](./documentation/en).
 
 __Table of contents__
 
@@ -20,6 +20,9 @@ __Table of contents__
   - [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)
@@ -29,17 +32,17 @@ __Table of contents__
 
 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 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 [mysqljs][node-mysql] and supports majority of features. MySQL2 also offers these additional features:
 
  - Faster / Better Performance
- - [Prepared Statements](https://github.com/sidorares/node-mysql2/tree/master/documentation/Prepared-Statements.md)
+ - [Prepared Statements](./documentation/en/Prepared-Statements.md)
  - MySQL Binary Log Protocol
- - [MySQL Server](https://github.com/sidorares/node-mysql2/tree/master/documentation/MySQL-Server.md)
+ - [MySQL Server](./documentation/en/MySQL-Server.md)
  - Extended support for Encoding and Collation
- - [Promise Wrapper](https://github.com/sidorares/node-mysql2/tree/master/documentation/Promise-Wrapper.md)
+ - [Promise Wrapper](./documentation/en/Promise-Wrapper.md)
  - Compression
- - SSL and [Authentication Switch](https://github.com/sidorares/node-mysql2/tree/master/documentation/Authentication-Switch.md)
- - [Custom Streams](https://github.com/sidorares/node-mysql2/tree/master/documentation/Extras.md)
+ - SSL and [Authentication Switch](./documentation/en/Authentication-Switch.md)
+ - [Custom Streams](./documentation/en/Extras.md)
  - [Pooling](#using-connection-pools)
 
 ## Installation
@@ -51,7 +54,6 @@ npm install --save mysql2
 ```
 
 ## First Query
-
 ```js
 // get the client
 const mysql = require('mysql2');
@@ -84,11 +86,11 @@ connection.query(
 
 ## Using Prepared Statements
 
-With MySQL2 you also get the prepared statements. With prepared statements MySQL doesn't have to prepare plan for same query everytime, this results in better performance. If you don't know why they are important, please check these discussions
+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)
 
-MySQL provides `execute` helper which will prepare and query the statement. You can also manually prepare / unprepare statement with `prepare` / `unprepare` methods.
+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
@@ -144,27 +146,25 @@ The pool does not create all connections upfront but creates them on demand unti
 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 atable", function(err, rows, fields) {
-   // Connection is automatically released when query resolves
-})
+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);
-})
+  // 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.
-
-<!--eslint-disable-next-block-->
 ```js
 async function main() {
   // get the client
@@ -176,9 +176,7 @@ async function main() {
 }
 ```
 
-MySQL2 use default `Promise` object available in scope. But you can choose which `Promise` implementation you want to use
-
-<!--eslint-disable-next-block-->
+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');
@@ -193,7 +191,7 @@ const connection = await mysql.createConnection({host:'localhost', user: 'root',
 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
+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
@@ -204,9 +202,10 @@ async function main() {
   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
+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');
@@ -222,7 +221,7 @@ con.promise().query("SELECT 1")
   .then( () => con.end());
 ```
 
-## Array results
+## 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.
 
@@ -230,22 +229,19 @@ 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
+### Connection Level
 ```js
 const con = mysql.createConnection(
   { host: 'localhost', database: 'test', user: 'root', rowsAsArray: true }
 );
-
 ```
 
-### Query Option
-
+### Query Level
 ```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
+  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
@@ -258,7 +254,7 @@ If you find any other incompatibility with [Node MySQL][node-mysql], Please repo
 
 ## Documentation
 
-You can find more detailed documentation [here](https://github.com/sidorares/node-mysql2/tree/master/documentation). You should also check various code [examples](https://github.com/sidorares/node-mysql2/tree/master/examples) to understand advanced concepts.
+You can find more detailed documentation [here](./documentation/en). You should also check various code [examples](./examples) to understand advanced concepts.
 
 ## Acknowledgements
 

package/index.d.ts

@@ -1,5 +1,6 @@
 import {
   Connection as PromiseConnection,
+  Pool as PromisePool,
   PoolConnection as PromisePoolConnection,
 } from './promise';
 
@@ -83,7 +84,7 @@ export interface Connection extends mysql.Connection {
 }
 
 export interface PoolConnection extends mysql.PoolConnection {
-  promise(promiseImpl?: PromiseConstructor): PromisePoolConnection;
+  promise(promiseImpl?: PromiseConstructor): PromisePool;
 }
 
 export interface Pool extends mysql.Connection {
@@ -152,13 +153,14 @@ export interface Pool extends mysql.Connection {
   getConnection(
     callback: (err: NodeJS.ErrnoException, connection: PoolConnection) => any
   ): void;
+  releaseConnection(connection: PoolConnection | PromisePoolConnection): void;
   on(event: 'connection', listener: (connection: PoolConnection) => any): this;
   on(event: 'acquire', listener: (connection: PoolConnection) => any): this;
   on(event: 'release', listener: (connection: PoolConnection) => any): this;
   on(event: 'enqueue', listener: () => any): this;
   unprepare(sql: string): mysql.PrepareStatementInfo;
   prepare(sql: string, callback?: (err: mysql.QueryError | null, statement: mysql.PrepareStatementInfo) => any): mysql.Prepare;
-  promise(promiseImpl?: PromiseConstructor): PromisePoolConnection;
+  promise(promiseImpl?: PromiseConstructor): PromisePool;
   config: mysql.PoolOptions;
 }
 

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/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://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";
     // eslint-disable-next-line
     console.log(err);
     throw new Error(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mysql2",
-  "version": "3.3.3",
+  "version": "3.3.4",
   "description": "fast mysql driver. Implements core protocol, prepared statements, ssl and compression in native JS",
   "main": "index.js",
   "directories": {
@@ -10,7 +10,7 @@
   "scripts": {
     "lint": "npm run lint:docs && npm run lint:code",
     "lint:code": "eslint index.js promise.js \"lib/**/*.js\" \"test/**/*.js\" \"benchmarks/**/*.js\"",
-    "lint:docs": "eslint Contributing.md \"documentation/**/*.md\" \"examples/*.js\"",
+    "lint:docs": "eslint Contributing.md README.md \"documentation/**/*.md\" \"examples/*.js\"",
     "test": "node ./test/run.js",
     "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",

package/promise.d.ts

@@ -83,12 +83,11 @@ export interface Connection extends EventEmitter {
 }
 
 export interface PoolConnection extends Connection {
-  connection: Connection;
-  getConnection(): Promise<PoolConnection>;
   release(): void;
+  connection: Connection;
 }
 
-export interface Pool extends EventEmitter {
+export interface Pool extends EventEmitter, Connection {
   query<T extends RowDataPacket[][] | RowDataPacket[] | OkPacket | OkPacket[] | ResultSetHeader>(
     sql: string
   ): Promise<[T, FieldPacket[]]>;
@@ -128,6 +127,7 @@ export interface Pool extends EventEmitter {
   ): Promise<[T, FieldPacket[]]>;
 
   getConnection(): Promise<PoolConnection>;
+  releaseConnection(connection: PoolConnection): void;
   on(event: 'connection', listener: (connection: PoolConnection) => any): this;
   on(event: 'acquire', listener: (connection: PoolConnection) => any): this;
   on(event: 'release', listener: (connection: PoolConnection) => any): this;
@@ -138,7 +138,7 @@ export interface Pool extends EventEmitter {
   escapeId(value: string): string;
   escapeId(values: string[]): string;
   format(sql: string, values?: any | any[] | { [param: string]: any }): string;
-
+  
   pool: CorePool;
 }
 
@@ -153,4 +153,3 @@ export interface PreparedStatementInfo {
   close(): Promise<void>;
   execute(parameters: any[]): Promise<[RowDataPacket[][] | RowDataPacket[] | OkPacket | OkPacket[] | ResultSetHeader, FieldPacket[]]>;
 }
-

package/promise.js

@@ -346,6 +346,10 @@ class PromisePool extends EventEmitter {
     });
   }
 
+  releaseConnection(connection) {
+    if (connection instanceof PromisePoolConnection) connection.release();
+  }
+
   query(sql, args) {
     const corePool = this.pool;
     const localErr = new Error();

package/typings/mysql/lib/Pool.d.ts

@@ -61,6 +61,8 @@ declare class Pool extends EventEmitter {
 
     getConnection(callback: (err: NodeJS.ErrnoException | null, connection: PoolConnection) => any): void;
 
+    releaseConnection(connection: PoolConnection): void;
+
     query<T extends RowDataPacket[][] | RowDataPacket[] | OkPacket | OkPacket[] | ResultSetHeader>(sql: string, callback?: (err: Query.QueryError | null, result: T, fields: FieldPacket[]) => any): Query;
     query<T extends RowDataPacket[][] | RowDataPacket[] | OkPacket | OkPacket[] | ResultSetHeader>(sql: string, values: any | any[] | { [param: string]: any }, callback?: (err: Query.QueryError | null, result: T, fields: FieldPacket[]) => any): Query;
     query<T extends RowDataPacket[][] | RowDataPacket[] | OkPacket | OkPacket[] | ResultSetHeader>(options: Query.QueryOptions, callback?: (err: Query.QueryError | null, result: T, fields?: FieldPacket[]) => any): Query;