postgres-nest-transaction
Nest transactions easily with PostgreSQL & Node.js. Designed for use with pg on npm.
Install
$ npm install pg-nest
Example
pg = require 'pg'Transaction = require 'pg-nest'url = "postgres://user:password@localhost:5432/db" # Retrieve a pooled client connection. pgconnect url # Create a new transaction with the pooled pg client. t = clientdone # Start a new transaction with auto savepoint, and insert our hero! tstart tquery "INSERT INTO Characters VALUES ('Finn', 'human')" # Create a nested subtransaction with savepoint, and continue... tnest t2query "INSERT INTO Characters VALUES ('Ice King', 'wizard')" # Wrong character! ~_~ Cancel the subtransaction to rollback. t2cancel # Commit our work on the parent transaction. tfinish consolelog 'Saved Finn!' unless err
API Overview
Class: Transaction | |
---|---|
Constructor | |
new Transaction( client, done ) |
Creates a new transaction, using a pooled pg client. |
Start / Nest | |
transaction.start(cb(err)) |
Starts a new transaction, with auto savepoint |
transaction.nest(cb(err, nested)) |
Starts a nested subtransaction, with auto savepoint. |
Query | |
transaction.query(args..., cb(err, result)) |
Syntactic sugar for client.query(). |
Restart / Cancel | |
transaction.restart(cb(err)) |
Restarts this transaction by rolling back to its savepoint. |
transaction.cancel(cb(err)) |
Cancels this transaction, but allows any parents to continue. |
transaction.cancelAll(cb(err)) |
Cancels both this transaction and all parents. |
Finish / Finalize | |
transaction.finish(cb(err)) |
Completes work on this transaction. |
transaction.finalize(lastErr, cb(err)) |
Completes or cancels, depending on an error status. |
API
new Transaction(client, done)
Creates a new transaction, using a pooled pg client.
pg = require 'pg'Transaction = require 'pg-nest' pgconnect url t = clientdone
Just pass the client instance and done() function
provided by pg.connect().
When the transaction completes, it will automatically release the
client by calling done().
See the pg docs on
pg.connect()
for details.
start(callback(err))
Starts the new (or nested) transaction, with an auto savepoint.
t = clientdonetstart tquery "SELECT * FROM Characters" consolelog resultrows
nest(callback(err, nested))
Starts a nested subtransaction, with its own savepoint.
Since PostgreSQL lacks true subtransactions, this module simulates them with savepoints.
t = clientdonetstart tnest t2query "SELECT * FROM Characters" consolelog resultrows
query(text, callback(err, result))
query(text, values, callback(err, result))
query(config, callback(err, result))
Syntactic sugar for pg's client.query().
The pg module's client.query() is quite versatile, supporting simple or parameterized queries, and prepared statements.
query = "SELECT * FROM Characters"tquery query consolelog resultrows
See the pg docs on Client.query()
for details.
Params
text
String The query text (for simple queries).values
Array An array of values (for parameterized queries).config
Object A configuration object (for parameterized queries or prepared statements).callback(err, result)
Function Called with the query result or error.
restart(callback(err))
Restarts this transaction by rolling back to its savepoint.
When called on subtransactions, only the subtransaction is undone.
# Start transaction tstart consolelog "Started!" # Run queries... # Restart to rollback to savepoint trestart consolelog "Restarted!"
cancel(callback(err))
Cancels this transaction, but allows any parents to continue.
tcancel consolelog "Canceled this transaction."
cancelAll(callback(err))
Cancels this transaction (and any parents) completely.
tcancelAll consolelog "Canceled this and parent transactions!"
finish(callback(err))
Completes work on this transaction.
This commits if called on a top-level transaction, or just releases the savepoint if called on a subtransaction.
tfinish consolelog "Committed the transaction" unless err
finalize(lastErr, callback(err))
Finalizes (finish or cancel) this transaction depending on a final error.
Simply a convenience to replace branching calls to .cancel() or finish().
Just give finalize() your last error, and it branches for you.
It propagates any error to the callback, including lastErr.
Instead of this:
tquery "INSERT INTO Foo VALUES ('bar', 'baz');" if lastErr tcancel consolelog 'error!' doLastThing else tfinish consolelog 'done!' doLastThing
You can write:
tquery "INSERT INTO Foo VALUES ('bar', 'baz');" tfinalize lastErr consolelog if err then 'error!' else 'done!' doLastThing
Params
lastErr
Error If present then .cancel(), otherwise .finish().callback(err)
Function Called on completion or error.
License
MIT