any-db-transaction - npm Package Compare versions

Comparing version 2.2.0 to 2.2.1

package.json

 {
   "name": "any-db-transaction",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Transaction object for Any-DB adapters",
@@ -5,0 +5,0 @@ "main": "transaction.js",

README.md

@@ -57,3 +57,3 @@ # any-db-transaction
 
-Any queries that error during a transaction will cause an automatic rollback.
+By default, any queries that error during a transaction will cause an automatic rollback.
 If a query has no callback, the transaction will also handle (and re-emit)
@@ -98,2 +98,60 @@ `'error'` events for the [Query][] instance. This enables handling errors for
 
+
+#### Automatic Rollback on Error
+
+As stated previously, by default any queries that error during a transaction
+will cause an automatic rollback. This is to support the common pattern in which
+a transaction is a series of queries you either want to succeed or fail
+atomically.
+
+There is another common pattern for transactions where you either create or
+update a record. Many databases support an `INSERT OR REPLACE` statement, but
+quite often you'd like an `INSERT OR UPDATE` construct instead.
+
+Intuitively, a transaction can be used for this as well:
+
+1. Start a transaction
+1. Try an insert statement
+ - If that succeeds, commit.
+ - Otherwise, continue
+1. Try an update statement.
+  - If that succeeds, commit.
+  - Otherwise, roll back the transaction.
+
+A transaction is unlikely to be the best choice here. The results of the first
+statement need to make it back to the client before it can decide whether to
+commit or try something else. Usually databases better support this kind of
+construct with nested queries, which avoid those roundtrips.
+
+To facilitate this kind transaction use, automatic rollback of transactions
+can be disabled.
+
+```javascript
+var tx = begin(conn, {autoRollback: false});
+tx.query('Query that produces errors', function(err) {
+    tx.query('another query');
+});
+```
+
+**Note**: PostgreSQL does not allow you to use a transaction immediately after
+an error. However, you can get much the same behaviour by explicitly adding
+`SAVEPOINT` statements. A transaction with an error can be rolled back to a
+known good savepoint, and can be used from there onwards. You can achieve the
+same by using nested transactions.
+
+```javascript
+var tx = begin(conn, {autoRollback: false});
+var sp = begin(tx);
+sp.query('query that might fail', function(err) {
+  if (err) {
+    tx.query('alternate queries');
+  } else {
+    sp.commit();
+  }
+});
+```
+
+Note that the failing query is performed on the "savepoint" child transaction,
+but the final query is perfomed on the outer/parent transaction.
+
 ### Transaction states
@@ -100,0 +158,0 @@

transaction.js

@@ -25,3 +25,3 @@ var inherits = require('inherits')
   if (queryable instanceof Transaction) {
-    return beginWithParent(queryable, callback)
+    return beginWithParent(queryable, options, callback)
   }
@@ -238,4 +238,4 @@
 
-function beginWithParent (parent, callback) {
-  var child = createChildTransaction(parent, callback)
+function beginWithParent (parent, options, callback) {
+  var child = createChildTransaction(parent, options, callback)
   switch (parent.state()) {
@@ -259,3 +259,3 @@ case 'disconnected':
 
-function createChildTransaction (parent, callback) {
+function createChildTransaction (parent, options, callback) {
   var nestingLevel = parent._nestingLevel + 1
@@ -271,2 +271,3 @@ var savepointName = 'sp_' + nestingLevel
     rollback:     'ROLLBACK TO '       + savepointName,
+    autoRollback: options.autoRollback,
   })
@@ -273,0 +274,0 @@

No alert changes

Improved metrics

Total package byte prevSize

30113

7.03%

Number of lines in readme file

340

20.57%

Worsened metrics

Lines of code

548

-0.72%

No dependency changes