Merge pull request #2990 from janmeier/rawquery

Revamped raw query handling

.gitignore

@@ -7,5 +7,6 @@ npm-debug.log
 *~
 *~
 test/binary/tmp/*
 test/binary/tmp/*
 test/tmp/*
 test/tmp/*
+test/dialects/sqlite/test.sqlite
 test/sqlite/test.sqlite
 test/sqlite/test.sqlite
 coverage-*
 coverage-*

changelog.md

 # Next
 # Next
 - [BUG] Fixed `field` support for `increment` and `decrement`.
 - [BUG] Fixed `field` support for `increment` and `decrement`.
+- [FEATURE/BUG] Raw queries always return all results (including affected rows etc). This means you should change all promise listeners on `sequelize.query` to use `.spread` instead of `.then`, unless you are passing a query type.
+
+#### Backwards compatability changes
+- The default query type for `sequelize.query` is now `RAW` - this means that two arguments (results and metadata) will be returned by default and you should use `.spread`
+- The 4th argument to `sequelize.query` has been deprecated in favor of `options.replacements`
 
 
 # 2.0.0-rc8
 # 2.0.0-rc8
 - [FEATURE] CLS Support. CLS is also used to automatically pass the transaction to any calls within the callback chain when using `sequelize.transaction(function() ...`.
 - [FEATURE] CLS Support. CLS is also used to automatically pass the transaction to any calls within the callback chain when using `sequelize.transaction(function() ...`.

docs/docs/raw-queries.md

+As there are often use cases in which it is just easier to execute raw / already prepared SQL queries, you can utilize the function `sequelize.query`.
+
+By default the function will return two arguments - a results array, and an object containing metadata (affected rows etc.). Note that since this is a raw query, the metadata (property names etc.) is dialect specific. Some dialects return the metadata "within" the results object (as properties on an array). However, two arguments will always be returned, but for MSSQL and MySQL it will be two references to the same object.
+
+```js
+sequelize.query("UPDATE users SET y = 42 WHERE x = 12").spread(function(results, metadata) {
+  // Results will be an empty array and metadata will contain the number of affected rows.
+})
+```
+
+In cases where you don't need to access the metadata you can pass in a query type to tell sequelize how to format the results. For example, for a simple select query you could do: 
+
+```js
+sequelize.query("SELECT * FROM `users`", { type: sequelize.QueryTypes.SELECT})
+  .then(function(users) {
+    // We don't need spread here, since only the results will be returned for select queries
+  })
+```
+
+Several other query types are available. [Peek into the source for details](https://github.com/sequelize/sequelize/blob/master/lib/query-types.js)
+
+A second, optional, argument is the _callee_, which is a model. If you pass a model the returned data will be instances of that model.
+
+```js
+// Callee is the model definition. This allows you to easily map a query to a predefined model
+sequelize.query('SELECT * FROM projects', Projects).then(function(projects){
+  // Each record will now be a instance of Project
+})
+```
+
+# Replacements
+Replacements in a query can be done in two different ways, either using named parameters (starting with `:`), or unnamed, represented by a `?`. Replacements are passed in the options object.
+
+* If an array is passed, `?` will be replaced in the order that they appear in the array
+* If an object is passed, `:key` will be replaced with the keys from that object. If the object contains keys not found in the query or vice verca, an exception will be thrown.
+
+```js
+sequelize.query('SELECT * FROM projects WHERE status = ?', 
+  { replacements: ['active'], type: sequelize.QueryTypes.SELECT }
+).then(function(projects) {
+  console.log(projects)
+})
+
+sequelize.query('SELECT * FROM projects WHERE status = :status ', 
+  { replacements: { status: 'active', type: sequelize.QueryTypes.SELECT }}
+).then(function(projects) {
+  console.log(projects)
+})
+```

docs/docs/usage.md

@@ -225,9 +225,9 @@ var sequelize = new Sequelize('database', 'username', 'password', {
 
 
 ## Executing raw SQL queries
 ## Executing raw SQL queries
 
 
-As there are often use cases in which it is just easier to execute raw / already prepared SQL queries, you can utilize the function`sequelize.query`.
+As there are often use cases in which it is just easier to execute raw / already prepared SQL queries, you can utilize the function `sequelize.query`.
 
 
-Here is how it works:
+Here is how it works:
     
     
 ```js
 ```js
 // Arguments for raw queries
 // Arguments for raw queries
@@ -324,4 +324,4 @@ sequelize.query('select 1 as `foo.bar.baz`').success(function(rows) {
 
 
 
 
 
 
-[0]: /docs/latest/usage#options
+[0]: /docs/latest/usage#options
\ No newline at end of file

lib/dialects/abstract/query.js

@@ -83,6 +83,10 @@ module.exports = (function() {
     }
     }
   };
   };
 
 
+  AbstractQuery.prototype.isRawQuery = function () {
+    return this.options.type === QueryTypes.RAW;
+  };
+
   AbstractQuery.prototype.isVersionQuery = function () {
   AbstractQuery.prototype.isVersionQuery = function () {
     return this.options.type === QueryTypes.VERSION;
     return this.options.type === QueryTypes.VERSION;
   };
   };
@@ -137,6 +141,10 @@ module.exports = (function() {
     return this.options.type === QueryTypes.SHOWINDEXES;
     return this.options.type === QueryTypes.SHOWINDEXES;
   };
   };
 
 
+  AbstractQuery.prototype.isDescribeQuery = function () {
+    return this.options.type === QueryTypes.DESCRIBE;
+  };
+
   AbstractQuery.prototype.isSelectQuery = function() {
   AbstractQuery.prototype.isSelectQuery = function() {
     return this.options.type === QueryTypes.SELECT;
     return this.options.type === QueryTypes.SELECT;
   };
   };
@@ -149,7 +157,15 @@ module.exports = (function() {
     return this.options.type === QueryTypes.BULKDELETE;
     return this.options.type === QueryTypes.BULKDELETE;
   };
   };
 
 
+  AbstractQuery.prototype.isForeignKeysQuery = function() {
+    return this.options.type === QueryTypes.FOREIGNKEYS;
+  };
+
   AbstractQuery.prototype.isUpdateQuery = function() {
   AbstractQuery.prototype.isUpdateQuery = function() {
+    if (this.options.type === QueryTypes.UPDATE) {
+      return true;
+    }
+
     return (this.sql.toLowerCase().indexOf('update') === 0);
     return (this.sql.toLowerCase().indexOf('update') === 0);
   };
   };
 
 
@@ -167,15 +183,12 @@ module.exports = (function() {
           }
           }
         }
         }
 
 
-        return o;
-      });
-
-      if (this.options.nest) {
-        result = result.map(function(entry){
-          return Dot.transform(entry);
-        });
-      }
+        if (this.options.nest) {
+          o = Dot.transform(o);
+        }
 
 
+        return o;
+      }, this);
     // Queries with include
     // Queries with include
     } else if (this.options.hasJoin === true) {
     } else if (this.options.hasJoin === true) {
       results = groupJoinData(results, {
       results = groupJoinData(results, {

lib/dialects/mssql/query.js

@@ -129,23 +129,20 @@ module.exports = (function() {
 
 
     if (this.isShowTablesQuery()) {
     if (this.isShowTablesQuery()) {
       result = this.handleShowTablesQuery(data);
       result = this.handleShowTablesQuery(data);
-    } else if (this.isShowOrDescribeQuery()) {
-      result = data;
-      if (this.sql.toLowerCase().indexOf("select c.column_name as 'name', c.data_type as 'type', c.is_nullable as 'isnull'") === 0) {
-        result = {};
-        data.forEach(function(_result) {
-          if (_result.Default)
-            _result.Default = _result.Default.replace('(\'','').replace('\')','').replace(/'/g,'');
-
-          result[_result.Name] = {
-            type: _result.Type.toUpperCase(),
-            allowNull: (_result.IsNull === 'YES' ? true : false),
-            defaultValue: _result.Default
-          };
-        });
-      } else if (this.isShowIndexesQuery()) {
-        result = this.handleShowIndexesQuery(data);
-      }
+    } else if (this.isDescribeQuery()) {
+      result = {};
+      data.forEach(function(_result) {
+        if (_result.Default)
+          _result.Default = _result.Default.replace('(\'','').replace('\')','').replace(/'/g,'');
+
+        result[_result.Name] = {
+          type: _result.Type.toUpperCase(),
+          allowNull: (_result.IsNull === 'YES' ? true : false),
+          defaultValue: _result.Default
+        };
+      });
+    } else if (this.isShowIndexesQuery()) {
+      result = this.handleShowIndexesQuery(data);
     } else if (this.isSelectQuery()) {
     } else if (this.isSelectQuery()) {
       result = this.handleSelectQuery(data);
       result = this.handleSelectQuery(data);
     } else if (this.isCallQuery()) {
     } else if (this.isCallQuery()) {
@@ -156,7 +153,12 @@ module.exports = (function() {
       result = data[0] && data[0].AFFECTEDROWS;
       result = data[0] && data[0].AFFECTEDROWS;
     } else if (this.isVersionQuery()) {
     } else if (this.isVersionQuery()) {
       result = data[0].version;
       result = data[0].version;
-    }
+    } else if (this.isForeignKeysQuery()) {
+      result = data;
+    } else if (this.isRawQuery()) {
+      // MSSQL returns row data and metadata (affected rows etc) in a single object - let's standarize it, sorta
+      result = [data, data];
+     }
 
 
     return result;
     return result;
   };
   };

lib/dialects/mysql/query.js

@@ -76,28 +76,30 @@ module.exports = (function() {
       result = this.handleSelectQuery(data);
       result = this.handleSelectQuery(data);
     } else if (this.isShowTablesQuery()) {
     } else if (this.isShowTablesQuery()) {
       result = this.handleShowTablesQuery(data);
       result = this.handleShowTablesQuery(data);
-    } else if (this.isShowOrDescribeQuery()) {
-      result = data;
-
-      if (this.sql.toLowerCase().indexOf('describe') === 0) {
-        result = {};
+    } else if (this.isDescribeQuery()) {
+      result = {};
+
+      data.forEach(function(_result) {
+        result[_result.Field] = {
+          type: _result.Type.toUpperCase(),
+          allowNull: (_result.Null === 'YES'),
+          defaultValue: _result.Default
+        };
+      });
+    } else if (this.isShowIndexesQuery()) {
+      result = this.handleShowIndexesQuery(data);
 
 
-        data.forEach(function(_result) {
-          result[_result.Field] = {
-            type: _result.Type.toUpperCase(),
-            allowNull: (_result.Null === 'YES'),
-            defaultValue: _result.Default
-          };
-        });
-      } else if (this.isShowIndexesQuery()) {
-        result = this.handleShowIndexesQuery(data);
-      }
     } else if (this.isCallQuery()) {
     } else if (this.isCallQuery()) {
       result = data[0];
       result = data[0];
     } else if (this.isBulkUpdateQuery() || this.isBulkDeleteQuery() || this.isUpsertQuery()) {
     } else if (this.isBulkUpdateQuery() || this.isBulkDeleteQuery() || this.isUpsertQuery()) {
       result = data.affectedRows;
       result = data.affectedRows;
     } else if (this.isVersionQuery()) {
     } else if (this.isVersionQuery()) {
       result = data[0].version;
       result = data[0].version;
+    } else if (this.isForeignKeysQuery()) {
+      result = data;
+    } else if (this.isRawQuery()) {
+      // MySQL returns row data and metadata (affected rows etc) in a single object - let's standarize it, sorta
+      result = [data, data];
     }
     }
 
 
     return result;
     return result;

lib/dialects/postgres/query-generator.js

@@ -869,8 +869,6 @@ module.exports = (function() {
       return dataType;
       return dataType;
     },
     },
 
 
-
-
     quoteIdentifier: function(identifier, force) {
     quoteIdentifier: function(identifier, force) {
       var _ = Utils._;
       var _ = Utils._;
       if (identifier === '*') return identifier;
       if (identifier === '*') return identifier;

lib/dialects/postgres/query.js

@@ -147,62 +147,60 @@ module.exports = (function() {
         });
         });
         return result;
         return result;
       } else if (self.isSelectQuery()) {
       } else if (self.isSelectQuery()) {
-        if (self.sql.toLowerCase().indexOf('select c.column_name') === 0) {
-          result = {};
-
-          rows.forEach(function(_result) {
-            result[_result.Field] = {
-              type: _result.Type.toUpperCase(),
-              allowNull: (_result.Null === 'YES'),
-              defaultValue: _result.Default,
-              special: (!!_result.special ? self.sequelize.queryInterface.QueryGenerator.fromArray(_result.special) : [])
-            };
+        // Postgres will treat tables as case-insensitive, so fix the case
+        // of the returned values to match attributes
+        if (self.options.raw === false && self.sequelize.options.quoteIdentifiers === false) {
+          var attrsMap = Utils._.reduce(self.callee.attributes, function(m, v, k) { m[k.toLowerCase()] = k; return m; }, {});
+          rows.forEach(function(row) {
+            Utils._.keys(row).forEach(function(key) {
+              var targetAttr = attrsMap[key];
+              if (targetAttr !== key) {
+                row[targetAttr] = row[key];
+                delete row[key];
+              }
+            });
+          });
+        }
 
 
-            if (result[_result.Field].type === 'BOOLEAN') {
-              result[_result.Field].defaultValue = { 'false': false, 'true': true }[result[_result.Field].defaultValue];
+        if (!!self.callee && !!self.callee._hasHstoreAttributes) {
+          rows.forEach(function(row) {
+            parseHstoreFields(self.callee, row);
+          });
+        }
 
 
-              if (result[_result.Field].defaultValue === undefined) {
-                result[_result.Field].defaultValue = null;
-              }
+        return self.handleSelectQuery(rows);
+      } else if (QueryTypes.DESCRIBE === self.options.type) {
+        result = {};
+
+        rows.forEach(function(_result) {
+          result[_result.Field] = {
+            type: _result.Type.toUpperCase(),
+            allowNull: (_result.Null === 'YES'),
+            defaultValue: _result.Default,
+            special: (!!_result.special ? self.sequelize.queryInterface.QueryGenerator.fromArray(_result.special) : [])
+          };
+
+          if (result[_result.Field].type === 'BOOLEAN') {
+            result[_result.Field].defaultValue = { 'false': false, 'true': true }[result[_result.Field].defaultValue];
+
+            if (result[_result.Field].defaultValue === undefined) {
+              result[_result.Field].defaultValue = null;
             }
             }
+          }
 
 
-            if (typeof result[_result.Field].defaultValue === 'string') {
-              result[_result.Field].defaultValue = result[_result.Field].defaultValue.replace(/'/g, '');
+          if (typeof result[_result.Field].defaultValue === 'string') {
+            result[_result.Field].defaultValue = result[_result.Field].defaultValue.replace(/'/g, '');
 
 
-              if (result[_result.Field].defaultValue.indexOf('::') > -1) {
-                var split = result[_result.Field].defaultValue.split('::');
-                if (split[1].toLowerCase() !== 'regclass)') {
-                  result[_result.Field].defaultValue = split[0];
-                }
+            if (result[_result.Field].defaultValue.indexOf('::') > -1) {
+              var split = result[_result.Field].defaultValue.split('::');
+              if (split[1].toLowerCase() !== 'regclass)') {
+                result[_result.Field].defaultValue = split[0];
               }
               }
             }
             }
-          });
-
-          return result;
-        } else {
-          // Postgres will treat tables as case-insensitive, so fix the case
-          // of the returned values to match attributes
-          if (self.options.raw === false && self.sequelize.options.quoteIdentifiers === false) {
-            var attrsMap = Utils._.reduce(self.callee.attributes, function(m, v, k) { m[k.toLowerCase()] = k; return m; }, {});
-            rows.forEach(function(row) {
-              Utils._.keys(row).forEach(function(key) {
-                var targetAttr = attrsMap[key];
-                if (targetAttr !== key) {
-                  row[targetAttr] = row[key];
-                  delete row[key];
-                }
-              });
-            });
-          }
-
-          if (!!self.callee && !!self.callee._hasHstoreAttributes) {
-            rows.forEach(function(row) {
-              parseHstoreFields(self.callee, row);
-            });
           }
           }
+        });
 
 
-          return self.handleSelectQuery(rows);
-        }
+        return result;
       } else if (self.isShowOrDescribeQuery()) {
       } else if (self.isShowOrDescribeQuery()) {
         return results;
         return results;
       } else if (QueryTypes.BULKUPDATE === self.options.type) {
       } else if (QueryTypes.BULKUPDATE === self.options.type) {
@@ -243,6 +241,8 @@ module.exports = (function() {
         return self.callee || (rows && ((self.options.plain && rows[0]) || rows)) || undefined;
         return self.callee || (rows && ((self.options.plain && rows[0]) || rows)) || undefined;
       } else if (self.isVersionQuery()) {
       } else if (self.isVersionQuery()) {
         return results[0].version;
         return results[0].version;
+      } else if (self.isRawQuery()) {
+        return [rows, result];
       } else {
       } else {
         return results;
         return results;
       }
       }

lib/dialects/sqlite/query.js

@@ -139,6 +139,8 @@ module.exports = (function() {
                     result = undefined;
                     result = undefined;
                   } else if (self.options.type === QueryTypes.VERSION) {
                   } else if (self.options.type === QueryTypes.VERSION) {
                     result = results[0].version;
                     result = results[0].version;
+                  } else if (self.options.type === QueryTypes.RAW) {
+                    result = [results, metaData];
                   }
                   }
 
 
                   resolve(result);
                   resolve(result);

lib/instance.js

@@ -831,7 +831,7 @@ module.exports = (function() {
    * @param {Integer} [options.by=1] The number to increment by
    * @param {Integer} [options.by=1] The number to increment by
    * @param {Transaction} [options.transaction]
    * @param {Transaction} [options.transaction]
    *
    *
-   * @return {Promise}
+   * @return {Promise<this>}
    */
    */
   Instance.prototype.increment = function(fields, countOrOptions) {
   Instance.prototype.increment = function(fields, countOrOptions) {
     Utils.validateParameter(countOrOptions, Object, {
     Utils.validateParameter(countOrOptions, Object, {
@@ -895,7 +895,7 @@ module.exports = (function() {
       }
       }
     }, this);
     }, this);
 
 
-    return this.QueryInterface.increment(this, this.Model.getTableName(countOrOptions), values, where, countOrOptions);
+    return this.QueryInterface.increment(this, this.Model.getTableName(countOrOptions), values, where, countOrOptions).return(this);
   };
   };
 
 
   /**
   /**

lib/model.js

@@ -725,7 +725,6 @@ module.exports = (function() {
       }
       }
     }).then(function() {
     }).then(function() {
       return this.QueryInterface.select(this, this.getTableName(options), options, Utils._.defaults({
       return this.QueryInterface.select(this, this.getTableName(options), options, Utils._.defaults({
-        type: QueryTypes.SELECT,
         hasJoin: hasJoin,
         hasJoin: hasJoin,
         tableNames: Object.keys(tableNames)
         tableNames: Object.keys(tableNames)
       }, queryOptions, { transaction: options.transaction }));
       }, queryOptions, { transaction: options.transaction }));
@@ -743,9 +742,7 @@ module.exports = (function() {
     // whereCollection is used for non-primary key updates
     // whereCollection is used for non-primary key updates
     this.options.whereCollection = options.where || null;
     this.options.whereCollection = options.where || null;
 
 
-    return this.QueryInterface.select(this, [[this.getTableName(options), this.name], joinTableName], options, Utils._.defaults({
-      type: QueryTypes.SELECT
-    }, queryOptions, { transaction: (options || {}).transaction }));
+    return this.QueryInterface.select(this, [[this.getTableName(options), this.name], joinTableName], options, Utils._.defaults(queryOptions, { transaction: (options || {}).transaction }));
   };
   };
 
 
  /**
  /**
@@ -1449,7 +1446,6 @@ module.exports = (function() {
 
 
     options.type = QueryTypes.BULKDELETE;
     options.type = QueryTypes.BULKDELETE;
 
 
-
     mapFieldNames.call(this, options, this);
     mapFieldNames.call(this, options, this);
 
 
     return Promise.try(function() {
     return Promise.try(function() {

lib/query-interface.js

@@ -46,12 +46,13 @@ module.exports = (function() {
     var self = this;
     var self = this;
 
 
     options = Utils._.extend({
     options = Utils._.extend({
-      raw: true
+      raw: true,
+      type: this.sequelize.QueryTypes.SELECT
     }, options || {});
     }, options || {});
 
 
     var showSchemasSql = self.QueryGenerator.showSchemasQuery();
     var showSchemasSql = self.QueryGenerator.showSchemasQuery();
 
 
-    return this.sequelize.query(showSchemasSql, null, options).then(function(schemaNames) {
+    return this.sequelize.query(showSchemasSql, options).then(function(schemaNames) {
       return Utils._.flatten(
       return Utils._.flatten(
         Utils._.map(schemaNames, function(value) {
         Utils._.map(schemaNames, function(value) {
           return (!!value.schema_name ? value.schema_name : value);
           return (!!value.schema_name ? value.schema_name : value);
@@ -83,7 +84,7 @@ module.exports = (function() {
     });
     });
 
 
     options = Utils._.extend({
     options = Utils._.extend({
-      logging: this.sequelize.options.logging
+      logging: this.sequelize.options.logging,
     }, options || {});
     }, options || {});
 
 
     // Postgres requires a special SQL command for enums
     // Postgres requires a special SQL command for enums
@@ -317,7 +318,7 @@ module.exports = (function() {
 
 
     var sql = this.QueryGenerator.describeTableQuery(tableName, schema, schemaDelimiter);
     var sql = this.QueryGenerator.describeTableQuery(tableName, schema, schemaDelimiter);
 
 
-    return this.sequelize.query(sql, null, { raw: true }).then(function(data) {
+    return this.sequelize.query(sql, { type: QueryTypes.DESCRIBE }).then(function(data) {
       // If no data is returned from the query, then the table name may be wrong.
       // If no data is returned from the query, then the table name may be wrong.
       // Query generators that use information_schema for retrieving table info will just return an empty result set,
       // Query generators that use information_schema for retrieving table info will just return an empty result set,
       // it will not throw an error like built-ins do (e.g. DESCRIBE on MySql).
       // it will not throw an error like built-ins do (e.g. DESCRIBE on MySql).
@@ -443,7 +444,7 @@ module.exports = (function() {
     }
     }
 
 
     return Utils.Promise.map(tableNames, function(tableName) {
     return Utils.Promise.map(tableNames, function(tableName) {
-      return self.sequelize.query(self.QueryGenerator.getForeignKeysQuery(tableName, self.sequelize.config.database));
+      return self.sequelize.query(self.QueryGenerator.getForeignKeysQuery(tableName, self.sequelize.config.database)).get(0);
     }).then(function(results) {
     }).then(function(results) {
       var result = {};
       var result = {};
 
 
@@ -556,6 +557,9 @@ module.exports = (function() {
       , restrict = false
       , restrict = false
       , sql = self.QueryGenerator.updateQuery(tableName, values, identifier, options, dao.Model.rawAttributes);
       , sql = self.QueryGenerator.updateQuery(tableName, values, identifier, options, dao.Model.rawAttributes);
 
 
+    options = options || {};
+    options.type = QueryTypes.UPDATE;
+
     // Check for a restrict field
     // Check for a restrict field
     if (!!dao.Model && !!dao.Model.associations) {
     if (!!dao.Model && !!dao.Model.associations) {
       var keys = Object.keys(dao.Model.associations)
       var keys = Object.keys(dao.Model.associations)
@@ -689,13 +693,14 @@ module.exports = (function() {
 
 
     var sql = this.QueryGenerator.selectQuery(tableName, options, model);
     var sql = this.QueryGenerator.selectQuery(tableName, options, model);
     queryOptions = Utils._.extend({}, queryOptions, {
     queryOptions = Utils._.extend({}, queryOptions, {
+      type: QueryTypes.SELECT,
       include: options.include,
       include: options.include,
       includeNames: options.includeNames,
       includeNames: options.includeNames,
       includeMap: options.includeMap,
       includeMap: options.includeMap,
       hasSingleAssociation: options.hasSingleAssociation,
       hasSingleAssociation: options.hasSingleAssociation,
       hasMultiAssociation: options.hasMultiAssociation,
       hasMultiAssociation: options.hasMultiAssociation,
       attributes: options.attributes,
       attributes: options.attributes,
-      originalAttributes: options.originalAttributes
+      originalAttributes: options.originalAttributes,
     });
     });
 
 
     return this.sequelize.query(sql, model, queryOptions);
     return this.sequelize.query(sql, model, queryOptions);

lib/query-types.js

@@ -3,10 +3,14 @@
 module.exports = {
 module.exports = {
   SELECT: 'SELECT',
   SELECT: 'SELECT',
   INSERT: 'INSERT',
   INSERT: 'INSERT',
+  UPDATE: 'UPDATE',
   BULKUPDATE: 'BULKUPDATE',
   BULKUPDATE: 'BULKUPDATE',
   BULKDELETE: 'BULKDELETE',
   BULKDELETE: 'BULKDELETE',
   UPSERT: 'UPSERT',
   UPSERT: 'UPSERT',
   VERSION: 'VERSION',
   VERSION: 'VERSION',
   SHOWTABLES: 'SHOWTABLES',
   SHOWTABLES: 'SHOWTABLES',
-  SHOWINDEXES: 'SHOWINDEXES'
+  SHOWINDEXES: 'SHOWINDEXES',
+  DESCRIBE: 'DESCRIBE',
+  RAW: 'RAW',
+  FOREIGNKEYS: 'FOREIGNKEYS',
 };
 };

lib/sequelize.js

@@ -227,7 +227,11 @@ module.exports = (function() {
    */
    */
   Sequelize.prototype.Promise = Sequelize.Promise = Promise;
   Sequelize.prototype.Promise = Sequelize.Promise = Promise;
 
 
-  Sequelize.QueryTypes = QueryTypes;
+  /**
+   * Available query types for use with `sequelize.query`
+   * @property QueryTypes
+   */
+  Sequelize.prototype.QueryTypes = Sequelize.QueryTypes = QueryTypes;
 
 
   /**
   /**
    * Exposes the validator.js object, so you can extend it with custom validation functions. The validator is exposed both on the instance, and on the constructor.
    * Exposes the validator.js object, so you can extend it with custom validation functions. The validator is exposed both on the instance, and on the constructor.
@@ -624,17 +628,31 @@ module.exports = (function() {
   /**
   /**
    * Execute a query on the DB, with the posibility to bypass all the sequelize goodness.
    * Execute a query on the DB, with the posibility to bypass all the sequelize goodness.
    *
    *
-   * If you do not provide other arguments than the SQL, raw will be assumed to the true, and sequelize will not try to do any formatting to the results of the query.
+   * By default, the function will return two arguments: an array of results, and a metadata object, containing number of affected rows etc. Use `.spread` to access the results.
+   *
+   * If you are running a type of query where you don't need the metadata, for example a `SELECT` query, you can pass in a query type to make sequelize format the results:
+   *
+   * ```js
+   * sequlize.query('SELECT...').spread(function (results, metadata) {
+   *   // Raw query - use spread
+   * });
+   *
+   * sequlize.query('SELECT...', { type: sequelize.QueryTypes.SELECT }).then(function (results) {
+   *   // SELECT query - use then
+   * })
+   * ```
    *
    *
    * @method query
    * @method query
-   * @param {String}        sql
-   * @param {Instance}      [callee] If callee is provided, the returned data will be put into the callee
-   * @param {Object}        [options={}] Query options.
-   * @param {Boolean}       [options.raw] If true, sequelize will not try to format the results of the query, or build an instance of a model from the result
-   * @param {Transaction}   [options.transaction] The transaction that the query should be executed under
-   * @param {String}        [options.type='SELECT'] The type of query you are executing. The query type affects how results are formatted before they are passed back. If no type is provided sequelize will try to guess the right type based on the sql, and fall back to SELECT. The type is a string, but `Sequelize.QueryTypes` is provided is convenience shortcuts. Current options are SELECT, BULKUPDATE and BULKDELETE
-   * @param {Boolean}       [options.nest=false] If true, transforms objects with `.` separated property names into nested objects using [dottie.js](https://github.com/mickhansen/dottie.js). For example { 'user.username': 'john' } becomes { user: { username: 'john' }}
-   * @param {Object|Array}  [replacements] Either an object of named parameter replacements in the format `:param` or an array of unnamed replacements to replace `?` in your SQL.
+   * @param {String}          sql
+   * @param {Instance|Model}  [callee] If callee is provided, the returned data will be put into the callee
+   * @param {Object}          [options={}] Query options.
+   * @param {Boolean}         [options.raw] If true, sequelize will not try to format the results of the query, or build an instance of a model from the result
+   * @param {Transaction}     [options.transaction=null] The transaction that the query should be executed under
+   * @param {String}          [options.type='RAW'] The type of query you are executing. The query type affects how results are formatted before they are passed back. The type is a string, but `Sequelize.QueryTypes` is provided as convenience shortcuts.
+   * @param {Boolean}         [options.nest=false] If true, transforms objects with `.` separated property names into nested objects using [dottie.js](https://github.com/mickhansen/dottie.js). For example { 'user.username': 'john' } becomes { user: { username: 'john' }}. When `nest` is true, the query type is assumed to be `'SELECT'`, unless otherwise specified
+   * @param {Boolean}         [options.plain=false] Sets the query type to `SELECT` and return a single row
+   * @param {Object|Array}    [options.replacements] Either an object of named parameter replacements in the format `:param` or an array of unnamed replacements to replace `?` in your SQL.
+   *
    * @return {Promise}
    * @return {Promise}
    *
    *
    * @see {Model#build} for more information about callee.
    * @see {Model#build} for more information about callee.
@@ -643,30 +661,52 @@ module.exports = (function() {
     var self = this;
     var self = this;
     sql = sql.trim();
     sql = sql.trim();
     if (arguments.length === 4) {
     if (arguments.length === 4) {
-      if (Array.isArray(replacements)) {
-        sql = Utils.format([sql].concat(replacements), this.options.dialect);
-      }
-      else {
-        sql = Utils.formatNamedParameters(sql, replacements, this.options.dialect);
-      }
+      deprecated('passing raw query replacements as the 4th argument to sequelize.query is deprecated. Please use options.replacements instead');
+      options.replacements = replacements;
     } else if (arguments.length === 3) {
     } else if (arguments.length === 3) {
       options = options;
       options = options;
     } else if (arguments.length === 2) {
     } else if (arguments.length === 2) {
-      options = {};
+      if (callee instanceof Sequelize.Model) {
+        options = {};
+      } else {
+        options = callee;
+        callee = undefined;
+      }
     } else {
     } else {
       options = { raw: true };
       options = { raw: true };
     }
     }
 
 
+    if (!(callee instanceof Sequelize.Model)) {
+      // When callee is not set, assume raw query
+      options.raw = true;
+    }
+
+    if (options.replacements) {
+      if (Array.isArray(options.replacements)) {
+        sql = Utils.format([sql].concat(options.replacements), this.options.dialect);
+      }
+      else {
+        sql = Utils.formatNamedParameters(sql, options.replacements, this.options.dialect);
+      }
+    }
+
     options = Utils._.extend(Utils._.clone(this.options.query), options);
     options = Utils._.extend(Utils._.clone(this.options.query), options);
     options = Utils._.defaults(options, {
     options = Utils._.defaults(options, {
-      logging: this.options.hasOwnProperty('logging') ? this.options.logging : console.log,
-      type: (sql.toLowerCase().indexOf('select') === 0) ? QueryTypes.SELECT : false
+      logging: this.options.hasOwnProperty('logging') ? this.options.logging : console.log
     });
     });
 
 
     if (options.transaction === undefined && Sequelize.cls) {
     if (options.transaction === undefined && Sequelize.cls) {
       options.transaction = Sequelize.cls.get('transaction');
       options.transaction = Sequelize.cls.get('transaction');
     }
     }
 
 
+    if (!options.type) {
+      if (options.nest || options.plain) {
+        options.type = QueryTypes.SELECT;
+      } else {
+        options.type = QueryTypes.RAW;
+      }
+    }
+
     if (options.transaction && options.transaction.finished) {
     if (options.transaction && options.transaction.finished) {
       return Promise.reject(options.transaction.finished+' has been called on this transaction, you can no longer use it');
       return Promise.reject(options.transaction.finished+' has been called on this transaction, you can no longer use it');
     }
     }

mkdocs.yml

@@ -19,6 +19,7 @@ pages:
 - ['docs/hooks.md', 'Documentation', 'Hooks']
 - ['docs/hooks.md', 'Documentation', 'Hooks']
 - ['docs/transactions.md', 'Documentation', 'Transactions']
 - ['docs/transactions.md', 'Documentation', 'Transactions']
 - ['docs/legacy.md', 'Documentation', 'Working with legacy tables']
 - ['docs/legacy.md', 'Documentation', 'Working with legacy tables']
+- ['docs/raw-queries.md', 'Documentation', 'Raw queries']
 - ['docs/migrations.md', 'Documentation', 'Migrations']
 - ['docs/migrations.md', 'Documentation', 'Migrations']
 
 
 - ['api/sequelize.md', 'API', 'Sequelize']
 - ['api/sequelize.md', 'API', 'Sequelize']
@@ -29,4 +30,4 @@ pages:
 - ['api/promise.md', 'API', 'Promise']
 - ['api/promise.md', 'API', 'Promise']
 - ['api/transaction.md', 'API', 'Transaction']
 - ['api/transaction.md', 'API', 'Transaction']
 - ['api/datatypes.md', 'API', 'Datatypes']
 - ['api/datatypes.md', 'API', 'Datatypes']
-- ['api/errors.md', 'API', 'Errors']
+- ['api/errors.md', 'API', 'Errors']
\ No newline at end of file

test/integration/dialects/mysql/connector-manager.test.js

@@ -34,24 +34,21 @@ if (Support.dialectIsMySQL()) {
       });
       });
     });
     });
 
 
-    it('accepts new queries after shutting down a connection', function(done) {
+    it('accepts new queries after shutting down a connection', function() {
       // Create a sequelize instance with pooling disabled
       // Create a sequelize instance with pooling disabled
       var sequelize = Support.createSequelizeInstance({ pool: false });
       var sequelize = Support.createSequelizeInstance({ pool: false });
       var User = sequelize.define('User', { username: DataTypes.STRING });
       var User = sequelize.define('User', { username: DataTypes.STRING });
 
 
-      User.sync({force: true}).on('success', function() {
-        User.create({username: 'user1'}).on('success', function() {
-          // After 100 ms the DB connection will be disconnected for inactivity
-          setTimeout(function() {
-            // This query will be queued just after the `client.end` is executed and before its callback is called
-            sequelize.query('SELECT COUNT(*) AS count FROM Users').on('success', function(count) {
-              expect(count[0].count).to.equal(1);
-              done();
-            }).error(function(error) {
-              expect(error).to.not.exist;
-            });
-          }, 100);
-        });
+      return User.sync({force: true}).then(function() {
+        return User.create({username: 'user1'});
+      }).then(function() {
+        // After 100 ms the DB connection will be disconnected for inactivity
+        return sequelize.Promise.delay(100);
+      }).then(function () {
+        // This query will be queued just after the `client.end` is executed and before its callback is called
+        return sequelize.query('SELECT COUNT(*) AS count FROM Users', { type: sequelize.QueryTypes.SELECT });
+      }).then(function(count) {
+        expect(count[0].count).to.equal(1);
       });
       });
     });
     });
 
 

test/integration/query-interface.test.js

@@ -424,15 +424,15 @@ describe(Support.getTestDialectTeaser('QueryInterface'), function() {
       });
       });
     });
     });
 
 
-    it('should get a list of foreign keys for the table', function(done) {
-      var sql =
-        this.queryInterface.QueryGenerator.getForeignKeysQuery('hosts', this.sequelize.config.database);
-      this.sequelize.query(sql).complete(function(err, fks) {
-        expect(err).to.be.null;
+    it('should get a list of foreign keys for the table', function() {
+      var sql = this.queryInterface.QueryGenerator.getForeignKeysQuery('hosts', this.sequelize.config.database);
+
+      return this.sequelize.query(sql, {type: this.sequelize.QueryTypes.FOREIGNKEYS}).then(function(fks) {
         expect(fks).to.have.length(3);
         expect(fks).to.have.length(3);
         var keys = Object.keys(fks[0]),
         var keys = Object.keys(fks[0]),
           keys2 = Object.keys(fks[1]),
           keys2 = Object.keys(fks[1]),
           keys3 = Object.keys(fks[2]);
           keys3 = Object.keys(fks[2]);
+
         if (dialect === 'postgres' || dialect === 'postgres-native') {
         if (dialect === 'postgres' || dialect === 'postgres-native') {
           expect(keys).to.have.length(6);
           expect(keys).to.have.length(6);
           expect(keys2).to.have.length(7);
           expect(keys2).to.have.length(7);
@@ -444,10 +444,7 @@ describe(Support.getTestDialectTeaser('QueryInterface'), function() {
         } else {
         } else {
           console.log("This test doesn't support " + dialect);
           console.log("This test doesn't support " + dialect);
         }
         }
-        done();
       });
       });
-
     });
     });
   });
   });
-
 });
 });

test/integration/sequelize.transaction.test.js

@@ -20,7 +20,7 @@ describe(Support.getTestDialectTeaser('Sequelize#transaction'), function() {
         .success(function() { done(); });
         .success(function() { done(); });
     });
     });
 
 
-    it('gets triggered once a transaction has been successfully rollbacked', function(done) {
+    it('gets triggered once a transaction has been successfully rolled back', function(done) {
       this
       this
         .sequelize
         .sequelize
         .transaction().then(function(t) { t.rollback(); })
         .transaction().then(function(t) { t.rollback(); })
@@ -28,59 +28,44 @@ describe(Support.getTestDialectTeaser('Sequelize#transaction'), function() {
     });
     });
 
 
     if (Support.getTestDialect() !== 'sqlite') {
     if (Support.getTestDialect() !== 'sqlite') {
-      it('works for long running transactions', function(done) {
-        Support.prepareTransactionTest(this.sequelize, function(sequelize) {
-          var User = sequelize.define('User', {
+      it('works for long running transactions', function() {
+        this.timeout(10000);
+        return Support.prepareTransactionTest(this.sequelize).bind(this).then(function(sequelize) {
+          this.sequelize = sequelize;
+
+          this.User = sequelize.define('User', {
             name: Support.Sequelize.STRING
             name: Support.Sequelize.STRING
           }, { timestamps: false });
           }, { timestamps: false });
 
 
-          return sequelize.sync({ force: true }).success(function() {
-            return sequelize.transaction();
-          }).then(function(t) {
-            expect(t).to.be.ok;
-            var query = 'select sleep(2);';
-
-            switch (Support.getTestDialect()) {
-            case 'postgres':
-              query = 'select pg_sleep(2);';
-              break;
-            case 'sqlite':
-              query = 'select sqlite3_sleep(2000);';
-              break;
-            default:
-              break;
-            }
-
-            return sequelize.query(query, null, {
-              raw: true,
-              plain: true,
-              transaction: t
-            }).then(function() {
-              var dao = User.build({ name: 'foo' });
-
-              // this.QueryGenerator.insertQuery(tableName, values, dao.daoFactory.rawAttributes)
-              return query = sequelize
-                .getQueryInterface()
-                .QueryGenerator
-                .insertQuery(User.tableName, dao.values, User.rawAttributes);
-            }).then(function() {
-              return Promise.delay(1000);
-            }).then(function() {
-              return sequelize.query(query, null, {
-                raw: true,
-                plain: true,
-                transaction: t
-              });
-            }).then(function() {
-              return t.commit();
-            });
+          return sequelize.sync({ force: true });
+        }).then(function() {
+          return this.sequelize.transaction();
+        }).then(function(t) {
+          var query = 'select sleep(2);';
+
+          switch (Support.getTestDialect()) {
+          case 'postgres':
+            query = 'select pg_sleep(2);';
+            break;
+          case 'sqlite':
+            query = 'select sqlite3_sleep(2000);';
+            break;
+          default:
+            break;
+          }
+
+          return this.sequelize.query(query, { transaction: t }).bind(this).then(function() {
+            return this.User.create({ name: 'foo' });
           }).then(function() {
           }).then(function() {
-            return User.all().success(function(users) {
-              expect(users.length).to.equal(1);
-              expect(users[0].name).to.equal('foo');
-              done();
-            });
-          }).catch (done);
+            return this.sequelize.query(query, { transaction: t });
+          }).then(function() {
+            return t.commit();
+          });
+        }).then(function() {
+          return this.User.all();
+        }).then(function(users) {
+          expect(users.length).to.equal(1);
+          expect(users[0].name).to.equal('foo');
         });
         });
       });
       });
     }
     }

test/integration/timezone.test.js

@@ -28,8 +28,8 @@ if (dialect !== 'sqlite') {
 
 
       var query = 'SELECT ' + now + ' as now';
       var query = 'SELECT ' + now + ' as now';
       return Promise.all([
       return Promise.all([
-        this.sequelize.query(query),
-        this.sequelizeWithTimezone.query(query)
+        this.sequelize.query(query, { type: this.sequelize.QueryTypes.SELECT }),
+        this.sequelizeWithTimezone.query(query, { type: this.sequelize.QueryTypes.SELECT })
       ]).spread(function(now1, now2) {
       ]).spread(function(now1, now2) {
         var elapsedQueryTime = (Date.now() - startQueryTime) + 20;
         var elapsedQueryTime = (Date.now() - startQueryTime) + 20;
         expect(now1[0].now.getTime()).to.be.closeTo(now2[0].now.getTime(), elapsedQueryTime);
         expect(now1[0].now.getTime()).to.be.closeTo(now2[0].now.getTime(), elapsedQueryTime);

test/integration/transaction.test.js

@@ -98,7 +98,7 @@ describe(Support.getTestDialectTeaser('Transaction'), function() {
         .then(function(t) {
         .then(function(t) {
           return sequelize.sync({transaction:t})
           return sequelize.sync({transaction:t})
             .then(function( ) {
             .then(function( ) {
-              return t;              
+              return t;
             });
             });
         })
         })
         .then(function(t) {
         .then(function(t) {
@@ -116,7 +116,7 @@ describe(Support.getTestDialectTeaser('Transaction'), function() {
         .then(function(users) {
         .then(function(users) {
           return expect(users.length).to.equal(1);
           return expect(users.length).to.equal(1);
         });
         });
-    });  
+    });
   }
   }
 
 
    if (current.dialect.supports.lock) {
    if (current.dialect.supports.lock) {