-
Notifications
You must be signed in to change notification settings - Fork 1
/
readme-template.md.hbs
75 lines (65 loc) · 2.59 KB
/
readme-template.md.hbs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
# Promise Pool [![Build Status][1]][2] [![Coverage Status][3]][4]
Promise-based connection pooling library inspired by generic-pool.
## Installation
```sh
$ npm install generic-promise-pool
```
## Documentation
The full generated [JSDoc](http://usejsdoc.org/) documentation is hosted on GitHub here:
https://NatalieWolfe.github.io/node-promise-pool/docs/. You can also find the documentation as a
single markdown file at `docs.md`. All of the [options used for configuring](#pool-factory-options)
a pool are at the end of this README.
## Examples
### Creating a Pool
This example creates a pool that uses a hypothetical promise-based MySQL library.
```js
var mysql = require('promise-mysql');
var pool = require('generic-promise-pool');
var mysqlPool = pool.create({
name : 'mysql', // An optional name for the pool.
max : 10, // Optional limit for how many connections to allow.
min : 2, // Optional minimum connections to keep in the pool.
create : function(){
var conn = mysql.createConnection(mysqlConnOptions);
return conn.connect();
},
destroy : function(conn){
return conn.end();
}
});
```
For a full list of options that the `PromisePool` accepts, see the documentation on GitHub:
https://NatalieWolfe.github.io/node-promise-pool/docs/PromisePool.Factory.html
### Using the Pool
In this example we get a connection from the pool and use it to make a query.
```js
mysqlPool.acquire(function(conn){
// The connection remains acquired until the promise returned by this
// function is resolved or rejected.
return conn.query('SELECT * FROM books WHERE author = "Neal Stephenson"');
}).then(function(res){
// The connection has been released back to the pool before we get here,
// and the results from the acquire callback is propagated out.
res.forEach(function(row){ console.dir(row); });
}, function(err){
console.error(err);
});
```
### Draining the Pool
When you want to shut down your application, it can be quite annoying to wait for idle connections
to close naturally. To get past this, drain the pool before shutting down.
```js
mysqlPool.drain()
.then(function(){
console.log('The pool has drained, and all connections destroyed.');
});
```
## Pool Factory Options
{{#namespace name="Factory"}}
{{>properties~}}
{{>members~}}
{{/namespace}}
[1]: https://travis-ci.org/NatalieWolfe/node-promise-pool.svg?branch=master
[2]: https://travis-ci.org/NatalieWolfe/node-promise-pool
[3]: https://coveralls.io/repos/NatalieWolfe/node-promise-pool/badge.svg
[4]: https://coveralls.io/r/NatalieWolfe/node-promise-pool