PoolPlus: Add .raw() method

README.md

@@ -240,6 +240,7 @@ and perform queries and transactions using promises.
 * [PoolPlus](#PoolPlus) ⇐ <code>Pool</code>
     * _instance_
         * [.ColTypes](#PoolPlus+ColTypes)
+        * [.raw(sql)](#PoolPlus+raw) ⇒ <code>Object</code>
         * [.basicTable(name)](#PoolPlus+basicTable) ⇒ <code>[MySQLTable](#MySQLTable)</code>
         * [.defineTable(name, schema, [migrationStrategy])](#PoolPlus+defineTable) ⇒ <code>[MySQLTable](#MySQLTable)</code>
         * [.sync(cb)](#PoolPlus+sync) ⇒ <code>void</code>
@@ -273,6 +274,40 @@ const userTable = pool.defineTable('user', {
 ```
 
 
+---
+
+<a name="PoolPlus+raw"></a>
+
+### poolPlus.raw(sql) ⇒ <code>Object</code>
+Wraps the provided SQL string in an object that will prevent the string from being escaped
+when it is used as a data-object value or `?` placeholder replacement.
+(The same as [`mysql.raw()`](https://github.com/mysqljs/mysql#escaping-query-values).)
+
+
+| Param | Type | Description |
+|:--- |:--- |:--- |
+| sql | <code>string</code> | SQL that you do not want to be escaped. |
+
+**Returns**: <code>Object</code> - An object that is turned into the provided `sql` string when `mysql` attempts to escape it.  
+**See**: [(mysql) Escaping query values](https://github.com/mysqljs/mysql#escaping-query-values)
+
+**Example**: Inserting a geometry Point
+```js
+placeTable.insert({
+  placeId: 'ChIJK2f',
+  coordinates: pool.raw('POINT(-80.5204, 43.4642)'),
+});
+// or
+placeTable.insert(
+  'SET `placeId` = ?, `coordinates` = ?',
+  ['ChIJK2f', pool.raw('POINT(-80.5204, 43.4642)')]
+);
+
+// INSERT INTO `place`
+// SET `placeId` = 'ChIJK2f', `coordinates` = POINT(-80.5204, 43.4642);
+```
+
+
 ---
 
 <a name="PoolPlus+basicTable"></a>

lib/PoolPlus.js

@@ -62,11 +62,38 @@ class PoolPlus extends Pool {
     return SqlString.format(sql, values, connConfig.stringifyObjects, connConfig.timezone);
   }
 
+  /**
+   * Wraps the provided SQL string in an object that will prevent the string from being escaped
+   * when it is used as a data-object value or `?` placeholder replacement.
+   * (The same as [`mysql.raw()`](https://github.com/mysqljs/mysql#escaping-query-values).)
+   *
+   * @param {string} sql - SQL that you do not want to be escaped.
+   * @return {Object} An object that is turned into the provided `sql` string when `mysql` attempts to escape it.
+   * @see {@link https://github.com/mysqljs/mysql#escaping-query-values|(mysql) Escaping query values}
+   *
+   * @example <caption>Inserting a geometry Point</caption>
+   * placeTable.insert({
+   *   placeId: 'ChIJK2f',
+   *   coordinates: pool.raw('POINT(-80.5204, 43.4642)'),
+   * });
+   * // or
+   * placeTable.insert(
+   *   'SET `placeId` = ?, `coordinates` = ?',
+   *   ['ChIJK2f', pool.raw('POINT(-80.5204, 43.4642)')]
+   * );
+   *
+   * // INSERT INTO `place`
+   * // SET `placeId` = 'ChIJK2f', `coordinates` = POINT(-80.5204, 43.4642);
+   */
+  raw(sql) {
+    return SqlString.raw(sql);
+  }
+
   /**
    * Simply returns an instance of {@link MySQLTable|`MySQLTable`}
    * for querying the table with the given `name`.
    *
-   * @param  {string} name - The name of the table.
+   * @param {string} name - The name of the table.
    * @returns {MySQLTable} A `MySQLTable` instance.
    */
   basicTable(name) {