libpq - npm Package Compare versions

Comparing version 0.4.1 to 0.5.0

test/error-info.js

index.js

		@@ -178,2 +178,6 @@ var PQ = module.exports = require('bindings')('addon.node').PQ;

		PQ.prototype.resultErrorFields = function() {
		return this.$resultErrorFields();
		};

		//free the memory associated with a result
		@@ -180,0 +184,0 @@ //this is somewhat handled for you within the c/c++ code

package.json

		{
		"name": "libpq",
		"version": "0.4.1",
		"version": "0.5.0",
		"description": "Low-level native bindings to PostgreSQL libpq",
		@@ -15,3 +15,3 @@ "main": "index.js",
		"scripts": {
		"test": "node-gyp rebuild && ./node_modules/.bin/mocha"
		"test": "node-gyp rebuild && node_modules/.bin/mocha"
		},
		@@ -18,0 +18,0 @@ "author": "Brian M. Carlson",

README.md

		@@ -9,2 +9,4 @@ # node-libpq

		I am also building some [higher level abstractions](https://github.com/brianc/node-pg-native) to eventually replace the `pg.native` portion of node-postgres. They should help as reference material.

		## install
		@@ -35,3 +37,3 @@

		Asyncronously attempts to connect to the postgres server.
		Asyncronously attempts to connect to the postgres server.

		@@ -41,4 +43,6 @@ - `connectionParams` is an optional string

		This function actually calls the `PQconnectdb` blocking connection method in a background thread within node's internal thread-pool. There is a way to do non-blocking network I/O for some of the connecting with libpq directly, but it still blocks when your local file system looking for config files, SSL certificates, .pgpass file, and doing possible dns resolution. Because of this, the best way to get _fully_ non-blocking is to juse use `libuv_queue_work` and let node do it's magic.
		__async__ Connects to a PostgreSQL backend server process.

		This function actually calls the `PQconnectdb` blocking connection method in a background thread within node's internal thread-pool. There is a way to do non-blocking network I/O for some of the connecting with libpq directly, but it still blocks when your local file system looking for config files, SSL certificates, .pgpass file, and doing possible dns resolution. Because of this, the best way to get _fully_ non-blocking is to juse use `libuv_queue_work` and let node do it's magic and so that's what I do. This function _does not block_.

		##### `pq.connectSync([connectionParams:string])`
		@@ -94,3 +98,3 @@

		In libpq the async command execution functions _only_ dispatch a reqest to the backend to run a query. They do not start result fetching on their own. Because libpq is a C api there is a somewhat complicated "dance" to retrieve the result information in a non-blocking way. node-libpq attempts to do as little as possible to abstract over this; therefore, the following functions are only part of the story. For a complete tutorial on how to dispatch & retrieve results from libpq in an async way you can [view the complete approach here](https://github.com/brianc/node-pg-native/blob/master/index.js#L105)
		In libpq the async command execution functions _only_ dispatch a request to the backend to run a query. They do not start result fetching on their own. Because libpq is a C api there is a somewhat complicated "dance" to retrieve the result information in a non-blocking way. node-libpq attempts to do as little as possible to abstract over this; therefore, the following functions are only part of the story. For a complete tutorial on how to dispatch & retrieve results from libpq in an async way you can [view the complete approach here](https://github.com/brianc/node-pg-native/blob/master/index.js#L105)

		@@ -144,2 +148,10 @@ ##### `pq.sendQuery(commandText:string):boolean`

		##### `pq.resultErrorFields():object`

		Retrieves detailed error information from the current result object. Very similar to `PQresultErrorField()` except instead of passing a fieldCode and retrieving a single field, retrieves all fields from the error at once on a single object. The object returned is a simple hash, _not_ an instance of an error object. Example: if you wanted to access `PG_DIAG_MESSAGE_DETAIL` you would do the following:

		```js
		console.log(pq.errorFields().messageDetail)
		```

		##### `pq.clear()`
		@@ -221,2 +233,45 @@

		### listen/notify

		##### `pq.notifies():object`

		Checks for `NOTIFY` messages that have come in. If any have been received they will be in the following format:

		```js
		var msg = {
		relname: 'name of channel',
		extra: 'message passed to notify command',
		be_pid: 130
		}
		```

		### COPY IN/OUT

		##### `pq.putCopyData(buffer:Buffer):int`

		After issuing a successful command like `COPY table FROM stdin` you can start putting buffers directly into the databse with this function.

		- `buffer` Is a required node buffer of text data such as `Buffer('column1\tcolumn2\n')`

		Returns `1` if sent succesfully. Returns `0` if the command would block (only if you have called `pq.setNonBlocking(true)`). Returns `-1` if there was an error sending the command.

		##### `pq.putCopyEnd([errorMessage:string])`

		Signals the backed your copy procedure is complete. If you pass `errorMessage` it will be sent to the backend and effectively cancel the copy operation.

		- `errorMessage` is an _optional_ string you can pass to cancel the copy operation.

		Returns `1` if sent succesfully. Returns `0` if the command would block (only if you have called `pq.setNonBlocking(true)`). Returns `-1` if there was an error sending the command.


		##### `pq.getCopyData(async:boolean):Buffer or int`

		After issuing a successfuly command like `COPY table TO stdout` gets copy data from the connection.

		Returns a node buffer if there is data available.

		Returns `0` if the copy is still in progress (only if you have called `pq.setNonBlocking(true)`). Returns `-1` if the copy is completed. Returns `-2` if there was an error.

		- `async` is a boolean. Pass `false` to __block__ waiting for data from the backend. _defaults to `false`_

		### Misc Functions
		@@ -223,0 +278,0 @@

test/multiple-queries.js

		@@ -54,4 +54,7 @@ var Libpq = require('../');
		var pq = new Libpq();
		pq.connectSync();

		before(function(done) {
		pq.connect(done)
		})

		it('first query works', function(done) {
		@@ -58,0 +61,0 @@ query(pq, done);

src/addon.cc