node-postgres/README.md

#node-postgres

100% javascript. 100% async. 100% would love your contributions.

Why?

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 told my friend "ah man the only thing holding node back is a really solid data access story." I mean...let's put the NoSQL debate aside. 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? 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 and doesn't seem to be actively developed anymore. I am not comfortable forking & playing with a project without having a way to run a test suite, let alone using it in production.

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 possible obsessive test coverage to back up.

ALPHA version

Implemented in a fully TDD fashion. I'm aiming for extremely high quality code, but first doing the implementation and only refactoring after tests are in place.

Connection

The connection object is a 1 to 1 mapping to the messaging protocol. It is mostly used by the Client object (which...I haven't yet finished implementing) but you can do anything you want with PostgreSQL using the connection object if you're really into that. I studied the protocol for a while implementing this and the documentation is pretty solid.

There are a few minor variations from the protocol:

• The connection only supports 'text' mode right now.
• Renamed 'passwordMessage' to 'password'
• Renamed 'startupMessage' to 'startup'
• Renamed 'errorResposne' to 'error'
• Renamed 'noticeResponce' to 'notice'

The reason for the renamings is 90% of the message names in the protocol do no contain "message" "request" "response" or anything similar, and I feel it's a bit redundant to send a "passwordMessage message." But then again...I do say ATM machine.

Anyways...using a connection directly is a pretty verbose and cumbersom affair. Here's an example of executing a prepared query using the directly Connection api in compliance with PostgreSQL.

note: this works and is taken directly from an integration test; however, it doesn't even include error handling

var con = new Connection({stream: new net.Stream()});

con.connect('5432','localhost');

con.once('connect', function() {

  con.startup({
    user: username,
    database: database
  });

  con.once('readyForQuery', function() {

    con.query('create temp table ids(id integer)');

    con.once('readyForQuery', function() {

      con.query('insert into ids(id) values(1); insert into ids(id) values(2);');

      con.once('readyForQuery', function() {

        con.parse({
          text: 'select * from ids'
        });
        con.flush();

        con.once('parseComplete', function() {
          con.bind();
          con.flush();
        });

        con.once('bindComplete', function() {
          con.execute();
          con.flush();
        });

        con.once('commandComplete', function() {
          con.sync();
        });

        con.once('readyForQuery', function() {
          con.end();
        });
      });
    });
  });
});

Client

Basically a facade on top of the connection to provide a much more user friendly, "node style" interface for doing all the lovely things you like with PostgreSQL.

Now that I've got the Connection api in place, the bulk and meat of the work is being done on the Client to provide the best possible API. Help? Yes please!

What I'd like is to simplify the above low level use with something like this:

note: this doesn't even exist yet var client = new Client({ user: 'brian', database: 'postgres', });

client.query("create temp table ids(id integer)");
client.query("insert into ids(id) values(1)");
client.query("insert into ids(id) values(2)");
var query = client.query("select * from ids", function(row) {
  row.fields[0] // <- that equals 1 the first time. 2 the second time.
});
query.on('end', function() {
  client.end();
});    

TODO

• Error handling
• integration testing
• notificationp
• setting parameters
• connection pooling
• copy data
• connection pooling
• kiss the sky