Skip to content

Commit a867233

Browse files
sushantdhimansushantdhiman
committed
extra docs
1 parent bee36c1 commit a867233

File tree

3 files changed

+84
-84
lines changed

3 files changed

+84
-84
lines changed

‎README.md

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

2626

27-
### Named placeholders
28-
29-
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.
30-
31-
```js
32-
connection.config.namedPlaceholders = true;
33-
connection.execute('select :x + :y as z', { x: 1, y: 2}, function(err, rows) {
34-
// statement prepared as "select ? + ? as z" and executed with [1,2] values
35-
// rows returned: [ { z: 3 } ]
36-
});
37-
38-
connection.execute('select :x + :x as z', { x: 1 }, function(err, rows) {
39-
// select ? + ? as z, execute with [1, 1]
40-
});
41-
42-
connection.query('select :x + :x as z', { x: 1 }, function(err, rows) {
43-
// query select 1 + 1 as z
44-
});
45-
```
46-
47-
### Receiving rows as array of columns instead of hash with column name as key:
48-
49-
```js
50-
var options = {sql: 'select A,B,C,D from foo', rowsAsArray: true};
51-
connection.query(options, function(err, results) {
52-
/* results will be an array of arrays like this now:
53-
[[
54-
'field A value',
55-
'field B value',
56-
'field C value',
57-
'field D value',
58-
], ...]
59-
*/
60-
});
61-
```
62-
63-
### Sending tabular data with 'load infile' and local stream:
64-
65-
In addition to sending local fs files you can send any stream using `infileStreamFactory` query option. If set, it has to be a function that return a readable stream. It gets file path from query as a parameter.
66-
67-
```js
68-
// local file
69-
connection.query('LOAD DATA LOCAL INFILE "/tmp/data.csv" INTO TABLE test FIELDS TERMINATED BY ? (id, title)', onInserted1);
70-
// local stream
71-
var sql = 'LOAD DATA LOCAL INFILE "mystream" INTO TABLE test FIELDS TERMINATED BY ? (id, title)';
72-
connection.query({
73-
sql: sql,
74-
infileStreamFactory: function(path) { return getStream(); }
75-
}, onInserted2);
76-
```
77-
78-
### Connecting using custom stream:
79-
80-
```js
81-
var net = require('net');
82-
var mysql = require('mysql2');
83-
var shape = require('shaper');
84-
var connection = mysql.createConnection({
85-
user: 'test',
86-
database: 'test',
87-
stream: net.connect('/tmp/mysql.sock').pipe(shape(10)) // emulate 10 bytes/sec link
88-
});
89-
connection.query('SELECT 1+1 as test1', console.log);
90-
```
91-
`stream` also can be a function. In that case function result has to be duplex stream, and it is used for connection transport. This is required if you connect pool using custom transport as new pooled connection needs new stream. [Example](https://github.com/sidorares/node-mysql2/issues/80) connecting over socks5 proxy:
92-
93-
```js
94-
var mysql = require('mysql2');
95-
var SocksConnection = require('socksjs');
96-
var pool = mysql.createPool({
97-
database: 'test',
98-
user: 'foo',
99-
password: 'bar'
100-
stream: function(cb) {
101-
cb(null, new SocksConnection({ host: 'remote.host', port: 3306}, { host: 'localhost', port: 1080 }));
102-
}
103-
});
104-
```
105-
106-
In addition to password `createConnection()`, `createPool()` and `changeUser()` accept `passwordSha1` option. This is useful when implementing proxies as plaintext password might be not available.
107-
10827
## Known incompatibilities with node-mysql
10928

11029
In contrast to node-mysql, `zeroFill` flag is ignored in type conversion.

‎documentation/Extras.md

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Extra Features
2+
3+
## Named placeholders
4+
5+
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.
6+
7+
```js
8+
connection.config.namedPlaceholders = true;
9+
connection.execute('select :x + :y as z', { x: 1, y: 2}, function(err, rows) {
10+
// statement prepared as "select ? + ? as z" and executed with [1,2] values
11+
// rows returned: [ { z: 3 } ]
12+
});
13+
14+
connection.execute('select :x + :x as z', { x: 1 }, function(err, rows) {
15+
// select ? + ? as z, execute with [1, 1]
16+
});
17+
18+
connection.query('select :x + :x as z', { x: 1 }, function(err, rows) {
19+
// query select 1 + 1 as z
20+
});
21+
```
22+
23+
## Receiving rows as array of columns instead of hash with column name as key:
24+
25+
```js
26+
var options = {sql: 'select A,B,C,D from foo', rowsAsArray: true};
27+
connection.query(options, function(err, results) {
28+
/* results will be an array of arrays like this now:
29+
[[
30+
'field A value',
31+
'field B value',
32+
'field C value',
33+
'field D value',
34+
], ...]
35+
*/
36+
});
37+
```
38+
39+
## Sending tabular data with 'load infile' and local stream:
40+
41+
In addition to sending local fs files you can send any stream using `infileStreamFactory` query option. If set, it has to be a function that return a readable stream. It gets file path from query as a parameter.
42+
43+
```js
44+
// local file
45+
connection.query('LOAD DATA LOCAL INFILE "/tmp/data.csv" INTO TABLE test FIELDS TERMINATED BY ? (id, title)', onInserted1);
46+
// local stream
47+
var sql = 'LOAD DATA LOCAL INFILE "mystream" INTO TABLE test FIELDS TERMINATED BY ? (id, title)';
48+
connection.query({
49+
sql: sql,
50+
infileStreamFactory: function(path) { return getStream(); }
51+
}, onInserted2);
52+
```
53+
54+
## Connecting using custom stream:
55+
56+
```js
57+
var net = require('net');
58+
var mysql = require('mysql2');
59+
var shape = require('shaper');
60+
var connection = mysql.createConnection({
61+
user: 'test',
62+
database: 'test',
63+
stream: net.connect('/tmp/mysql.sock').pipe(shape(10)) // emulate 10 bytes/sec link
64+
});
65+
connection.query('SELECT 1+1 as test1', console.log);
66+
```
67+
`stream` also can be a function. In that case function result has to be duplex stream, and it is used for connection transport. This is required if you connect pool using custom transport as new pooled connection needs new stream. [Example](https://github.com/sidorares/node-mysql2/issues/80) connecting over socks5 proxy:
68+
69+
```js
70+
var mysql = require('mysql2');
71+
var SocksConnection = require('socksjs');
72+
var pool = mysql.createPool({
73+
database: 'test',
74+
user: 'foo',
75+
password: 'bar'
76+
stream: function(cb) {
77+
cb(null, new SocksConnection({ host: 'remote.host', port: 3306}, { host: 'localhost', port: 1080 }));
78+
}
79+
});
80+
```
81+
82+
In addition to password `createConnection()`, `createPool()` and `changeUser()` accept `passwordSha1` option. This is useful when implementing proxies as plaintext password might be not available.

‎documentation/Readme.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,9 @@
44

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

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

99
- [Prepared Statements](https://github.com/sidorares/node-mysql2/tree/master/documentation/Prepared-Statements.md)
1010
- [Promise Wrapper](https://github.com/sidorares/node-mysql2/tree/master/documentation/Promise-Wrapper.md)
1111
- [Authentication Switch](https://github.com/sidorares/node-mysql2/tree/master/documentation/Authentication-Switch.md)
12-
- [MySQL Server]()
13-
- [Other Features]()
12+
- [Extra Features](https://github.com/sidorares/node-mysql2/tree/master/documentation/Extras.md)

0 commit comments

Comments
 (0)