diff --git a/README.md b/README.md index 2247e5fc..9be33fbe 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ #node-postgres -Non-blocking (async) JavaScript PostgreSQL client for node.js written -fully TDD and with lots of love. +Non-blocking (async) pure JavaScript PostgreSQL client for node.js written +with love and TDD. ## alpha version @@ -9,65 +9,37 @@ fully TDD and with lots of love. npm install pg -### Whirlwind tour +### Example - var Client = require('pg').Client; - var client = new Client({ - user: 'brianc', - database: 'test', - password: 'boom' //plaintext or md5 supported - }); - - client.connect(); - client.on('drain', client.end.bind(client)); + var pg = require('pg'); - //queries are queued on a per-client basis and executed one at a time - client.query("create temp table user(heart varchar(10), birthday timestamptz);"); - - //parameters are always parsed & prepared inside of PostgreSQL server - //using unnamed prepared statement (no sql injection! yay!) - client.query({ - text: 'INSERT INTO user(heart, birthday) VALUES ($1, $2)', - values: ['big', new Date(2031, 03, 03)] - }); - client.query({ - text: 'INSERT INTO user(heart, birthday) VALUES ($1, $2)', - values: ['filled with kisses', new Date(2010, 01, 01)] - }); - - var simpleQuery = client.query("select * from user where heart = 'big'"); - simpleQuery.on('row', function(row){ - console.log(row.heart); //big - console.log(row.birthday.getYear()); //2031 - }); + pg.connect('postgres://user:password@host:port/database', function(error, client) { + if(error) { + //handle error + return + } + //simple query + client.query("CREATE TABLE users(name varchar(10), birthday timestamptz)") - var preparedStatement = client.query({ - name: 'user by heart type', - text: 'select * from user where heart = $1', - values: ['big'] - }); + //prepared statements with bound parameters + client.query("INSERT INTO users(name, birthday) VALUES($1, $2)" ['brianc', new Date(2010, 01, 01)]) + client.query("INSERT INTO users(name, birthday) VALUES($1, $2)", ['ringo', new Date(2008, 01, 01)]) + client.query("SELECT * FROM users WHERE birthday > $1", [new Date(2009, 01, 01)], function(error, result) { + if(error) { + //handle error + return + } + assert.equal(result.rows[0].name, 'brianc') + }) - preparedStatement.on('row', function(row){ - console.log(row.heart); //big - console.log(row.birthday.getYear()); //2031 - }); + }) - var cachedPreparedStatement = client.query({ - name: 'user by heart type', - //you can omit the text the 2nd time if using a named query - values: ['filled with kisses'] - }); - - cachedPreparedStatement.on('row', function(row){ - console.log(row.heart); //filled with kisses - console.log(row.birthday.getYear()); //2010 - }); ### Philosophy * well tested * no monkey patching -* no dependencies (well...besides PostgreSQL) +* no dependencies (...besides PostgreSQL) * [extreme documentation](http://github.com/brianc/node-postgres/wiki) ### features @@ -84,13 +56,13 @@ fully TDD and with lots of love. - tested like a Toyota ~1000 assertions executed on - ubuntu - - node v0.2.2, v0.2.3, v0.2.4, v0.3.0 + - node v0.2.2, v0.2.3, v0.2.4, v0.2.5, v0.3.0, v0.3.1 - postgres 8.4.4 - osx - - node v0.2.2, v0.2.3, v0.2.4, v0.3.0 - - postgres v8.4.4, v9.0.1 + - node v0.2.2, v0.2.3, v0.2.4, v0.2.5, v0.3.0, v0.3.1 + - postgres v8.4.4, v9.0.1 installed both locally and on networked Windows 7 -### party time +### Contributing clone the repo: @@ -102,16 +74,10 @@ And just like magic, you're ready to contribute! <3 ## More info please -### Documentalicious +### Documentation __PLEASE__ check out the [WIKI](node-postgres/wiki). __MUCH__ more information there. -p.s. want your own offline version of the wiki? - - git clone git://github.com/brianc/node-postgres.wiki.git - -_github is magic_ - ### Working? [this page](http://www.explodemy.com) is running the worlds worst (but fully functional) PostgreSQL backed, Node.js powered website. @@ -122,30 +88,17 @@ As soon as I saw node.js for the first time I knew I had found something lovely and simple and _just what I always wanted!_. So...I poked around for a while. I was excited. I still am! -Let's say for arguments sake you have to run a query from node.js on PostgreSQL before the -last petal falls off the rose and you are stuck as a beast forever? -You can't use NoSQL because your boss said he'd pour a cup of -Hoegarten into your laptop fan vent and you _hate_ that beer? -What if your entire production site depends on it? Well, fret no -more. And let [GastonDB](http://www.snipetts.com/ashley/mymusicals/disney/beauty-an-beast/images/gaston.gif) be vanquished. - -I drew major inspiration from -[postgres-js](http://github.com/creationix/postgres-js). I didn't -just fork and contribute because it has -_0_ tests included with it, adds a bunch of methods to the Buffer() -object, and doesn't seem to be maintained. Still...was a lovely way -to learn & excellent reference material. +I drew major inspiration from [postgres-js](http://github.com/creationix/postgres-js). I also drew some major inspirrado from [node-mysql](http://github.com/felixge/node-mysql) and liked what I -saw there. I'm thinking I might be stealing some of the ideas there -for the __Client__ api. +saw there. -So...__boom__. I set out to write my own. I'm not working on anything -else in my spare time other than this. It's a labor of love. I'd -love for you to love it as well. Contribute. Fork, patch, and send -me a pull request. All I ask is everything you add you have complete -and possibly obsessive test coverage to back up. +### Plans for the future? + +- transparent prepared statement caching +- connection pooling +- more testings of error scenarios ## License