add docs for query bind parameters

docs/docs/raw-queries.md

@@ -47,3 +47,31 @@ sequelize.query('SELECT * FROM projects WHERE status = :status ',
   console.log(projects)
   console.log(projects)
 })
 })
 ```
 ```
+
+# Bind Parameter
+Bind parameters are like replacemnets. Except replacements are escaped and inserted into the query by sequelize before the query is sent to the database, while bind parameters are sent to the database outside the sql query text. A query can have either bind parameters or replacments.
+
+Only Sqlite and Postgresql support bind parameters. Other dialects will insert them into the sql query in the same way it is done for replacements. Bind parameters are referred to by either $1, $2, ... (numeric) or $key (alpha-numeric). This is independent of the dialect.
+
+* If an array is passed, `$1` will be bound to the 1st element in the array (`bind[0]`)
+* If an object is passed, `$key` will be bound to `object['key']`. Each key must have a none numeric char. `$1` is not a valid key, even if `object['1']` exists.
+* In either case `$$` can be used to escape a literal `$` sign.
+
+All bound values must be present in the array/object or an exception will be thrown. This applies even to cases in which the database may ignore the bound parameter.
+
+The database may add further restrictions to this. Bind parameters can not be sql keywords, nor table or column names. They are also ignored in quoted text/data. In Postgresql it may also be needed to typecast them, if the type can not be inferred from the context `$1::varchar`.
+
+```js
+sequelize.query('SELECT *, "text with literal $$1 and literal $$status" as t FROM projects WHERE status = $1',
+  { bind: ['active'], type: sequelize.QueryTypes.SELECT }
+).then(function(projects) {
+  console.log(projects)
+})
+
+sequelize.query('SELECT *, "text with literal $$1 and literal $$status" as t FROM projects WHERE status = $status',
+  { bind: { status: 'active' }, type: sequelize.QueryTypes.SELECT }
+).then(function(projects) {
+  console.log(projects)
+})
+```
+

lib/sequelize.js

@@ -666,6 +666,7 @@ Sequelize.prototype.import = function(path) {
  * @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.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 {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.
  * @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.
+ * @param {Object|Array}    [options.bind] Either an object of named bind parameter in the format `$param` or an array of unnamed bind parameter to replace `$1, $2, ...` in your SQL.
  * @param {Boolean}         [options.useMaster=false] Force the query to use the write pool, regardless of the query type.
  * @param {Boolean}         [options.useMaster=false] Force the query to use the write pool, regardless of the query type.
  * @param {Function}        [options.logging=false] A function that gets executed while running the query to log the sql.
  * @param {Function}        [options.logging=false] A function that gets executed while running the query to log the sql.
  * @param {Instance}        [options.instance] A sequelize instance used to build the return instance
  * @param {Instance}        [options.instance] A sequelize instance used to build the return instance