glider
Simple, expressive, Promise-based API for interacting with Postgres built on node-postgres. Supports node.js 0.12+.
Table of Contents
Install
npm install --save glider
Usage
create a Database object
The Database
object is the core for most of the API. All you need to do is provide a connection string or client configuration object, just like in node-postgres with pg.connect.
var db = ; // or... var db = ;
basic queries
The mechanics of the basic query is identical to node-postgres, except that instead of providing a callback, glider
returns a Promise.
var db = ; // "result" is a node-postgres result objectdb;
getting data from queries (SELECT)
The following functions allow you to grab rows, a single row, or even a single value.
var db = ; // array of rowsdb; // single rowdb; // single valuedbvalue'select 1::integer as number';
row count queries (INSERT/UPDATE/DELETE)
In the instance where you are doing non-returning queries that have a row count, like insert/update/delete, glider
has functions that will instead return the row count. This is a matter of convenience. If you need the full result object, use db.query()
.
The functions are functionally identical to each other, but allow the actual operation to be more expressive, which becomes extremely useful once you start using glider
's transactions.
var db = ; db; db; db; db;
postgres commands
You can also execute postgres commands or any query you don't need a result for with command()
. So whether you're invoking a CREATE
or ALTER
or just calling an insert/update/delete for which you don't need a result, use command()
.
var db = ; db; db;
transactions
glider
has a unique chaining API that allows you to string together a series of queries in a very clear, expressive manner. All connection pooling, result gathering, error handling, etc... is handled internally and a Promise is returned.
If there's an error in any of the queries in a transaction, glider
will automatically invoke a ROLLBACK
and reject the current Promise with the database error.
var db = ;db value'select value from foo where id = 1' ;
or a similar example of returning node-postgres
's result objects...
var db = ;db ;
and since the session is handled internally by glider
, you can make use of postgres's sequence manipulation functions, like in this trivial example...
var db = ;db ;
Testing
To test, install the prerequisites, run npm test
, and vagrant will take care of spinning up a headless VM with a local postgres instance. All tests will be run against this instance. The vagrant VM will continue running after the tests complete to make subsequent test runs instant. You can shut down the VM at any time by running vagrant halt
, or remove the VM entirely with vagrant destroy
.
Prerequisites
Run tests (mocha + should)
npm test
Generate coverage report (istanbul)
Reports are generated in the ./coverage
folder. An HTML-based report can be loaded into the browser from ./coverage/lcov-report/index.html
.
npm run cover