feat(postgres): returning option for arithmetic queries (#8727) (#8748)

docs/instances.md

@@ -300,7 +300,10 @@ First of all you can define a field and the value you want to add to it.
 ```js
 User.findById(1).then(user => {
   return user.increment('my-integer-field', {by: 2})
-}).then(/* ... */)
+}).then(user => {
+  // Postgres will return the updated user by default (unless disabled by setting { returning: false })
+  // In other dialects, you'll want to call user.reload() to get the updated instance...
+})
 ```
 
 Second, you can define multiple fields and the value you want to add to them.
@@ -331,7 +334,10 @@ First of all you can define a field and the value you want to add to it.
 ```js
 User.findById(1).then(user => {
   return user.decrement('my-integer-field', {by: 2})
-}).then(/* ... */)
+}).then(user => {
+  // Postgres will return the updated user by default (unless disabled by setting { returning: false })
+  // In other dialects, you'll want to call user.reload() to get the updated instance...
+})
 ```
 
 Second, you can define multiple fields and the value you want to add to them.

lib/dialects/abstract/query-generator.js

@@ -388,13 +388,16 @@ const QueryGenerator = {
    @private
   */
   arithmeticQuery(operator, tableName, attrValueHash, where, options, attributes) {
+    options = options || {};
+    _.defaults(options, { returning: true });
+
     attrValueHash = Utils.removeNullValuesFromHash(attrValueHash, this.options.omitNull);
 
     const values = [];
     let query = 'UPDATE <%= table %> SET <%= values %><%= output %> <%= where %>';
     let outputFragment;
 
-    if (this._dialect.supports.returnValues) {
+    if (this._dialect.supports.returnValues && options.returning) {
       if (this._dialect.supports.returnValues.returning) {
         options.mapToModel = true;
         query += ' RETURNING *';

lib/model.js

@@ -3904,7 +3904,7 @@ class Model {
    * ```sql
    * SET column = column + X
    * ```
-   * query. To get the correct value after an increment into the Instance you should do a reload.
+   * query. The updated instance will be returned by default in Postgres. However, in other dialects, you will need to do a reload to get the new values.
    *
    *```js
   * instance.increment('number') // increment number by 1
@@ -3921,6 +3921,7 @@ class Model {
   * @param {Function} [options.logging=false] A function that gets executed while running the query to log the sql.
   * @param {Transaction} [options.transaction]
   * @param  {String}       [options.searchPath=DEFAULT] An optional parameter to specify the schema search_path (Postgres only)
+  * @param {Boolean} [options.returning=true] Append RETURNING * to get back auto generated values (Postgres only)
   *
   * @return {Promise<this>}
   * @since 4.0.0
@@ -3940,7 +3941,7 @@ class Model {
    * ```sql
    * SET column = column - X
    * ```
-   * query. To get the correct value after an decrement into the Instance you should do a reload.
+   * query. The updated instance will be returned by default in Postgres. However, in other dialects, you will need to do a reload to get the new values.
    *
    * ```js
    * instance.decrement('number') // decrement number by 1
@@ -3957,6 +3958,7 @@ class Model {
    * @param {Function} [options.logging=false] A function that gets executed while running the query to log the sql.
    * @param {Transaction} [options.transaction]
    * @param  {String}       [options.searchPath=DEFAULT] An optional parameter to specify the schema search_path (Postgres only)
+   * @param {Boolean} [options.returning=true] Append RETURNING * to get back auto generated values (Postgres only)
    *
    * @return {Promise}
    */

test/integration/instance.test.js

@@ -156,6 +156,9 @@ describe(Support.getTestDialectTeaser('Instance'), () => {
         return this.User.findById(1).then(user1 => {
           return user1.increment('aNumber', { by: 2 }).then(() => {
             expect(user1.aNumber).to.be.equal(2);
+            return user1.increment('bNumber', { by: 2, returning: false }).then(user3 => {
+              expect(user3.bNumber).to.be.equal(0);
+            });
           });
         });
       });
@@ -323,6 +326,9 @@ describe(Support.getTestDialectTeaser('Instance'), () => {
         return this.User.findById(1).then(user1 => {
           return user1.decrement('aNumber', { by: 2 }).then(() => {
             expect(user1.aNumber).to.be.equal(-2);
+            return user1.decrement('bNumber', { by: 2, returning: false }).then(user3 => {
+              expect(user3.bNumber).to.be.equal(0);
+            });
           });
         });
       });

test/unit/dialects/postgres/query-generator.test.js

@@ -26,6 +26,11 @@ if (dialect.match(/^postgres/)) {
           expectation: 'UPDATE "myTable" SET "foo"="foo"+ \'bar\' WHERE "bar" = \'biz\' RETURNING *'
         },
         {
+          title: 'Should use the plus operator without returning clause',
+          arguments: ['+', 'myTable', { foo: 'bar' }, {}, { returning: false }],
+          expectation: 'UPDATE "myTable" SET "foo"="foo"+ \'bar\' '
+        },
+        {
           title: 'Should use the minus operator',
           arguments: ['-', 'myTable', { foo: 'bar' }, {}, {}],
           expectation: 'UPDATE "myTable" SET "foo"="foo"- \'bar\'  RETURNING *'
@@ -39,6 +44,11 @@ if (dialect.match(/^postgres/)) {
           title: 'Should use the minus operator with where clause',
           arguments: ['-', 'myTable', { foo: 'bar' }, { bar: 'biz'}, {}],
           expectation: 'UPDATE "myTable" SET "foo"="foo"- \'bar\' WHERE "bar" = \'biz\' RETURNING *'
+        },
+        {
+          title: 'Should use the minus operator without returning clause',
+          arguments: ['-', 'myTable', { foo: 'bar' }, {}, { returning: false }],
+          expectation: 'UPDATE "myTable" SET "foo"="foo"- \'bar\' '
         }
       ],
       attributesToSQL: [