Skip to content

Commit bee36c1

Browse files
sushantdhimansushantdhiman
committed
document updates
1 parent 626bb62 commit bee36c1

File tree

5 files changed

+129
-133
lines changed

5 files changed

+129
-133
lines changed

‎README.md

Lines changed: 0 additions & 128 deletions
Original file line numberDiff line numberDiff line change
@@ -24,99 +24,6 @@ MySql client for node.js. Written in native JavaScript and aims to be mostly api
2424
## Documentation
2525

2626

27-
28-
### Promise wrappers
29-
30-
In addition to errback interface there is thin wrapper to expose Promise-based api
31-
32-
```js
33-
var mysql = require('mysql2/promise'); // or require('mysql2').createConnectionPromise
34-
mysql.createConnection({ /* same parameters as for non-promise createConnection */ })
35-
.then((conn) => conn.query('select foo from bar'))
36-
.then(([rows, fields]) => console.log(rows[0].foo))
37-
```
38-
39-
```js
40-
var pool = require('mysql2/promise').createPool({}); // or mysql.createPoolPromise({})
41-
pool.getConnection()
42-
.then((conn) => {
43-
var res = conn.query('select foo from bar');
44-
conn.release();
45-
return res;
46-
}).then( (result) => {
47-
console.log(res[0][0].foo);
48-
}).catch( (err) => {
49-
console.log(err); // any of connection time or query time errors from above
50-
});
51-
52-
```
53-
es7 async/await:
54-
55-
```js
56-
let mysql = require('mysql2/promise');
57-
let conn = await mysql.createConnection({ database: test });
58-
let [rows, fields] = await conn.execute('select ?+? as sum', [2, 2]);
59-
```
60-
61-
```js
62-
let mysql = require('mysql2/promise');
63-
let pool = mysql.createPool({ database: test });
64-
// execute in parallel, next console.log in 3 seconds
65-
await Promise.all([pool.query('select sleep(2)'), pool.query('select sleep(3)')]);
66-
console.log('3 seconds after');
67-
await pool.end();
68-
await conn.end();
69-
```
70-
71-
[co](https://github.com/tj/co) library:
72-
73-
```js
74-
var mysql = require('mysql2');
75-
var co = require('co')
76-
co(function * () {
77-
var c = yield mysql.createConnectionPromise({ user: 'root', namedPlaceholders: true });
78-
var rows = yield c.query('show databases');
79-
console.log(rows)
80-
console.log( yield c.execute('select 1+:toAdd as qqq', {toAdd: 10}) );
81-
yield c.end();
82-
})
83-
```
84-
see examples in [/examples/promise-co-await](/examples/promise-co-await)
85-
86-
### Authentication switch request
87-
88-
During connection phase the server may ask client to switch to a different auth method.
89-
If `authSwitchHandler` connection config option is set it must be a function that receive
90-
switch request data and respond via callback. Note that if `mysql_native_password` method is
91-
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
92-
`authSwitchHandler` won't be invoked. `authSwitchHandler` MAY be called multiple times if
93-
plugin algorithm requires multiple roundtrips of data exchange between client and server.
94-
First invocation always has `({pluginName, pluginData})` signature, following calls - `({pluginData})`.
95-
The client respond with opaque blob matching requested plugin via `callback(null, data: Buffer)`.
96-
97-
Example: (imaginary `ssh-key-auth` plugin) pseudo code
98-
99-
```js
100-
var conn = mysql.createConnection({
101-
user: 'test_user',
102-
password: 'test',
103-
database: 'test_database',
104-
authSwitchHandler: function(data, cb) {
105-
if (data.pluginName === 'ssh-key-auth') {
106-
getPrivateKey((key) => {
107-
var response = encrypt(key, data.pluginData);
108-
// continue handshake by sending response data
109-
// respond with error to propagate error to connect/changeUser handlers
110-
cb(null, response);
111-
})
112-
}
113-
}
114-
});
115-
```
116-
117-
Initial handshake always performed using `mysql_native_password` plugin. This will be possible to override in
118-
the future versions.
119-
12027
### Named placeholders
12128

12229
You can use named placeholders for parameters by setting `namedPlaceholders` config value or query/execute time option. Named placeholders are converted to unnamed `?` on the client (mysql protocol does not support named parameters). If you reference parameter multiple times under the same name it is sent to server multiple times.
@@ -137,41 +44,6 @@ You can use named placeholders for parameters by setting `namedPlaceholders` con
13744
});
13845
```
13946

140-
### Prepared statements
141-
142-
#### Automatic creation, cached and re-used by connection
143-
144-
Similar to `connection.query()`.
145-
146-
```js
147-
connection.execute('select 1 + ? + ? as result', [5, 6], function(err, rows) {
148-
// rows: [ { result: 12 } ]
149-
// internally 'select 1 + ? + ? as result' is prepared first. On subsequent calls cached statement is re-used
150-
});
151-
152-
// close cached statement for 'select 1 + ? + ? as result'. noop if not in cache
153-
connection.unprepare('select 1 + ? + ? as result');
154-
```
155-
156-
#### Manual prepare / execute
157-
158-
```js
159-
connection.prepare('select ? + ? as tests', function(err, statement) {
160-
// statement.parameters - array of column definitions, length === number of params, here 2
161-
// statement.columns - array of result column definitions. Can be empty if result schema is dynamic / not known
162-
// statement.id
163-
// statement.query
164-
165-
statement.execute([1, 2], function(err, rows, columns) {
166-
// -> [ { tests: 3 } ]
167-
});
168-
169-
// note that there is no callback here. There is no statement close ack at protocol level.
170-
statement.close();
171-
});
172-
```
173-
Note that you should not use statement after connection reset (`changeUser()` or disconnect). Statement scope is connection, you need to prepare statement for each new connection in order to use it.
174-
17547
### Receiving rows as array of columns instead of hash with column name as key:
17648

17749
```js

‎documentation/Authentication-Switch.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Authentication switch request
2+
3+
During connection phase the server may ask client to switch to a different auth method.
4+
If `authSwitchHandler` connection config option is set it must be a function that receive
5+
switch request data and respond via callback. Note that if `mysql_native_password` method is
6+
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
7+
`authSwitchHandler` won't be invoked. `authSwitchHandler` MAY be called multiple times if
8+
plugin algorithm requires multiple roundtrips of data exchange between client and server.
9+
First invocation always has `({pluginName, pluginData})` signature, following calls - `({pluginData})`.
10+
The client respond with opaque blob matching requested plugin via `callback(null, data: Buffer)`.
11+
12+
Example: (imaginary `ssh-key-auth` plugin) pseudo code
13+
14+
```js
15+
var conn = mysql.createConnection({
16+
user: 'test_user',
17+
password: 'test',
18+
database: 'test_database',
19+
authSwitchHandler: function(data, cb) {
20+
if (data.pluginName === 'ssh-key-auth') {
21+
getPrivateKey((key) => {
22+
var response = encrypt(key, data.pluginData);
23+
// continue handshake by sending response data
24+
// respond with error to propagate error to connect/changeUser handlers
25+
cb(null, response);
26+
})
27+
}
28+
}
29+
});
30+
```
31+
32+
Initial handshake always performed using `mysql_native_password` plugin. This will be possible to override in the future versions.

‎documentation/Prepared-Statements.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Prepared statements
2+
3+
## Automatic creation, cached and re-used by connection
4+
5+
Similar to `connection.query()`.
6+
7+
```js
8+
connection.execute('select 1 + ? + ? as result', [5, 6], function(err, rows) {
9+
// rows: [ { result: 12 } ]
10+
// internally 'select 1 + ? + ? as result' is prepared first. On subsequent calls cached statement is re-used
11+
});
12+
13+
// close cached statement for 'select 1 + ? + ? as result'. noop if not in cache
14+
connection.unprepare('select 1 + ? + ? as result');
15+
```
16+
17+
## Manual prepare / execute
18+
19+
```js
20+
connection.prepare('select ? + ? as tests', function(err, statement) {
21+
// statement.parameters - array of column definitions, length === number of params, here 2
22+
// statement.columns - array of result column definitions. Can be empty if result schema is dynamic / not known
23+
// statement.id
24+
// statement.query
25+
26+
statement.execute([1, 2], function(err, rows, columns) {
27+
// -> [ { tests: 3 } ]
28+
});
29+
30+
// note that there is no callback here. There is no statement close ack at protocol level.
31+
statement.close();
32+
});
33+
```
34+
Note that you should not use statement after connection reset (`changeUser()` or disconnect). Statement scope is connection, you need to prepare statement for each new connection in order to use it.

‎documentation/Promise-Wrapper.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Promise wrappers
2+
3+
In addition to errback interface there is thin wrapper to expose Promise-based api
4+
5+
## Basic Promise
6+
7+
```js
8+
var mysql = require('mysql2/promise'); // or require('mysql2').createConnectionPromise
9+
mysql.createConnection({ /* same parameters as for non-promise createConnection */ })
10+
.then((conn) => conn.query('select foo from bar'))
11+
.then(([rows, fields]) => console.log(rows[0].foo))
12+
```
13+
14+
```js
15+
var pool = require('mysql2/promise').createPool({}); // or mysql.createPoolPromise({})
16+
pool.getConnection()
17+
.then((conn) => {
18+
var res = conn.query('select foo from bar');
19+
conn.release();
20+
return res;
21+
}).then( (result) => {
22+
console.log(res[0][0].foo);
23+
}).catch( (err) => {
24+
console.log(err); // any of connection time or query time errors from above
25+
});
26+
27+
```
28+
## ES7 Async Await
29+
30+
```js
31+
let mysql = require('mysql2/promise');
32+
let conn = await mysql.createConnection({ database: test });
33+
let [rows, fields] = await conn.execute('select ?+? as sum', [2, 2]);
34+
```
35+
36+
```js
37+
let mysql = require('mysql2/promise');
38+
let pool = mysql.createPool({ database: test });
39+
// execute in parallel, next console.log in 3 seconds
40+
await Promise.all([pool.query('select sleep(2)'), pool.query('select sleep(3)')]);
41+
console.log('3 seconds after');
42+
await pool.end();
43+
await conn.end();
44+
```
45+
46+
## With [CO](https://github.com/tj/co)
47+
48+
```js
49+
var mysql = require('mysql2');
50+
var co = require('co')
51+
co(function * () {
52+
var c = yield mysql.createConnectionPromise({ user: 'root', namedPlaceholders: true });
53+
var rows = yield c.query('show databases');
54+
console.log(rows)
55+
console.log( yield c.execute('select 1+:toAdd as qqq', {toAdd: 10}) );
56+
yield c.end();
57+
})
58+
```
59+
Examples in [/examples/promise-co-await](https://github.com/sidorares/node-mysql2/tree/master/examples/promise-co-await)

‎documentation/Readme.md

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,13 @@
1-
### Documentation
1+
# Documentation
22

33
`Node-MySQL2` is aims to be a drop in replacement for [node-mysql](https://github.com/felixge/node-mysql). Please check `node-mysql` for full documentation.
44

55
**Note :** *If you see any API incompatibilities with `node-mysql`, please report via github issue.*
66

77
Not only `Node-MySQL2` offer a better performance over `node-mysql`, we also support these features.
88

9-
- [Prepared Statements]()
10-
- [Promise Wrapper]()
11-
- [Authentication Switch]()
12-
- [Named Placeholders]()
9+
- [Prepared Statements](https://github.com/sidorares/node-mysql2/tree/master/documentation/Prepared-Statements.md)
10+
- [Promise Wrapper](https://github.com/sidorares/node-mysql2/tree/master/documentation/Promise-Wrapper.md)
11+
- [Authentication Switch](https://github.com/sidorares/node-mysql2/tree/master/documentation/Authentication-Switch.md)
1312
- [MySQL Server]()
1413
- [Other Features]()

0 commit comments

Comments
 (0)