lib | ||
script | ||
test | ||
.gitignore | ||
License | ||
package.json | ||
README.md |
#node-postgres
Non-blocking (async) JavaScript PostgreSQL client for node.js written fully TDD and with lots of love.
alpha version
Installation
npm install pg
Whirlwind tour
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));
//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
});
var preparedStatement = client.query({
name: 'user by heart type',
text: 'select * from user where heart = $1',
values: ['big']
});
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)
- extreme documentation
features
- prepared statement support
- parameters
- query caching
- type coercion
- date <-> timestamptz
- integer <-> integer, smallint, bigint
- float <-> double, numeric
- boolean <-> boolean
- notification message support
- tested like a Toyota
~1000 assertions executed on
- ubuntu
- node v0.2.2, v0.2.3, v0.2.4, v0.3.0
- 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
- ubuntu
party time
clone the repo:
git clone git://github.com/brianc/node-postgres
cd node-postgres
node test/run.js
And just like magic, you're ready to contribute! <3
More info please
Documentalicious
PLEASE check out the 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 is running the worlds worst (but fully functional) PostgreSQL backed, Node.js powered website.
Why did you write this?
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 be vanquished.
I drew major inspiration from 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 also drew some major inspirrado from node-mysql and liked what I saw there. I'm thinking I might be stealing some of the ideas there for the Client api.
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.
License
node-postgres is licensed under the MIT license.