yujunjun/knex
1
0
Fork 0
mirror of https://github.com/knex/knex.git synced 2025-07-31 12:52:02 +00:00
Code Issues Packages Projects Releases Wiki Activity
knex/docs/lib/common.html
Tim Griesser 373868cfbc docs update for 0.5.2
2013-12-18 17:27:16 -05:00

100 lines
20 KiB
HTML
Raw Blame History

<!DOCTYPE html><html lang="en"><head><title>lib/common</title></head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0"><meta name="groc-relative-root" content="../"><meta name="groc-document-path" content="lib/common"><meta name="groc-project-path" content="lib/common.js"><link rel="stylesheet" type="text/css" media="all" href="../assets/style.css"><script type="text/javascript" src="../assets/behavior.js"></script><body><div id="meta"><div class="file-path">lib/common.js</div></div><div id="document"><div class="segment"><div class="comments"><div class="wrapper"><h2 id="common">Common</h2></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Some functions which are common to both the
<code>Builder</code> and <code>SchemaBuilder</code> classes.</p></div></div><div class="code"><div class="wrapper"><span class="kd">var</span> <span class="nx">_</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;lodash&#39;</span><span class="p">);</span>
<span class="kd">var</span> <span class="nx">Helpers</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;./helpers&#39;</span><span class="p">).</span><span class="nx">Helpers</span><span class="p">;</span>
<span class="kd">var</span> <span class="nx">SqlString</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;./sqlstring&#39;</span><span class="p">).</span><span class="nx">SqlString</span><span class="p">;</span>
<span class="kd">var</span> <span class="nx">Promise</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;./promise&#39;</span><span class="p">).</span><span class="nx">Promise</span><span class="p">;</span>
<span class="kd">var</span> <span class="nx">push</span> <span class="o">=</span> <span class="p">[].</span><span class="nx">push</span><span class="p">;</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Methods common to both the <code>Grammar</code> and <code>SchemaGrammar</code> interfaces,
used to generate the sql in one form or another.</p></div></div><div class="code"><div class="wrapper"><span class="nx">exports</span><span class="p">.</span><span class="nx">Common</span> <span class="o">=</span> <span class="p">{</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Creates a new instance of the current <code>Builder</code> or <code>SchemaBuilder</code>,
with the correct current <code>knex</code> instance.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">instance</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">builder</span> <span class="o">=</span> <span class="k">new</span> <span class="k">this</span><span class="p">.</span><span class="nx">constructor</span><span class="p">(</span><span class="k">this</span><span class="p">.</span><span class="nx">knex</span><span class="p">);</span>
<span class="nx">builder</span><span class="p">.</span><span class="nx">table</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">table</span><span class="p">;</span>
<span class="k">return</span> <span class="nx">builder</span><span class="p">;</span>
<span class="p">},</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Sets the flag, so that when this object is passed into the
client adapter, we know to <code>log</code> the query.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">debug</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="k">this</span><span class="p">.</span><span class="nx">flags</span><span class="p">.</span><span class="nx">debug</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span>
<span class="k">return</span> <span class="k">this</span><span class="p">;</span>
<span class="p">},</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Sets <code>options</code> which are passed along to the database client.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">options</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">opts</span><span class="p">)</span> <span class="p">{</span>
<span class="k">this</span><span class="p">.</span><span class="nx">flags</span><span class="p">.</span><span class="nx">options</span> <span class="o">=</span> <span class="nx">_</span><span class="p">.</span><span class="nx">extend</span><span class="p">({},</span> <span class="k">this</span><span class="p">.</span><span class="nx">flags</span><span class="p">.</span><span class="nx">options</span><span class="p">,</span> <span class="nx">opts</span><span class="p">);</span>
<span class="k">return</span> <span class="k">this</span><span class="p">;</span>
<span class="p">},</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>For those who dislike promise interfaces.
Multiple calls to <code>exec</code> will resolve with the same value
if called more than once. Any unhandled errors will be thrown
after the last block.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">exec</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">callback</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="k">this</span><span class="p">.</span><span class="nx">then</span><span class="p">().</span><span class="nx">nodeify</span><span class="p">(</span><span class="nx">callback</span><span class="p">);</span>
<span class="p">},</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>The promise interface for the query builder.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">then</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">onFulfilled</span><span class="p">,</span> <span class="nx">onRejected</span><span class="p">)</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="k">this</span><span class="p">.</span><span class="nx">_promise</span><span class="p">)</span> <span class="p">{</span>
<span class="k">this</span><span class="p">.</span><span class="nx">_promise</span> <span class="o">=</span> <span class="nx">Promise</span><span class="p">.</span><span class="nx">bind</span><span class="p">(</span><span class="k">this</span><span class="p">);</span>
<span class="k">this</span><span class="p">.</span><span class="nx">_promise</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">_promise</span><span class="p">.</span><span class="nx">then</span><span class="p">(</span><span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="k">return</span> <span class="k">this</span><span class="p">.</span><span class="nx">client</span><span class="p">.</span><span class="nx">query</span><span class="p">(</span><span class="k">this</span><span class="p">);</span>
<span class="p">}).</span><span class="nx">bind</span><span class="p">();</span>
<span class="p">}</span>
<span class="k">return</span> <span class="k">this</span><span class="p">.</span><span class="nx">_promise</span><span class="p">.</span><span class="nx">then</span><span class="p">(</span><span class="nx">onFulfilled</span><span class="p">,</span> <span class="nx">onRejected</span><span class="p">);</span>
<span class="p">},</span>
<span class="k">catch</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="k">return</span> <span class="k">this</span><span class="p">.</span><span class="nx">caught</span><span class="p">.</span><span class="nx">apply</span><span class="p">(</span><span class="k">this</span><span class="p">,</span> <span class="nx">arguments</span><span class="p">);</span>
<span class="p">},</span>
<span class="nx">caught</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">promise</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">then</span><span class="p">();</span>
<span class="k">return</span> <span class="nx">promise</span><span class="p">.</span><span class="nx">caught</span><span class="p">.</span><span class="nx">apply</span><span class="p">(</span><span class="nx">promise</span><span class="p">,</span> <span class="nx">arguments</span><span class="p">);</span>
<span class="p">},</span>
<span class="nx">lastly</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">promise</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">then</span><span class="p">();</span>
<span class="k">return</span> <span class="nx">promise</span><span class="p">.</span><span class="nx">lastly</span><span class="p">.</span><span class="nx">apply</span><span class="p">(</span><span class="nx">promise</span><span class="p">,</span> <span class="nx">arguments</span><span class="p">);</span>
<span class="p">},</span>
<span class="k">finally</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="k">return</span> <span class="k">this</span><span class="p">.</span><span class="nx">lastly</span><span class="p">.</span><span class="nx">apply</span><span class="p">(</span><span class="k">this</span><span class="p">,</span> <span class="nx">arguments</span><span class="p">);</span>
<span class="p">},</span>
<span class="nx">tap</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">handler</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="k">this</span><span class="p">.</span><span class="nx">then</span><span class="p">().</span><span class="nx">tap</span><span class="p">(</span><span class="nx">handler</span><span class="p">);</span>
<span class="p">},</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Returns an array of query strings filled out with the
correct values based on bindings, etc. Useful for debugging.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">toString</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>TODO: get rid of the need to clone the object here...</p></div></div><div class="code"><div class="wrapper"> <span class="kd">var</span> <span class="nx">builder</span> <span class="o">=</span> <span class="k">this</span><span class="p">,</span> <span class="nx">data</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">clone</span><span class="p">().</span><span class="nx">toSql</span><span class="p">();</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">_</span><span class="p">.</span><span class="nx">isArray</span><span class="p">(</span><span class="nx">data</span><span class="p">))</span> <span class="nx">data</span> <span class="o">=</span> <span class="p">[</span><span class="nx">data</span><span class="p">];</span>
<span class="k">return</span> <span class="nx">_</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="nx">data</span><span class="p">,</span> <span class="kd">function</span><span class="p">(</span><span class="nx">str</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="nx">SqlString</span><span class="p">.</span><span class="nx">format</span><span class="p">(</span><span class="nx">str</span><span class="p">,</span> <span class="nx">builder</span><span class="p">.</span><span class="nx">getBindings</span><span class="p">());</span>
<span class="p">}).</span><span class="nx">join</span><span class="p">(</span><span class="s1">&#39;; &#39;</span><span class="p">);</span>
<span class="p">},</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Converts the current statement to a sql string</p></div></div><div class="code"><div class="wrapper"> <span class="nx">toSql</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="k">return</span> <span class="k">this</span><span class="p">.</span><span class="nx">grammar</span><span class="p">.</span><span class="nx">toSql</span><span class="p">(</span><span class="k">this</span><span class="p">);</span>
<span class="p">},</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Explicitly sets the connection.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">connection</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">connection</span><span class="p">)</span> <span class="p">{</span>
<span class="k">this</span><span class="p">.</span><span class="nx">usingConnection</span> <span class="o">=</span> <span class="nx">connection</span><span class="p">;</span>
<span class="k">return</span> <span class="k">this</span><span class="p">;</span>
<span class="p">},</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>The connection the current query is being run on, optionally
specified by the <code>connection</code> method.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">usingConnection</span><span class="o">:</span> <span class="kc">false</span><span class="p">,</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Default handler for a response is to pass it along.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">handleResponse</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">resp</span><span class="p">)</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="k">this</span> <span class="o">&amp;&amp;</span> <span class="k">this</span><span class="p">.</span><span class="nx">grammar</span> <span class="o">&amp;&amp;</span> <span class="k">this</span><span class="p">.</span><span class="nx">grammar</span><span class="p">.</span><span class="nx">handleResponse</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="k">this</span><span class="p">.</span><span class="nx">grammar</span><span class="p">.</span><span class="nx">handleResponse</span><span class="p">(</span><span class="k">this</span><span class="p">,</span> <span class="nx">resp</span><span class="p">);</span>
<span class="p">}</span>
<span class="k">return</span> <span class="nx">resp</span><span class="p">;</span>
<span class="p">},</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Sets the "type" of the current query, so we can potentially place
<code>select</code>, <code>update</code>, <code>del</code>, etc. anywhere in the query statement
and have it come out fine.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">_setType</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">type</span><span class="p">)</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="k">this</span><span class="p">.</span><span class="nx">type</span><span class="p">)</span> <span class="p">{</span>
<span class="k">throw</span> <span class="k">new</span> <span class="nb">Error</span><span class="p">(</span><span class="s1">&#39;The query type has already been set to &#39;</span> <span class="o">+</span> <span class="k">this</span><span class="p">.</span><span class="nx">type</span><span class="p">);</span>
<span class="p">}</span>
<span class="k">this</span><span class="p">.</span><span class="nx">type</span> <span class="o">=</span> <span class="nx">type</span><span class="p">;</span>
<span class="k">return</span> <span class="k">this</span><span class="p">;</span>
<span class="p">},</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Returns all bindings excluding the <code>Knex.Raw</code> types.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">getBindings</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="k">return</span> <span class="k">this</span><span class="p">.</span><span class="nx">grammar</span><span class="p">.</span><span class="nx">getBindings</span><span class="p">(</span><span class="k">this</span><span class="p">);</span>
<span class="p">},</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Sets the current Builder connection to that of the
the currently running transaction</p></div></div><div class="code"><div class="wrapper"> <span class="nx">transacting</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">t</span><span class="p">)</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="nx">t</span><span class="p">)</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="k">this</span><span class="p">.</span><span class="nx">transaction</span><span class="p">)</span> <span class="k">throw</span> <span class="k">new</span> <span class="nb">Error</span><span class="p">(</span><span class="s1">&#39;A transaction has already been set for the current query chain&#39;</span><span class="p">);</span>
<span class="kd">var</span> <span class="nx">flags</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">flags</span><span class="p">;</span>
<span class="k">this</span><span class="p">.</span><span class="nx">transaction</span> <span class="o">=</span> <span class="nx">t</span><span class="p">;</span>
<span class="k">this</span><span class="p">.</span><span class="nx">usingConnection</span> <span class="o">=</span> <span class="nx">t</span><span class="p">.</span><span class="nx">connection</span><span class="p">;</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Add "forUpdate" and "forShare" here, since these are only relevant
within the context of a transaction.</p></div></div><div class="code"><div class="wrapper"> <span class="k">this</span><span class="p">.</span><span class="nx">forUpdate</span> <span class="o">=</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="nx">flags</span><span class="p">.</span><span class="nx">selectMode</span> <span class="o">=</span> <span class="s1">&#39;ForUpdate&#39;</span><span class="p">;</span>
<span class="p">};</span>
<span class="k">this</span><span class="p">.</span><span class="nx">forShare</span> <span class="o">=</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="nx">flags</span><span class="p">.</span><span class="nx">selectMode</span> <span class="o">=</span> <span class="s1">&#39;ForShare&#39;</span><span class="p">;</span>
<span class="p">};</span>
<span class="p">}</span>
<span class="k">return</span> <span class="k">this</span><span class="p">;</span>
<span class="p">}</span>
<span class="p">};</span></div></div></div></div></body></html>
Reference in New Issue View Git Blame Copy Permalink