Add row-level locking options

src/bookshelf.js

@@ -193,6 +193,11 @@ function Bookshelf(knex) {
      * resolve when the transaction is committed, or fail if the transaction is
      * rolled back.
      *
+     * When fetching inside a transaction it's possible to specify a row-level
+     * lock by passing the wanted lock type in the `lock` option to
+     * {@linkcode Model#fetch fetch}. Available options are `forUpdate` and
+     * `forShare`.
+     *
      *     var Promise = require('bluebird');
      *
      *     Bookshelf.transaction(function(t) {

src/collection.js

@@ -214,8 +214,12 @@ const BookshelfCollection = CollectionBase.extend({
    *   Model.NotFoundError NotFoundError} if no result is found.
    * @param {(string|string[])} [options.columns='*']
    *   Limit the number of columns fetched.
-   * @param {Transaction} options.transacting
+   * @param {Transaction} [options.transacting]
    *  Optionally run the query in a transaction.
+   * @param {string} [options.lock]
+   *  Type of row-level lock to use. Valid options are `forShare` and
+   *  `forUpdate`. This only works in conjunction with the `transacting`
+   *  option, and requires a database that supports it.
    *
    * @throws {Model.NotFoundError}
    * @returns {Promise<Model|null>}
@@ -240,6 +244,10 @@ const BookshelfCollection = CollectionBase.extend({
    *  @param {string|string[]} relations The relation, or relations, to be loaded.
    *  @param {Object=}      options Hash of options.
    *  @param {Transaction=} options.transacting
+   *  @param {string=} options.lock
+   *  Type of row-level lock to use. Valid options are `forShare` and
+   *  `forUpdate`. This only works in conjunction with the `transacting`
+   *  option, and requires a database that supports it.
    *
    *  @returns {Promise<Collection>} A promise resolving to this {@link
    *  Collection collection}

src/model.js

@@ -657,6 +657,10 @@ const BookshelfModel = ModelBase.extend({
    *   Specify columns to be retrieved.
    * @param {Transaction} [options.transacting]
    *  Optionally run the query in a transaction.
+   * @param {string} [options.lock]
+   *  Type of row-level lock to use. Valid options are `forShare` and
+   *  `forUpdate`. This only works in conjunction with the `transacting`
+   *  option, and requires a database that supports it.
    * @param {string|Object|mixed[]} [options.withRelated]
    *  Relations to be retrieved with `Model` instance. Either one or more
    *  relation names or objects mapping relation names to query callbacks.
@@ -859,6 +863,10 @@ const BookshelfModel = ModelBase.extend({
    * @param {Object=}      options Hash of options.
    * @param {Transaction=} options.transacting
    *   Optionally run the query in a transaction.
+   * @param {string=} options.lock
+   *  Type of row-level lock to use. Valid options are `forShare` and
+   *  `forUpdate`. This only works in conjunction with the `transacting`
+   *  option, and requires a database that supports it.
    * @returns {Promise<Model>} A promise resolving to this {@link Model model}
    */
   load: Promise.method(function(relations, options) {

src/sync.js

@@ -4,6 +4,7 @@ import _ from 'lodash';
 import Promise from './base/promise';
 
 const supportsReturning = (client) => _.includes(['postgresql', 'postgres', 'pg', 'oracle', 'mssql'], client)
+const validLocks = ['forShare', 'forUpdate']
 
 // Sync is the dispatcher for any database queries,
 // taking the "syncing" `model` or `collection` being queried, along with
@@ -16,7 +17,10 @@ const Sync = function(syncing, options) {
   this.syncing = syncing.resetQuery();
   this.options = options;
   if (options.debug) this.query.debug();
-  if (options.transacting) this.query.transacting(options.transacting);
+  if (options.transacting) {
+    this.query.transacting(options.transacting);
+    if (validLocks.indexOf(options.lock) > -1) this.query[options.lock]();
+  }
   if (options.withSchema) this.query.withSchema(options.withSchema);
 };
 

test/integration/model.js

@@ -446,6 +446,56 @@ module.exports = function(bookshelf) {
           expect(author.get('name')).to.eql('Ryan Coogler');
         })
       })
+
+      it('locks the table when called with the forUpdate option during a transaction', function() {
+        var newAuthorId;
+
+        return new Models.Author().save({first_name: 'foo', site_id: 1}).then(function(author) {
+          newAuthorId = author.id;
+
+          return Promise.all([
+            bookshelf.transaction(function(t) {
+              return new Models.Author({id: author.id}).fetch({transacting: t, lock: 'forUpdate'}).then(function() {
+                return Promise.delay(100)
+              }).then(function() {
+                return new Models.Author({id: author.id}).fetch({transacting: t})
+              }).then(function(author) {
+                expect(author.get('first_name')).to.equal('foo')
+              })
+            }),
+            Promise.delay(25).then(function() {
+              return new Models.Author({id: author.id}).save({first_name: 'changed'})
+            })
+          ])
+        }).then(function() {
+          return new Models.Author({id: newAuthorId}).destroy()
+        })
+      })
+
+      it('locks the table when called with the forShare option during a transaction', function() {
+        var newAuthorId;
+
+        return new Models.Author().save({first_name: 'foo', site_id: 1}).then(function(author) {
+          newAuthorId = author.id;
+
+          return Promise.all([
+            bookshelf.transaction(function(t) {
+              return new Models.Author({id: author.id}).fetch({transacting: t, lock: 'forShare'}).then(function() {
+                return Promise.delay(100)
+              }).then(function() {
+                return new Models.Author({id: author.id}).fetch({transacting: t})
+              }).then(function(author) {
+                expect(author.get('first_name')).to.equal('foo')
+              })
+            }),
+            Promise.delay(25).then(function() {
+              return new Models.Author({id: author.id}).save({first_name: 'changed'})
+            })
+          ])
+        }).then(function() {
+          return new Models.Author({id: newAuthorId}).destroy()
+        })
+      })
     });
 
     describe('fetchAll', function() {

test/unit/sql/sync.js

@@ -58,6 +58,34 @@ module.exports = function() {
       setSchema.should.have.been.calledWith(testSchema);
     })
 
+    it('accepts a lock option option if called with a transaction', function() {
+      var setLock = sinon.spy();
+      var mockModel = {
+        query: function() {
+          return {forUpdate: setLock, transacting: function() {}}
+        },
+        resetQuery: function() {}
+      }
+
+      new Sync(mockModel, {lock: 'forUpdate', transacting: 'something'});
+
+      setLock.should.have.been.called;
+    })
+
+    it('ignores the lock option if called without a transaction', function() {
+      var setLock = sinon.spy();
+      var mockModel = {
+        query: function() {
+          return {forUpdate: setLock, transacting: function() {}}
+        },
+        resetQuery: function() {}
+      }
+
+      new Sync(mockModel, {lock: 'forUpdate'});
+
+      setLock.should.not.have.been.called;
+    })
+
     describe('prefixFields', function() {
       it('should prefix all keys of the passed in object with the tablename', function() {
         var sync = new Sync(stubModel());