Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

updated readme

  • Loading branch information...
commit b6af6927a50b2106b7b9c81c38760a196ae6296d 1 parent a2f7ca3
@brianc authored
Showing with 67 additions and 26 deletions.
  1. +67 −26 README.md
View
93 README.md
@@ -1,28 +1,6 @@
#node-postgres
-Non-blocking PostgreSQL client for node.js
-
-* a pure javascript client and native libpq bindings with _the same api_
-* _heavily_ tested
- * the same suite of 200+ integration tests passed by both javascript & libpq bindings
- * benchmark & long-running memory leak tests performed before releases
- * tested with with
- * postgres 8.x, 9.x
- * Linux, OS X
- * node 2.x, 3.x, & 4.x
-* row-by-row result streaming
-* optional, built-in connection pooling
-* responsive project maintainer
-* supported PostgreSQL features
- * parameterized queries
- * named statements with query plan caching
- * async notifications
- * extensible js<->postgresql data-type coercion
-* query queue
-* active development
-* _very_ fast
-* No dependencies (other than PostgreSQL)
-* No monkey patching
+Non-blocking PostgreSQL client for node.js. Pure JavaScript and native libpq bindings.
## Installation
@@ -30,7 +8,27 @@ Non-blocking PostgreSQL client for node.js
## Examples
-All examples will work with the pure javascript bindings (currently default) or the libpq native (c/c++) bindings (currently in beta.) Replace `require('pg')` with `require(pg/native)` to use the libpq native (c/c++) bindings.
+All examples will work with the pure javascript bindings (currently default) or the libpq native (c/c++) bindings (currently in beta)
+
+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.
+
+### Simple, using built-in client pool
+
+ var pg = require('pg');
+ //or native libpq bindings
+ //var pg = require('pg/native')
+
+ var conString = "tcp://postgres:1234@localhost/postgres";
+
+ //error handling omitted
+ pg.connect(conString, function(err, client) {
+ client.query("SELECT NOW() as when", function(err, result) {
+ console.log("Row count: %d",result.rows.length); // 1
+ console.log("Current year: %d", result.rows[0].when.getYear());
+ });
+ });
### Evented api
@@ -39,11 +37,27 @@ All examples will work with the pure javascript bindings (currently default) or
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("CREATE TEMP TABLE beatles(name varchar(10), height integer, birthday timestamps)");
client.query("INSERT INTO beatles(name, height, birthday) values($1, $2, $3)", ['Ringo', 67, new Date(1945, 11, 2)]);
client.query("INSERT INTO beatles(name, height, birthday) values($1, $2, $3)", ['John', 68, new Date(1944, 10, 13)]);
+
+ //queries can be executed either via text/parameter values passed as individual arguments
+ //or by passing an options object containing text, (optional) parameter values, and (optional) query name
+ client.query({
+ name: 'insert beatle',
+ text: "INSERT INTO beatles(name, height, birthday) values($1, $2, $3)",
+ values: ['George', 70, new Date(1946, 02, 14)]
+ });
+
+ //subsequent queries with the same name will be executed without re-parsing the query plan by postgres
+ client.query({
+ name: 'insert beatle',
+ values: ['Paul', 63, new Date(1945, 04, 03)]
+ });
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);
@@ -51,10 +65,37 @@ All examples will work with the pure javascript bindings (currently default) or
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
});
- query.on('end', function() { //fired after last row is emitted
+
+ //fired after last row is emitted
+ query.on('end', function() {
client.end();
});
+### Info
+
+* a pure javascript client and native libpq bindings with _the same api_
+* _heavily_ tested
+ * the same suite of 200+ integration tests passed by both javascript & libpq bindings
+ * benchmark & long-running memory leak tests performed before releases
+ * tested with with
+ * postgres 8.x, 9.x
+ * Linux, OS X
+ * node 2.x, 3.x, & 4.x
+* row-by-row result streaming
+* optional, built-in connection pooling
+* responsive project maintainer
+* supported PostgreSQL features
+ * parameterized queries
+ * named statements with query plan caching
+ * async notifications
+ * extensible js<->postgresql data-type coercion
+* query queue
+* active development
+* fast
+* No dependencies (other than PostgreSQL)
+* No monkey patching
+* Tried to mirror the node-mysql api as much as possible for future multi-database-supported ORM implementation ease
+
### Contributors
Many thanks to the following:
Please sign in to comment.
Something went wrong with that request. Please try again.