Updated README.md

Author: brianc

README.md

@@ -7,10 +7,12 @@ PostgreSQL client for node.js.  Pure JavaScript and native libpq bindings.
 ## Installation
 
     npm install pg
-    
+       
 ## Examples
 
-### Callbacks
+### Simple
+
+Connect to a postgres instance, run a query, and disconnect.
 
 ```javascript
 var pg = require('pg'); 
@@ -19,88 +21,77 @@ var pg = require('pg');
 
 var conString = "tcp://postgres:1234@localhost/postgres";
 
-//note: error handling omitted
 var client = new pg.Client(conString);
 client.connect(function(err) {
+  if(err) {
+    console.error('could not connect to postgres', err);
+    return;
+  }
   client.query('SELECT NOW() AS "theTime"', function(err, result) {
+      if(err) {
+        console.error('error running query', err);
+        return;
+      }
       console.log(result.rows[0].theTime);
       //output: Tue Jan 15 2013 19:12:47 GMT-600 (CST)
+      client.end();
   })
 });
 
 ```
 
-### Events
+### Client pooling
+
+Typically you will access the PostgreSQL server through a pool of clients.  node-postgres ships with a built in pool to help get you up and running quickly.
 
 ```javascript
-var pg = require('pg'); //native libpq bindings = `var pg = require('pg').native`
+var pg = require('pg');
 var conString = "tcp://postgres:1234@localhost/postgres";
 
-var client = new pg.Client(conString);
-client.connect();
-
-//queries are queued and executed one after another once the connection becomes available
-client.query("CREATE TEMP TABLE beatles(name varchar(10), height integer, birthday timestamptz)");
-client.query("INSERT INTO beatles(name, height, birthday) values($1, $2, $3)", ['John', 68, new Date(1944, 10, 13)]);
-var query = client.query("SELECT * FROM beatles WHERE name = $1", ['John']);
-
-//can stream row results back 1 at a time
-query.on('row', function(row) {
-  console.log(row);
-  console.log("Beatle name: %s", row.name); //Beatle name: John
-  console.log("Beatle birth year: %d", row.birthday.getYear()); //dates are returned as javascript dates
-  console.log("Beatle height: %d' %d\"", Math.floor(row.height/12), row.height%12); //integers are returned as javascript ints
-});
-
-//fired after last row is emitted
-query.on('end', function() { 
-  client.end();
+pg.connect(conString, function(err, client, done) {
+  if(err) {
+  	console.error('error fetching client from pool', err);
+    return;
+  }
+  client.query('SELECT $1::int AS numbor', ['1'], function(err, result) {
+    //call `done()` to release the client back to the pool
+    done();
+    
+    if(err) {
+      console.error('error running query', err);
+      return;
+    }
+    console.log(result.rows[0].numbor);
+    //output: 1
+  });
 });
 ```
 
-### Example notes
+## Documentation
 
-node-postgres supports both an 'event emitter' style API and a 'callback' style.  The callback style is more concise and generally preferred, but the evented API can come in handy when you want to handle row events as they come in.  
+Documentation is a work in progress primarily taking place on the github WIKI
+
+### [Documentation](https://github.com/brianc/node-postgres/wiki)
 
-They can be mixed and matched.  The only events which do __not__ fire when callbacks are supplied are the `error` events, as they are to be handled within the callback function.
+## Native Bindings
 
-All examples will work with the pure javascript bindings or the libpq native (c/c++) bindings
+node-postgres contains a pure JavaScript driver and also exposes JavaScript bindings to libpq.  You can use either interface.  I personally use the JavaScript bindings as the are quite fast, and I like having everything implemented in JavaScript.
 
 To use native libpq bindings replace `require('pg')` with `require('pg').native`.
 
 The two share the same interface so __no other code changes should be required__.  If you find yourself having to change code other than the require statement when switching from `pg` to `pg.native`, please report an issue.
 
-### Features
 
-* pure javascript client and native libpq bindings share _the same api_
-* row-by-row result streaming
-* responsive project maintainer
+## Features
+
+* pure JavaScript client and native libpq bindings share _the same api_
+* optional connection pooling
+* extensible js<->postgresql data-type coercion
 * supported PostgreSQL features
   * parameterized queries
   * named statements with query plan caching
   * async notifications with `LISTEN/NOTIFY`
   * bulk import & export with `COPY TO/COPY FROM`
-  * extensible js<->postgresql data-type coercion
-
-## Documentation
-
-Documentation is a work in progress primarily taking place on the github WIKI
-
-### [Documentation](https://github.com/brianc/node-postgres/wiki)
-
-### __PLEASE__ check out the WIKI
-
-If you have a question, post it to the FAQ section of the WIKI so everyone can read the answer
-
-## Production Use
-* [yammer.com](http://www.yammer.com)
-* [bayt.com](http://bayt.com)
-* [bitfloor.com](https://bitfloor.com)
-* [Vendly](http://www.vend.ly)
-* [SaferAging](http://www.saferaging.com)
-* [CartoDB](http://www.cartodb.com)
-
-_if you use node-postgres in production and would like your site listed here, fork & add it_
 
 ## Contributing
 
@@ -140,6 +131,18 @@ node-postgres is by design _low level_ with the bare minimum of abstraction.  Th
 - https://github.com/grncdr/node-any-db
 - https://github.com/brianc/node-sql
 
+
+## Production Use
+* [yammer.com](http://www.yammer.com)
+* [bayt.com](http://bayt.com)
+* [bitfloor.com](https://bitfloor.com)
+* [Vendly](http://www.vend.ly)
+* [SaferAging](http://www.saferaging.com)
+* [CartoDB](http://www.cartodb.com)
+
+_if you use node-postgres in production and would like your site listed here, fork & add it_
+
+
 ## License
 
 Copyright (c) 2010 Brian Carlson (brian.m.carlson@gmail.com)