updated readme
This commit is contained in:
brianc
parent
80ee829ba0
commit
f54f6bfab5
134
README.md
134
README.md
@ -1,20 +1,34 @@
|
||||
#pg.js
|
||||
Async Pure JavaScript PostgreSQL driver for node.js
|
||||
#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 looked at the various NoSQL solutions but
|
||||
I still thought having support an actual database founded on decades of PhD
|
||||
level research might be something nice to have?
|
||||
|
||||
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 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 and 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. Drew major inspiration from
|
||||
[postgres-js](http://github.com/creationix/postgres-js) but it has 0 tests and
|
||||
doesn't seem to be actively developed anymore. I'm aiming for
|
||||
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.
|
||||
|
||||
I'm first aiming to support the low level [messaging
|
||||
protocol](http://developer.postgresql.org/pgdocs/postgres/protocol.html).
|
||||
|
||||
Due to the fully async nature of node sockets, the driver is
|
||||
completely non-blocking. Jump for joy!
|
||||
|
||||
### Connection
|
||||
|
||||
The connection object is a 1 to 1 mapping to the [messaging
|
||||
@ -23,18 +37,110 @@ It is mostly used by the Client object (which...I haven't yet
|
||||
implemented) 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. The connection only supports 'text' mode right now.
|
||||
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
|
||||
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
|
||||
- notification
|
||||
- notificationp
|
||||
- setting parameters
|
||||
- connection pooling
|
||||
- copy data
|
||||
|
||||
Loading…
Reference in New Issue
Block a user