updated readme
This commit is contained in:
parent
80ee829ba0
commit
f54f6bfab5
134
README.md
134
README.md
@ -1,20 +1,34 @@
|
|||||||
#pg.js
|
#node-postgres
|
||||||
Async Pure JavaScript PostgreSQL driver for node.js
|
|
||||||
|
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
|
## ALPHA version
|
||||||
|
|
||||||
Implemented in a fully TDD fashion. Drew major inspiration from
|
Implemented in a fully TDD fashion. I'm aiming for
|
||||||
[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
|
|
||||||
extremely high quality code, but first doing the implementation and
|
extremely high quality code, but first doing the implementation and
|
||||||
only refactoring after tests are in place.
|
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
|
### Connection
|
||||||
|
|
||||||
The connection object is a 1 to 1 mapping to the [messaging
|
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
|
implemented) but you can do anything you want with PostgreSQL using
|
||||||
the connection object if you're really into that. I studied the
|
the connection object if you're really into that. I studied the
|
||||||
protocol for a while implementing this and the documentation is pretty
|
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
|
### 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
|
user friendly, "node style" interface for doing all the lovely things
|
||||||
you like with PostgreSQL.
|
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
|
## TODO
|
||||||
- Error handling
|
- Error handling
|
||||||
- integration testing
|
- integration testing
|
||||||
- notification
|
- notificationp
|
||||||
- setting parameters
|
- setting parameters
|
||||||
- connection pooling
|
- connection pooling
|
||||||
- copy data
|
- copy data
|
||||||
|
Loading…
Reference in New Issue
Block a user