Skip to content

Commit 5c88bd6

Browse files
committed
Update readme
1 parent da6a2b0 commit 5c88bd6

File tree

2 files changed

+36
-2
lines changed

2 files changed

+36
-2
lines changed

README.md

Lines changed: 34 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,13 +56,39 @@ pool.connect().then(client => {
5656
})
5757
```
5858

59-
pg-pool supports the traditional callback api for acquiring a client that node-postgres has shipped with internally for years:
59+
this ends up looking much nicer if you're using [co](https://github.com/tj/co) or async/await:
60+
61+
```js
62+
const pool = new Pool()
63+
const client = await pool.connect()
64+
try {
65+
const result = await client.query('select $1::text as name', ['brianc'])
66+
console.log('hello from', result.rows[0])
67+
} finally {
68+
client.release()
69+
}
70+
```
71+
72+
because its so common to just run a query and return the client to the pool afterward pg-pool has this built-in:
73+
74+
```js
75+
const pool = new Pool()
76+
const time = await pool.query('SELECT NOW()')
77+
const name = await pool.query('select $1::text as name', ['brianc'])
78+
console.log(name.rows[0].name, 'says hello at', time.rows[0].name)
79+
```
80+
__pro tip:__ unless you need to run a transaction (which requires a single client for multiple queries) or you
81+
have some other edge case like [streaming rows](https://github.com/brianc/node-pg-query-stream) or using a [cursor](https://github.com/brianc/node-pg-cursor)
82+
you should almost always just use `pool.query`. Its easy, it does the right thing :tm:, and wont ever forget to return
83+
clients back to the pool after the query is done.
84+
85+
pg-pool still and will always support the traditional callback api for acquiring a client that node-postgres has shipped with internally for years:
6086

6187
```js
6288
const pool = new Pool()
6389
pool.connect((err, client, done) => {
6490
if (err) return done(err)
65-
91+
6692
client.query('SELECT $1::text as name', ['pg-pool'], (err, res) => {
6793
done()
6894
if (err) {
@@ -73,6 +99,8 @@ pool.connect((err, client, done) => {
7399
})
74100
```
75101

102+
That means you can drop pg-pool into your app and 99% of the cases you wont even notice a difference. In fact, very soon I will be using pg-pool internally within node-postgres itself!
103+
76104
When you are finished with the pool if all the clients are idle the pool will close them after `config.idleTimeoutMillis` and your app
77105
will shutdown gracefully. If you don't want to wait for the timeout you can end the pool as follows:
78106

@@ -88,6 +116,10 @@ await pool.end()
88116

89117
To run tests clone the repo, `npm i` in the working dir, and then run `npm test`
90118

119+
## contributions
120+
121+
I love contributions. Please make sure they have tests, and submit a PR. If you're not sure if the issue is worth it or will be accepted it never hurts to open an issue to begin the conversation. Don't forget to follow me on twitter at [@briancarlson](https://twitter.com/briancarlson) - I generally announce any noteworthy updates there.
122+
91123
## license
92124

93125
The MIT License (MIT)

index.js

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,8 @@ Pool.prototype._create = function (cb) {
4242
cb(err)
4343
}
4444

45+
var query = client.query;
46+
4547
client.queryAsync = function (text, values) {
4648
return new this.Promise((resolve, reject) => {
4749
client.query(text, values, function (err, res) {

0 commit comments

Comments
 (0)