sharp-db

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width,initial-scale=1"> <title>Home - Documentation</title> <script src="scripts/prettify/prettify.js"></script> <script src="scripts/prettify/lang-css.js"></script>  <link type="text/css" rel="stylesheet" href="https://code.ionicframework.com/ionicons/2.0.1/css/ionicons.min.css"> <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css"> <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css"> </head> <body> <input type="checkbox" id="nav-trigger" class="nav-trigger" /> <label for="nav-trigger" class="navicon-button x"> <div class="navicon"></div> </label> <label for="nav-trigger" class="overlay"></label> <nav> <li class="nav-link nav-home-link"><a href="index.html">Home</a></li><li class="nav-heading">Classes</li><li class="nav-heading">C<a href="DataBroker.html">DataBroker</a></li><li class="nav-item">F<a href="DataBroker.html#cleanup">cleanup</a></li><li class="nav-item">F<a href="DataBroker.html#created_and_modified">created_and_modified</a></li><li class="nav-item">F<a href="DataBroker.html#createdAndModified">createdAndModified</a></li><li class="nav-item">F<a href="DataBroker.html#delete">delete</a></li><li class="nav-item">F<a href="DataBroker.html#insert">insert</a></li><li class="nav-heading">C<a href="Db.html">Db</a></li><li class="nav-item">F<a href="Db.html#.destroyAll">destroyAll</a></li><li class="nav-item">F<a href="Db.html#.endAll">endAll</a></li><li class="nav-item">F<a href="Db.html#.factory">factory</a></li><li class="nav-item">F<a href="Db.html#.withInstance">withInstance</a></li><li class="nav-item">F<a href="Db.html#beginTransaction">beginTransaction</a></li><li class="nav-item">F<a href="Db.html#bindArgs">bindArgs</a></li><li class="nav-item">F<a href="Db.html#commit">commit</a></li><li class="nav-item">F<a href="Db.html#connect">connect</a></li><li class="nav-item">F<a href="Db.html#connectOnce">connectOnce</a></li><li class="nav-item">F<a href="Db.html#delete">delete</a></li><li class="nav-item">F<a href="Db.html#deleteFrom">deleteFrom</a></li><li class="nav-item">F<a href="Db.html#destroy">destroy</a></li><li class="nav-item">F<a href="Db.html#emit">emit</a></li><li class="nav-item">F<a href="Db.html#emitError">emitError</a></li><li class="nav-item">F<a href="Db.html#end">end</a></li><li class="nav-item">F<a href="Db.html#escape">escape</a></li><li class="nav-item">F<a href="Db.html#escapeLike">escapeLike</a></li><li class="nav-item">F<a href="Db.html#escapeQuoteless">escapeQuoteless</a></li><li class="nav-item">F<a href="Db.html#exportAsSql">exportAsSql</a></li><li class="nav-item">F<a href="Db.html#insert">insert</a></li><li class="nav-item">F<a href="Db.html#insertExtended">insertExtended</a></li><li class="nav-item">F<a href="Db.html#insertInto">insertInto</a></li><li class="nav-item">F<a href="Db.html#insertIntoOnDuplicateKeyUpdate">insertIntoOnDuplicateKeyUpdate</a></li><li class="nav-item">F<a href="Db.html#multiQuery">multiQuery</a></li><li class="nav-item">F<a href="Db.html#query">query</a></li><li class="nav-item">F<a href="Db.html#quote">quote</a></li><li class="nav-item">F<a href="Db.html#rollback">rollback</a></li><li class="nav-item">F<a href="Db.html#select">select</a></li><li class="nav-item">F<a href="Db.html#selectByKey">selectByKey</a></li><li class="nav-item">F<a href="Db.html#selectExists">selectExists</a></li><li class="nav-item">F<a href="Db.html#selectFirst">selectFirst</a></li><li class="nav-item">F<a href="Db.html#selectFrom">selectFrom</a></li><li class="nav-item">F<a href="Db.html#selectGrouped">selectGrouped</a></li><li class="nav-item">F<a href="Db.html#selectHash">selectHash</a></li><li class="nav-item">F<a href="Db.html#selectId">selectId</a></li><li class="nav-item">F<a href="Db.html#selectIndexed">selectIndexed</a></li><li class="nav-item">F<a href="Db.html#selectList">selectList</a></li><li class="nav-item">F<a href="Db.html#selectOrCreate">selectOrCreate</a></li><li class="nav-item">F<a href="Db.html#selectOrCreateId">selectOrCreateId</a></li><li class="nav-item">F<a href="Db.html#selectUuid">selectUuid</a></li><li class="nav-item">F<a href="Db.html#selectValue">selectValue</a></li><li class="nav-item">F<a href="Db.html#startTransaction">startTransaction</a></li><li class="nav-item">F<a href="Db.html#tpl">tpl</a></li><li class="nav-item">F<a href="Db.html#update">update</a></li><li class="nav-item">F<a href="Db.html#updateTable">updateTable</a></li><li class="nav-heading">C<a href="DbEvent.html">DbEvent</a></li><li class="nav-heading">C<a href="Parser.html">Parser</a></li><li class="nav-item">F<a href="Parser.html#_extractSubqueries">_extractSubqueries</a></li><li class="nav-item">F<a href="Parser.html#_handleConditions">_handleConditions</a></li><li class="nav-item">F<a href="Parser.html#_handleCrossJoin">_handleCrossJoin</a></li><li class="nav-item">F<a href="Parser.html#_handleFrom">_handleFrom</a></li><li class="nav-item">F<a href="Parser.html#_handleFullJoin">_handleFullJoin</a></li><li class="nav-item">F<a href="Parser.html#_handleFullOuterJoin">_handleFullOuterJoin</a></li><li class="nav-item">F<a href="Parser.html#_handleGroupBy">_handleGroupBy</a></li><li class="nav-item">F<a href="Parser.html#_handleHaving">_handleHaving</a></li><li class="nav-item">F<a href="Parser.html#_handleInnerJoin">_handleInnerJoin</a></li><li class="nav-item">F<a href="Parser.html#_handleLeftJoin">_handleLeftJoin</a></li><li class="nav-item">F<a href="Parser.html#_handleLeftOuterJoin">_handleLeftOuterJoin</a></li><li class="nav-item">F<a href="Parser.html#_handleLimit">_handleLimit</a></li><li class="nav-item">F<a href="Parser.html#_handleOffset">_handleOffset</a></li><li class="nav-item">F<a href="Parser.html#_handleOrderBy">_handleOrderBy</a></li><li class="nav-item">F<a href="Parser.html#_handleRightJoin">_handleRightJoin</a></li><li class="nav-item">F<a href="Parser.html#_handleRightOuterJoin">_handleRightOuterJoin</a></li><li class="nav-item">F<a href="Parser.html#_handleSelect">_handleSelect</a></li><li class="nav-item">F<a href="Parser.html#_handleWhere">_handleWhere</a></li><li class="nav-item">F<a href="Parser.html#_injectSubqueries">_injectSubqueries</a></li><li class="nav-item">F<a href="Parser.html#_split">_split</a></li><li class="nav-item">F<a href="Parser.html#_stripComments">_stripComments</a></li><li class="nav-item">F<a href="Parser.html#parse">parse</a></li><li class="nav-heading">C<a href="Select.html">Select</a></li><li class="nav-item">F<a href="Select.html#._extractBindingName">_extractBindingName</a></li><li class="nav-item">F<a href="Select.html#.init">init</a></li><li class="nav-item">F<a href="Select.html#.parse">parse</a></li><li class="nav-item">F<a href="Select.html#_conditions">_conditions</a></li><li class="nav-item">F<a href="Select.html#_isEntirelyDigits">_isEntirelyDigits</a></li><li class="nav-item">F<a href="Select.html#_isEntirelyDigitsNoZeros">_isEntirelyDigitsNoZeros</a></li><li class="nav-item">F<a href="Select.html#_isPlaceholder">_isPlaceholder</a></li><li class="nav-item">F<a href="Select.html#_spliceChildData">_spliceChildData</a></li><li class="nav-item">F<a href="Select.html#_spliceSiblingData">_spliceSiblingData</a></li><li class="nav-item">F<a href="Select.html#bind">bind</a></li><li class="nav-item">F<a href="Select.html#column">column</a></li><li class="nav-item">F<a href="Select.html#columns">columns</a></li><li class="nav-item">F<a href="Select.html#crossJoin">crossJoin</a></li><li class="nav-item">F<a href="Select.html#escape">escape</a></li><li class="nav-item">F<a href="Select.html#escapeLike">escapeLike</a></li><li class="nav-item">F<a href="Select.html#escapeQuoteless">escapeQuoteless</a></li><li class="nav-item">F<a href="Select.html#fetch">fetch</a></li><li class="nav-item">F<a href="Select.html#fetchFirst">fetchFirst</a></li><li class="nav-item">F<a href="Select.html#fetchGrouped">fetchGrouped</a></li><li class="nav-item">F<a href="Select.html#fetchHash">fetchHash</a></li><li class="nav-item">F<a href="Select.html#fetchIndexed">fetchIndexed</a></li><li class="nav-item">F<a href="Select.html#fetchList">fetchList</a></li><li class="nav-item">F<a href="Select.html#fetchValue">fetchValue</a></li><li class="nav-item">F<a href="Select.html#foundRows">foundRows</a></li><li class="nav-item">F<a href="Select.html#from">from</a></li><li class="nav-item">F<a href="Select.html#fullJoin">fullJoin</a></li><li class="nav-item">F<a href="Select.html#fullOuterJoin">fullOuterJoin</a></li><li class="nav-item">F<a href="Select.html#getClone">getClone</a></li><li class="nav-item">F<a href="Select.html#getFoundRowsQuery">getFoundRowsQuery</a></li><li class="nav-item">F<a href="Select.html#getFoundRowsSql">getFoundRowsSql</a></li><li class="nav-item">F<a href="Select.html#groupBy">groupBy</a></li><li class="nav-item">F<a href="Select.html#having">having</a></li><li class="nav-item">F<a href="Select.html#innerJoin">innerJoin</a></li><li class="nav-item">F<a href="Select.html#join">join</a></li><li class="nav-item">F<a href="Select.html#leftJoin">leftJoin</a></li><li class="nav-item">F<a href="Select.html#leftOuterJoin">leftOuterJoin</a></li><li class="nav-item">F<a href="Select.html#limit">limit</a></li><li class="nav-item">F<a href="Select.html#normalized">normalized</a></li><li class="nav-item">F<a href="Select.html#offset">offset</a></li><li class="nav-item">F<a href="Select.html#option">option</a></li><li class="nav-item">F<a href="Select.html#orderBy">orderBy</a></li><li class="nav-item">F<a href="Select.html#orHaving">orHaving</a></li><li class="nav-item">F<a href="Select.html#orWhere">orWhere</a></li><li class="nav-item">F<a href="Select.html#page">page</a></li><li class="nav-item">F<a href="Select.html#parse">parse</a></li><li class="nav-item">F<a href="Select.html#reset">reset</a></li><li class="nav-item">F<a href="Select.html#rightJoin">rightJoin</a></li><li class="nav-item">F<a href="Select.html#rightOuterJoin">rightOuterJoin</a></li><li class="nav-item">F<a href="Select.html#sortField">sortField</a></li><li class="nav-item">F<a href="Select.html#table">table</a></li><li class="nav-item">F<a href="Select.html#tables">tables</a></li><li class="nav-item">F<a href="Select.html#toBoundSql">toBoundSql</a></li><li class="nav-item">F<a href="Select.html#toString">toString</a></li><li class="nav-item">F<a href="Select.html#unbind">unbind</a></li><li class="nav-item">F<a href="Select.html#unjoin">unjoin</a></li><li class="nav-item">F<a href="Select.html#where">where</a></li><li class="nav-item">F<a href="Select.html#whereBetween">whereBetween</a></li><li class="nav-item">F<a href="Select.html#withChildData">withChildData</a></li><li class="nav-item">F<a href="Select.html#withSiblingData">withSiblingData</a></li><li class="nav-heading">C<a href="Ssh.html">Ssh</a></li><li class="nav-item">F<a href="Ssh.html#end">end</a></li><li class="nav-item">F<a href="Ssh.html#tunnelTo">tunnelTo</a></li> </nav> <div id="main"> <section class="readme"> <article><h1>sharp-db</h1> <a href="https://travis-ci.org/kensnyder/sharp-db"><img src="https://travis-ci.com/kensnyder/sharp-db.svg?branch=master&v=1.7.1" alt="Build Status"></a> <a href="https://codecov.io/gh/kensnyder/sharp-db"><img src="https://codecov.io/gh/kensnyder/sharp-db/branch/master/graph/badge.svg?v=1.7.1" alt="Code Coverage"></a> <a href="https://opensource.org/licenses/ISC"><img src="https://img.shields.io/github/license/kensnyder/sharp-db.svg?v=1.7.1" alt="ISC License"></a> Classes for running SQL and building select queries for MySQL in Node <h2>Installation</h2> <pre class="prettyprint source lang-bash"><code>npm install sharp-db </code></pre> <h2>Table of Contents</h2> <ul> <li><a href="#db">Db</a> <ul> <li><a href="#connection">Connection</a></li> <li><a href="#instantiation">Instantiation</a></li> <li><a href="#ssh-tunneling">SSH Tunneling</a></li> <li><a href="#basic-use">Basic Use</a></li> <li><a href="#bindings">Bindings</a></li> <li><a href="#methods">Methods</a></li> <li><a href="#useful-query-options">Useful Query Options</a></li> <li><a href="#solutions-to-common-problems">Solutions to Common Problems</a></li> </ul> </li> <li><a href="#select">Select</a> <ul> <li><a href="#selectparse">Select.parse()</a></li> <li><a href="#building-the-query">Building the Query</a></li> <li><a href="#fetching-data">Fetching Data</a></li> <li><a href="#counting-results">Counting Results</a></li> <li><a href="#specifying-the-db-instance-to-use">Set the <code>Db</code> instance</a></li> <li><a href="#dependent-data">Dependent Data</a></li> <li><a href="#other-methods">Other Methods</a></li> <li><a href="#selectparse-limitations">Select.parse() Limitations</a></li> </ul> </li> <li><a href="#databroker">DataBroker</a> <ul> <li><a href="#use-in-integration-tests">Use in Integration Tests</a></li> <li><a href="#insertions">Insertions</a></li> <li><a href="#deletions">Deletions</a></li> </ul> </li> <li><a href="#sqlbuilder">SqlBuilder</a> <ul> <li><a href="#function-list">Function List</a></li> </ul> </li> <li><a href="#querylogger">QueryLogger</a> <ul> <li><a href="#logging-queries">Logging queries</a></li> </ul> </li> <li><a href="./CONTRIBUTING.md">How to Contribute</a></li> <li><a href="./LICENSE.md">ISC License</a></li> </ul> <h2>Db</h2> <h3>Connection</h3> Connection can be configured with environmental variables or in the constructor. <table> <thead> <tr> <th>Option</th> <th>ENV name</th> <th>Default</th> </tr> </thead> <tbody> <tr> <td><code>host</code></td> <td>DB_HOST</td> <td>127.0.0.1</td> </tr> <tr> <td><code>port</code></td> <td>DB_PORT</td> <td>3306</td> </tr> <tr> <td><code>user</code></td> <td>DB_USER</td> <td>root</td> </tr> <tr> <td><code>password</code></td> <td>DB_PASSWORD</td> <td>empty string</td> </tr> <tr> <td><code>database</code></td> <td>DB_DATABASE</td> <td>undefined</td> </tr> <tr> <td><code>charset</code></td> <td>DB_CHARSET</td> <td>utf8mb4</td> </tr> </tbody> </table> See node's mysqljs for <a href="https://github.com/mysqljs/mysql#connection-options">other options</a>. <h3>Instantiation</h3> Connect to MySQL server <pre class="prettyprint source lang-js"><code>const { Db } = require('sharp-db'); // read options from ENV const db1 = Db.factory(); // specify options in constructor const db2 = new Db({ host: '127.0.0.1', user: 'root', password: '', port: 3306, }); // instance that was last created const db2Again = Db.factory(); // Don't forget to close the connection when done db1.end(); db2.end(); </code></pre> <h4>Auto factory and end</h4> You can use <code>await Db.withInstance(db => /* do stuff with db */)</code> to get an instance, do something, and then close the connection. <pre class="prettyprint source lang-js"><code>const { Db } = require('sharp-db'); // read options from ENV, instantiate and call db.end() automatically const { error, domain } = await Db.withInstance(async db => { const sql = 'SELECT email FROM users WHERE id = 5'; const { results: email } = await db.selectValue(sql); return { domain: email.split('@').pop(), }; }); </code></pre> <code>Db.withInstance()</code> will return one of the following: <ol> <li> <code>{ error }</code> where error is an object from mysql2. <a href="https://github.com/mysqljs/mysql#error-handling">Full docs</a>. Summary: <ul> <li><code>error.sqlMessage</code> The textual description of the error</li> <li><code>error.code</code> The string error code such as <code>PROTOCOL_CONNECTION_LOST</code></li> <li><code>error.errno</code> The associated number code</li> <li><code>error.fatal</code> True if the error caused the connection to close</li> <li><code>error.sql</code> The full SQL of the failed query</li> <li><code>error.sqlState</code> The five-character SQLSTATE code</li> </ul> </li> <li> Whatever value is returned from the handler. We suggest always returning an object, expecting the caller to check <code>.error</code>. </li> </ol> WARNING: Your handler function must return a promise that resolves AFTER your query has returned a result. Failing to do so will result in <code>db.end()</code> being called before your query is run. You may see an Error similar to the following: <code>[ERROR] -1 (N/A): Can't add new command when connection is in closed state</code> For example: <pre class="prettyprint source lang-js"><code>// WILL FAIL: const { error } = Db.withInstance(db => { db.insertInto('users', user); }); // WILL SUCCEED: const { error, results } = Db.withInstance(db => { return db.insertInto('users', user); }); // ALSO OK: const { error, newUserId } = Db.withInstance(async db => { const { insertId } = await db.insertInto('users', user); return { newUserId: insertId, }; }); </code></pre> <h3>SSH Tunneling</h3> Connect to MySQL through an SSH tunnel <pre class="prettyprint source lang-js"><code>const { Db } = require('sharp-db'); const db = Db.factory({ // MySQL connection as first argument host: '127.0.0.1', port: 3306, user: 'root', password: '', }, { // SSH connection as second argument host: 'example.com', port: 22, user: 'ubuntu', privateKey: '~/.ssh/example.com.pem', }); </code></pre> SSH Tunnel Options <table> <thead> <tr> <th>Option</th> <th>ENV name</th> <th>Default</th> </tr> </thead> <tbody> <tr> <td><code>host</code></td> <td>DB_SSH_HOST</td> <td>"localhost"</td> </tr> <tr> <td><code>port</code></td> <td>DB_SSH_PORT</td> <td>22</td> </tr> <tr> <td><code>user</code></td> <td>DB_SSH_USER</td> <td>none</td> </tr> <tr> <td><code>password</code></td> <td>DB_SSH_PASSWORD</td> <td>none</td> </tr> <tr> <td><code>privateKey</code></td> <td>DB_SSH_PRIVATE_KEY</td> <td>none</td> </tr> <tr> <td><code>localPort</code></td> <td>DB_SSH_LOCAL_PORT</td> <td>12346</td> </tr> </tbody> </table> See all options in <a href="https://github.com/mscdex/ssh2#client-methods">ssh2's npm package</a>. <h3>Basic use</h3> All code examples below assume the <code>Db</code> instance has been stored in <code>db</code>. <h4>Plain select queries</h4> <pre class="prettyprint source lang-js"><code>const { Db } = require('sharp-db'); const db = Db.factory(); const { query, results, fields } = await db.select('SELECT * FROM users'); // query is the final query executed after value binding // results is an Array of objects representing the query results // fields is an Array of objects representing the columns that were returned // Don't forget to close the connection when done db.destroy(); </code></pre> Relevant properties of each <code>fields</code> item: <table> <thead> <tr> <th>Item</th> <th>Description</th> <th>Example</th> </tr> </thead> <tbody> <tr> <td><code>characterSet</code></td> <td><a href="https://github.com/mysqljs/mysql/blob/master/lib/protocol/constants/charsets.js">Character set constant</a></td> <td>45</td> </tr> <tr> <td><code>encoding</code></td> <td>Character set name</td> <td>utf8</td> </tr> <tr> <td><code>name</code></td> <td>Name of column</td> <td>my_column</td> </tr> <tr> <td><code>columnLength</code></td> <td>Number of bytes of field</td> <td>400</td> </tr> <tr> <td><code>columnType</code></td> <td><a href="https://github.com/mysqljs/mysql/blob/master/lib/protocol/constants/types.js">Data type constant</a></td> <td>253</td> </tr> <tr> <td><code>flags</code></td> <td><a href="https://github.com/mysqljs/mysql/blob/master/lib/protocol/constants/field_flags.js">Field flag constant</a></td> <td>33</td> </tr> </tbody> </table> <h3>Bindings</h3> Question-mark and colon-prefixed bindings are supported. <h4>Binding with Question Marks</h4> <pre class="prettyprint source lang-js"><code>const sql = 'SELECT * FROM users WHERE is_active = ? AND department_id = ?'; const { results: users } = await db.select(sql, true, 5); </code></pre> <h4>Named Bindings</h4> <pre class="prettyprint source lang-js"><code>const sql = 'SELECT * FROM users WHERE is_active = :isActive AND department_id = :departmentId'; const { results: users } = await db.select(sql, { isActive: true, departmentId: 5, }); </code></pre> <h4>Binding data types</h4> <pre class="prettyprint source lang-js"><code>const { results: users } = await db.select(sql, { isActive: true, // Boolean departmentId: 5, // Number createdAt: '2020-02-14', // Strings statusCode: [1, 2, 3], // Arrays e.g. IN(1, 2, 3) deletedAt: null, // null e.g. NULL }); </code></pre> <h3>Methods</h3> <h4>selectFirst(sql, ...bindValues)</h4> Get only the first row. <pre class="prettyprint source lang-js"><code>const { results: row } = await db.selectFirst(sql); </code></pre> Example results: <code>{ id: 1, name: "John" }</code> <h4>selectValue(sql, ...bindValues)</h4> Get only the first column of the first row. <pre class="prettyprint source lang-js"><code>const { results: value } = await db.selectValue(sql); </code></pre> Example results: <code>"John"</code> <h4>selectHash(sql, ...bindValues)</h4> Get an Object with column-value pairs. <pre class="prettyprint source lang-js"><code>const { results: hash } = await db.selectHash(sql); </code></pre> Example results: <code>{ "1": "John", "2": "Jane" }</code> <h4>selectList(sql, ...bindValues)</h4> Get an Array of values for the first column of the first row. <pre class="prettyprint source lang-js"><code>const { results: list } = await db.selectList(sql); </code></pre> Example results: <code>["John", "Jane"]</code> <h4>selectExists(sql, ...bindValues)</h4> Return true if query returns any rows. <pre class="prettyprint source lang-js"><code>const { results: doesExist } = await db.selectExists(sql); </code></pre> Example results: <code>true</code> <h4>selectIndexed(indexColumn, sql, ...bindValues)</h4> Return an Object where every result row is indexed by the given field. <pre class="prettyprint source lang-js"><code>const { results: usersById } = await db.selectIndexed('id', sql); </code></pre> Example results: <pre class="prettyprint source lang-js"><code>results = { "1": { id: 1, name: "John" }, "2": { id: 2, name: "Jane" }, } </code></pre> <h4>selectGrouped(groupColumn, sql, ...bindValues)</h4> Return an Object where every result row is indexed by the given field. <pre class="prettyprint source lang-js"><code>const { results: usersGroupedByOrg } = await db.selectGrouped('org', sql); </code></pre> Example results: <pre class="prettyprint source lang-js"><code>results = { "Marketing": [ { id: 1, name: "John", org: "Marketing" }, { id: 2, name: "Jane", org: "Marketing" }, ], "Finance": [ { id: 3, name: "Jose", org: "Finance" }, ], } </code></pre> <h4>selectOrCreate(table, criteria[, newValues])</h4> Select a record or create a new record. Good when normalizing data that is frequently referenced. For example, say I have a table <code>hits</code> with a column <code>url_id</code> and a table <code>urls</code> with columns <code>id</code> and <code>url</code>. I want to add a new hit record with a given URL. You might write this: <pre class="prettyprint source lang-js"><code>const newHit = { date: '2021-10-15 17:43:24', url: 'https://example.com', } const { results } = await db.selectOrCreate('urls', { url: newHit.url }); await db.insert('hits', { date: newHit.date, url_id: results.id, }); </code></pre> <h3>Useful Query Options</h3> SQL can actually be an Object with options. <pre class="prettyprint source lang-js"><code>const options = { sql: ` SELECT users.*, avatars.* FROM users INNER JOIN avatars ON avatars.user_id = users.id WHERE users.is_active = ? `, // kill query if not completed within 30 seconds timeout: 30000, // return records with keys `users` and `avatars` with their own fields nested underneath nestTables: true, // you can also bind values here using question marks values: [true], }; const { results } = await db.select(options); </code></pre> <h4>nestTables Example</h4> Given a query of: <pre class="prettyprint source lang-sql"><code>SELECT users.*, avatars.* FROM users INNER JOIN avatars ON avatars.user_id = users.id WHERE users.is_active = ? </code></pre> nesting tables will return a data structure such as: <pre class="prettyprint source lang-js"><code>results = [ { users: { id: 1, name: 'John Doe', is_active: true, }, avatars: { id: 101, user_id: 1, url: 'http://example.com/john.png' } }, { users: { id: 2, name: 'Jane Doe', is_active: true, }, avatars: { id: 102, user_id: 2, url: 'http://example.com/jane.png' } } ] </code></pre> <h4>selectFrom(table, fields, values)</h4> Build and run a simple select statement. <pre class="prettyprint source lang-js"><code>const { results } = await db.selectFrom('users', ['fname','lname'], { 'id >': 5, is_active: true, department_id: [1,2], }); </code></pre> <h4>insert(sql, ...bindVars)</h4> Run an insert statement; return the id of the new record if applicable. <pre class="prettyprint source lang-js"><code>const { insertId } = await db.insert("INSERT INTO users SET name='John', email='john@example.com'"); </code></pre> <h4>insertInto(table, values)</h4> Build and run an insert statement; return the id of the new record if applicable. <pre class="prettyprint source lang-js"><code>const { insertId } = await db.insertInto('users', { name: 'John', email: 'john@example.com', }); </code></pre> <h4>insertExtended(table, rows)</h4> Build and run an extended insert statement; return the id of the last record if applicable. <pre class="prettyprint source lang-js"><code>const { insertId } = await db.insertExtended('users', [ { name: 'John', email: 'john@example.com' }, { name: 'Jane', email: 'jane@example.com' }, ]); </code></pre> <h4>insertIntoOnDuplicateKeyUpdate(table, insert, update)</h4> Build and run an insert statement; return the id of the new record if applicable. <pre class="prettyprint source lang-js"><code>const { insertId, affectedRows } = await db.insertIntoOnDuplicateKeyUpdate( 'users', { sso_ref: 'A123456', name: 'Jane Doe', created_at: '2020-02-02', }, { name: 'Jane Doe Carter', modified_at: '2020-02-02', } ); </code></pre> <h4>update(sql, ...bindValues)</h4> Run an update statement; return the number of affected rows. <pre class="prettyprint source lang-js"><code>const { affectedRows } = await db.update( "UPDATE users SET name = ? WHERE id = ?", 'Jane Doe Carter', 5 ); </code></pre> <h4>updateTable(table, set, where)</h4> Build and run an update statement; return the number of affected rows. <pre class="prettyprint source lang-js"><code>const { affectedRows } = await db.updateTable( 'users', { name: 'Jane Doe Carter' }, { id: 5 } ); </code></pre> <h4>delete(sql, ...bindValues)</h4> Run a delete statement; return the number of affected rows. <pre class="prettyprint source lang-js"><code>const { affectedRows } = await db.delete( "DELETE FROM users WHERE id = ? LIMIT 1", 5 ); </code></pre> <h4>deleteFrom(table, where, limit)</h4> Build and run a delete statement; return the number of affected rows. <pre class="prettyprint source lang-js"><code>const { affectedRows } = await db.deleteFrom('users', { id: 5 }, 1); </code></pre> <h4>query(sql, ...bindValues)</h4> Run any type of statement. <pre class="prettyprint source lang-js"><code>const { query, results, fields } = await db.query( 'SELECT * FROM users' ); </code></pre> <h4>multiQuery(sql, ...bindValues)</h4> Run multiple statements delimited by semicolon. <pre class="prettyprint source lang-js"><code>const { query, results, fields } = await db.query( 'SELECT * FROM users; SELECT * FROM tags' ); </code></pre> <h3>Solutions to Common Problems</h3> <h4>Connection is in closed state</h4> <code>Error: Can't add new command when connection is in closed state</code> Make sure you use <code>await</code> your results before closing your connection. <h4>ECONNRESET or error event</h4> <code>Error: read ECONNRESET</code> or <code>Emitted 'error' event on Client instance</code> Your SSH connection may have timed out. To keep connection alive, you can send keepalive packets. <pre class="prettyprint source lang-js"><code>const sshConfig = { // ... // How often (in milliseconds) to send SSH-level keepalive packets to the server (in a similar way as OpenSSH's ServerAliveInterval config option). Set to 0 to disable. Default: 0 keepaliveInterval: 30, // How many consecutive, unanswered SSH-level keepalive packets that can be sent to the server before disconnection (similar to OpenSSH's ServerAliveCountMax config option). Default: 3 keepaliveCountMax: 120, } const db = new Db(mysqlConfig, sshConfig); </code></pre> <h2>Select</h2> A Select object represents a SQL SELECT query and allows dynamically adding clauses including JOIN, WHERE, ORDER BY, LIMIT, OFFSET. <h3>Select.parse()</h3> The easiest way to define a base query is to use <code>Select.parse(sql)</code> and then add criteria as needed. <pre class="prettyprint source lang-js"><code>const { Select } = require('sharp-db'); const query = Select.parse(` SELECT u.id, u.fname, u.lname, u.email, p.phone FROM users LEFT JOIN phone_numbers p ON p.user_id = u.id AND p.type = 'main' WHERE u.is_active = 1 `); if (email) { query.where('u.email', email); } if (areaCode) { query.where('p.phone', 'LIKE ?%', areaCode); } query.sort(sortField); query.limit(limitTo); </code></pre> You can also define binding in the base query itself. <pre class="prettyprint source lang-js"><code>const query = Select.parse(` SELECT u.id, u.fname, u.lname, u.email, a.city, a.zip FROM users LEFT JOIN addresses a ON a.user_id = u.id WHERE a.state = :state `); query.bind('state', state); </code></pre> And you can bind multiple values at once. <pre class="prettyprint source lang-js"><code>const query = Select.parse(` SELECT u.id, u.fname, u.lname, u.email, a.city, a.zip FROM users LEFT JOIN addresses a ON a.user_id = u.id WHERE a.state = :state AND a.city IN (:city) `); query.bind({ state, city }); </code></pre> <h3>Building the Query</h3> The following are the most common methods for building queries. <ul> <li><code>query.columns(columnNames)</code> - Add column names to fetch</li> <li><code>query.column(columnName)</code> - Add a column name to fetch</li> <li><code>query.table(tableName)</code> - Specify the table in the FROM clause</li> <li><code>query.from(tableName)</code> - Same as above</li> <li><code>query.innerJoin(expression)</code> - Add an INNER JOIN expression</li> <li><code>query.leftJoin(expression)</code> - Add a LEFT JOIN expression</li> <li><code>query.fullJoin(expression)</code> - Add a FULL JOIN expression</li> <li><code>query.rightJoin(expression)</code> - Add a RIGHT JOIN expression</li> <li><code>query.crossJoin(expression)</code> - Add a CROSS JOIN expression</li> <li><code>query.leftOuterJoin(expression)</code> - Add a LEFT OUTER JOIN expression</li> <li><code>query.fullOuterJoin(expression)</code> - Add a FULL OUTER JOIN expression</li> <li><code>query.rightOuterJoin(expression)</code> - Add a RIGHT OUTER JOIN expression</li> <li><code>query.groupBy(column)</code> - Group by a column or expression</li> <li><code>query.where(column, operator, value)</code> - Require column satisfy operator</li> <li><code>query.where(column, value)</code> - Require column equal a value</li> <li><code>query.where(expression)</code> - Add an arbitrary WHERE expression</li> <li><code>query.where(columnValuePairs)</code> - Add multiple conditions</li> <li><code>query.whereBetween(column, twoValueArray)</code> - Require value BETWEEN, < or ></li> <li><code>query.orWhere(conditions)</code> - Specify multiple <code>where()</code>s joined by <code>OR</code></li> <li><code>query.having(column, operator, value)</code> - Having column satisfy operator</li> <li><code>query.having(column, value)</code> - Having column equal value</li> <li><code>query.having(column, value)</code> - Having column equal value</li> <li><code>query.having(expression)</code> - Having an arbitrary expression</li> <li><code>query.orHaving(expressions)</code> - Multiple <code>having()</code>s joined by OR</li> <li><code>query.orderBy(column)</code> - Add ORDER BY clause</li> <li><code>query.sortField(column, mapNames)</code> - Add ORDER BY clause with mapNames</li> <li><code>query.limit(num)</code> - Limit by the given number</li> <li><code>query.offset(num)</code> - Specify an offset</li> <li><code>query.page(num)</code> - Automatically calculate offset based on limit and page</li> </ul> <h3>Fetching Data</h3> The methods to fetch data mirror those of Db. <ul> <li><code>query.fetch()</code> - equivalent to <code>db.select()</code></li> <li><code>query.fetchFirst()</code> - equivalent to <code>db.selectFirst()</code></li> <li><code>query.fetchHashed()</code> - equivalent to <code>db.selectHashed()</code></li> <li><code>query.fetchList()</code> - equivalent to <code>db.selectList()</code></li> <li><code>query.fetchValue()</code> - equivalent to <code>db.selectValue()</code></li> <li><code>query.fetchIndexed(byField)</code> - equivalent to <code>db.selectIndexed(byField)</code></li> <li><code>query.fetchGrouped(byField)</code> - equivalent to <code>db.selectGrouped(byField)</code></li> </ul> <h3>Counting Results</h3> One powerful feature of Select is that it can construct a count query to fetch the number of results that would have been returned if there were no LIMIT. <pre class="prettyprint source lang-js"><code>const query = Select.parse('SELECT id, name FROM users LIMIT 5'); const { results: users } = await query.fetch(); const { results: count } = await query.foundRows(); // will run the following query: // SELECT COUNT(*) AS foundRows FROM users </code></pre> <h3>Specifying the <code>Db</code> Instance to Use</h3> There are three ways to specify the <code>Db</code> instance to fetch data with: <ol> <li><code>query = Select.parse(sql, db)</code></li> <li><code>query = new Select(db)</code></li> <li><code>query.db = db</code></li> </ol> If no instance is specified, <code>Db.factory()</code> is used. <h3>Dependent Data</h3> A Select object can splice in sibling or child data for each row. <h4>withSiblingData(propertyName, siblingSql)</h4> Example: <pre class="prettyprint source lang-js"><code>const query = Select.parse('SELECT id, name FROM users'); query.withSiblingData( 'homeAddress', Select.parse(` SELECT * FROM addresses WHERE addresses.user_id IN(:id) AND addresses.type = 'home' AND addresses.deleted_at IS NULL `), ); query.withSiblingData( 'workAddress', Select.parse(` SELECT * FROM addresses WHERE addresses.user_id IN(:id) AND addresses.type = 'work' AND addresses.deleted_at IS NULL `), ); const { results } = await query.fetch(); </code></pre> ...and <code>results</code> for example may equal: <pre class="prettyprint source lang-js"><code>results = [ { id: 1, name: 'John', homeAddress: { id: 11, type: 'home', is_active: 1, user_id: 1, street: '123 Any St.', city: 'Any Town', state: 'CA' }, workAddress: { id: 12, type: 'work', is_active: 1, user_id: 1, street: '123 Commerce Dr.', city: 'Any Town', state: 'CA', }, }, { id: 2, name: 'Jane', // rows without sibling data will be null homeAddress: null, workAddress: { id: 12, type: 'work', is_active: 1, user_id: 2, street: '123 Tower Blvd.', city: 'Any Town', state: 'CA', }, } ] </code></pre> <h4>withChildData(propertyName, childSql)</h4> Example: <pre class="prettyprint source lang-js"><code>const query = Select.parse('SELECT id, headline, published_by FROM posts'); query.withChildData( 'theComments', Select.parse('SELECT * FROM comments WHERE comments.post_id IN(:id)') ); query.withChildData( 'theTags', Select.parse(` SELECT posts_tags.post_id, tags.* FROM tags INNER JOIN posts_tags ON posts_tags.tag_id = tags.id WHERE posts_tags.post_id IN(:id) `) ); query.withSiblingData( 'thePublisher', Select.parse('SELECT id, name FROM users WHERE user_id IN(:published_by)') ); const { results } = await query.fetch(); </code></pre> ...and <code>results</code> for example may equal: <pre class="prettyprint source lang-js"><code>results = [ { id: 1, headline: 'Turmoil in China', published_by: 1001, theComments: [ { id: 11, post_id: 1, user_id: 101, text: 'Sad to hear', }, { id: 12, post_id: 1, user_id: 102, text: 'Hope it works out', }, ], theTags: [ { id: 101, post_id: 1, name: 'China', }, { id: