#easy-pg
easy-pg is "easy to use" deferred PostgreSQL client for node.js with possibility of using native libpq bindings and providing some frequently used querying functions. It prevents queries from not being processed due to unexpected minor errors such as temporary loss of connection. Easy-pg stacks queries during transactions as well to revive whole transaction in the case of interrupted connection.
##Installation
npm install easy-pg
##Examples
###Simple Connection Simple example of connecting to postgres instance, running a query and disconnecting. Client is created as deferrer client thus it's not connected until the first query is requested. In this example number 7 is inserted into table called numbers, column number. Client is disconnected right after the query result is known.
epg = require "easy-pg"
# epg = require("easy-pg").native -to use native libpq bindings
client = epg "pg://postgres@localhost/myapp_test"
client.on "ready", () -> console.log "Client is connected"
client.on "end", () -> console.log "Client is disconnected"
# not connected so far, it's deferred client!
# client creates connection only with the first query
#insert number into specified table and disconnect
client.insert "numbers", {number: 7}, (err, res) ->
console.log err if err?
console.log res if res?
client.end()Previous code results in:
Client is connected
{id: 1, number: 7}
Client is disconnected
###Connection Parameters & Options You can pass connection string or object into easy-pg constructor with connection options. These options are processed by client (if known) and transparently forwarded to postgres instance later.
epg = require "easy-pg"
#connection string
conString = "pg://postgres@localhost/myapp_test?opt1=val1&opt2=val2&opt3=val3"
#the same connection object
conObject =
protocol: "pg:"
user: "postgres"
host: "localhost"
db: "myapp_test"
options: {
opt1: val1
opt2: val2
opt3: val3
}
#both following is correct
client = epg conString
client = epg conObjectFollowing connection parameters and options can be used:
- Connection parameters
- protocol (required)
- user
- password
- host (required)
- port
- db (required)
- Connection options
- lazy -set to "no" or "false" to force the client to connect immediately
- poolSize -max number of connections in the pool
- dateStyle -instead of (in SQL) commonly used SET DATESTYLE
- searchPath -instead of (in SQL) commonly used SET SEARCH_PATH
- pgVersion -version of the postgreSQL instance, set automatically
Full connection string may look like this: "pg://postgres:123456@localhost:5432/myapp_test?lazy=no&dateStyle=iso, mdy&searchPath=public&poolSize=1&hang=no", where hang is not handled by easy-pg, but may be processed by postgres instance. Connection options are checked and applied every time the client is (re)connected, thus once you for example set dateStyle, it is kept set until the client is disconnected and destroyed. Even if the connection is temporarily lost.
###Disconnection
Client creates connection to specified postgres instance automatically, however disconnection has to be done manually. Easy-pg provides two functions for client disconnection or termination. Function end can be used to disconnect client with the last processed query. This way of client disconnection should be used in common cases. In the case of stuck, kill can be used to terminate the client immediately, but there is a risk of unpredictable behavior. Both functions emit end event.
epg = require "easy-pg"
client = epg "pg://postgres@localhost/myapp_test"
# not connected yet
client.queryAll "SELECT * FROM table"
# auto-connecting, client is going to send the query
client.end()
# connected, query is being processed
# end() is waiting until the query is finished
client.kill()
# connected, query is being processed, we don't want to wait anymore
# client is terminated immediately, error could occur
# not connected, end event is emitted###Client Events
There are 3 events emitted by easy-pg client:
- ready
- end
- error (client throws an ordinary Error if error listener is not registered, as shown in the following code)
epg = require "easy-pg"
client = epg "pg://postgres@localhost/myapp_test"
# an ordinary Error can be thrown here
client.on "ready", () -> console.log "Client is connected"
client.on "end", () -> console.log "Client is disconnected"
# an ordinary Error can still be thrown here
client.on "error", (err) ->
console.log "Client error: " + err
# error event can be emitted hereError event is emitted just in the case of fatal error (syntax error, etc.). For example, if postgres server is restarted while processing query and the query fails, client reconnects itself and tries to process this query again without emitting or throwing any error.
###Making Queries
Any kind of queries can be created and sent by easy-pg client, even with parameter binding. Queries can be easily made using following functions:
- query
- queryAll
- queryOne
These functions differ just in the data format of their results. Function query returns raw result of the query containing number of rows, table id, etc. QueryAll returns only array of all rows of the query result and queryOne returns only the first entry (row) of this array. They can be used as shown in the code:
epg = require "easy-pg"
client = epg "pg://postgres@localhost/myapp_test"
client.query "SET DATESTYLE = iso"
client.query "SELECT * FROM table", (err, res) -> # do sth. in callback...
client.query "SELECT $1 FROM $2", ["*", "table"] # bind some parameters...
client.query "SELECT $1 FROM $2", ["*", "table"], (err, res) -> # do sth. in callback...
client.queryAll "SET DATESTYLE = iso"
client.queryAll "SELECT * FROM table", (err, res) -> # do sth. in callback...
client.queryAll "SELECT $1 FROM $2", ["*", "table"] # bind some parameters...
client.queryAll "SELECT $1 FROM $2", ["*", "table"], (err, res) -> # do sth. in callback...
client.queryOne "SET DATESTYLE = iso"
client.queryOne "SELECT * FROM table", (err, res) -> # do sth. in callback...
client.queryOne "SELECT $1 FROM $2", ["*", "table"] # bind some parameters...
client.queryOne "SELECT $1 FROM $2", ["*", "table"], (err, res) -> # do sth. in callback...###Built-in Querying Functions
Easy-pg provides some well known querying functions as well to make your work easier and source code cleaner. Implemented querying functions are insert, update, upsert, delete and paginate. All these functions can be called with "One" postfix (e.g. updateOne) to make them return only the first row of the result.
epg = require "easy-pg"
client = epg "pg://postgres@localhost/myapp_test"
# db contains table "numbers" with column "number"
# table, value
# returns array of inserted rows
client.insert "numbers", {number: 0} # insert one row
client.insert "numbers", {number: 4}, (err, res) -> # do sth. in callback...
client.insert "numbers", [{number: 1}, {number: 2}, {number: 3}] # insert 3 rows
client.insert "numbers", [{number: 1}, {number: 2}, {number: 3}], (err, res) -> # do sth. in callback...
# table, value, where
# returns array of updated rows
client.update "numbers", {number: 99}, "number = 0" # replaces number 0 by 99
client.update "numbers", {number: 99}, "number = 0", (err, res) -> # do sth. in callback...
client.update "numbers", {number: 99}, "number = $1", [1] # replaces number 1 by 99
client.update "numbers", {number: 99}, "number = $1", [1], (err, res) -> # do sth. in callback...
# table, value, where
# returns object with .operation (insert/update) and .rows[] (array of rows)
client.upsert "numbers", {number: 9}, "number = 9" # inserts number 9
client.upsert "numbers", {number: 9}, "number = 9", (err, res) -> # do sth. in callback...
client.upsert "numbers", {number: 9}, "number = $1", [9] # replaces number 9 by 9
client.upsert "numbers", {number: 9}, "number = $1", [9], (err, res) -> # do sth. in callback...
# table
# returns array of deleted rows
client.delete "numbers" # deletes table "numbers"
client.delete "numbers", (err, res) -> # do sth. in callback...
client.delete "numbers", "number = 0" # deletes rows with 0
client.delete "numbers", "number = 0", (err, res) -> # do sth. in callback...
client.delete "numbers", "number = $1", [1] # deletes rows with 1
client.delete "numbers", "number = $1", [1], (err, res) -> # do sth. in callback...
# offset, limit, columns, query result (table), orderBy
# returns object with offsets and array of rows in .data[]
client.paginate 0, 10, "number", "numbers", "_id" # lists first 10 rows of the given table
client.paginate 0, 10, "number", "numbers", "_id", (err, res) -> # do sth. in callback...
client.paginate 0, 10, "_id, number", "numbers WHERE _id > $1", "_id", [9] # the same with ids > 9
client.paginate 0, 10, "_id, number", "numbers WHERE _id > $1", "_id", [9], (err, res) -> # do sth. in callback...###Transactions
Transactions are also carefully handled by easy-pg. Once the transaction is started, all queries are saved into transaction stack until the final commit or rollback is called. In the case of temporary connection loss or other minor error, whole transaction is revived and processed again. Following functions can be used to control the transaction flow:
- begin
- savepoint
- commit
- rollback
See the source code below to understand the use of these functions.
epg = require "easy-pg"
client = epg "pg://postgres@localhost/myapp_test"
client.begin() # begins transaction, client.query "BEGIN" can be used instead
client.begin (err, res) -> # do sth. in callback...
client.savepoint "my_savepoint" # creates savepoint for rollback to savepoint
client.savepoint "my_savepoint", (err, res) -> # do sth. in callback...
client.commit() # commits changes in db
client.commit (err, res) -> # do sth. in callback...
client.rollback() # rolls back to closest begin
client.rollback (err, res) -> # do sth. in callback...
client.rollback "my_savepoint" # rolls back to "my_savepoint"
client.rollback "my_savepoint", (err, res) -> # do sth. in callback...Stacks are used to allow the client proper handling of nested transactions! Pseudocode below shows an example of succesfully revived transaction.
COMMANDS STACK
begin B
query1 QB
begin BQB
query2 QBQB
query3 QQBQB
rollback QB
query4 QQB <-- connection err
commit
---- restart ----
begin B
query1 QB
query4 QQB
commit
###Acceptable Errors
Minor errors were mentioned in the text above. All messages sent by PostgreSQL server contain error codes to inform client about the state of the database. Most of these codes are not handled, just forwarded through callback-err, except of 3 error code classes:
- 00 Successful Completion
- 08 Connection Exception, 08P01 (Protocol Violation) is excluded
- 57 Operator Intervention
These 3 types of errors only forces the client to restart current connection and continue in query queue processing later. More information about PostgreSQL error codes can be found here.
###Notes and Tips
Sometimes, pg returns null instead of date-time values. It's not a mistake, it really does. To solve this issue, simply append following option into easy-pg connection string:
"?dateStyle=iso, mdy"
Easy-pg doesn't support queries containing IN and binded array of parameters right now, but you can use akin query instead.
epg.queryAll "SELECT * FROM numbers WHERE number IN ($1)", [[1, 2, 3]], () -> ... not supported
epg.queryAll "SELECT * FROM numbers WHERE number = ANY ($1)", [[1, 2, 3]], () -> ... works well