Merge pull request #1493 from xWTF/master

fix(typing & documentation): prepared statements usage

Author: sidorares

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();
 });

promise.d.ts

@@ -62,7 +62,8 @@ export interface Connection extends EventEmitter {
     values: any | any[] | { [param: string]: any }
   ): Promise<[T, FieldPacket[]]>;
 
-  unprepare(sql: string): void;
+  prepare(options: string | QueryOptions): Promise<PreparedStatementInfo>;
+  unprepare(sql: string | QueryOptions): void;
 
   end(options?: any): Promise<void>;
 
@@ -137,3 +138,8 @@ export function createConnection(
   config: ConnectionOptions
 ): Promise<Connection>;
 export function createPool(config: PoolOptions): Pool;
+
+export interface PreparedStatementInfo {
+  close(): Promise<void>;
+  execute(parameters: any[]): Promise<[RowDataPacket[][] | RowDataPacket[] | OkPacket | OkPacket[] | ResultSetHeader, FieldPacket[]]>;
+}