knex/docs/clients/server/base.html

91 lines
21 KiB
HTML
Raw Normal View History

2013-11-25 02:06:42 -05:00
<!DOCTYPE html><html lang="en"><head><title>clients/server/base</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="clients/server/base"><meta name="groc-project-path" content="clients/server/base.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">clients/server/base.js</div></div><div id="document"><div class="segment"><div class="comments"><div class="wrapper"><h2 id="serverbase">ServerBase</h2></div></div></div><div class="segment"><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>
2013-09-13 13:50:41 -04:00
<span class="kd">var</span> <span class="nx">Pool</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;../pool&#39;</span><span class="p">).</span><span class="nx">Pool</span><span class="p">;</span>
<span class="kd">var</span> <span class="nx">ClientBase</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;../base&#39;</span><span class="p">).</span><span class="nx">ClientBase</span><span class="p">;</span>
2013-11-25 02:06:42 -05:00
<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;../../lib/promise&#39;</span><span class="p">).</span><span class="nx">Promise</span><span class="p">;</span>
2013-09-13 13:50:41 -04:00
<span class="kd">var</span> <span class="nx">ServerBase</span> <span class="o">=</span> <span class="nx">ClientBase</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Pass a config object into the constructor,
which then initializes the pool and</p></div></div><div class="code"><div class="wrapper"> <span class="nx">constructor</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">config</span><span class="p">)</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="nx">config</span><span class="p">.</span><span class="nx">debug</span><span class="p">)</span> <span class="k">this</span><span class="p">.</span><span class="nx">isDebugging</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span>
2013-09-17 07:15:18 -04:00
<span class="k">this</span><span class="p">.</span><span class="nx">attachGrammars</span><span class="p">();</span>
2013-09-13 13:50:41 -04:00
<span class="k">this</span><span class="p">.</span><span class="nx">connectionSettings</span> <span class="o">=</span> <span class="nx">config</span><span class="p">.</span><span class="nx">connection</span><span class="p">;</span>
<span class="k">this</span><span class="p">.</span><span class="nx">initPool</span><span class="p">(</span><span class="nx">config</span><span class="p">.</span><span class="nx">pool</span><span class="p">);</span>
<span class="nx">_</span><span class="p">.</span><span class="nx">bindAll</span><span class="p">(</span><span class="k">this</span><span class="p">,</span> <span class="s1">&#39;getRawConnection&#39;</span><span class="p">);</span>
2013-09-13 16:58:38 -04:00
<span class="p">},</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Initialize a pool with the apporpriate configuration and
2013-09-13 13:50:41 -04:00
bind the pool to the current client object.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">initPool</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">poolConfig</span><span class="p">)</span> <span class="p">{</span>
2013-09-24 09:15:50 -04:00
<span class="k">this</span><span class="p">.</span><span class="nx">pool</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Pool</span><span class="p">(</span><span class="nx">_</span><span class="p">.</span><span class="nx">extend</span><span class="p">({},</span> <span class="nx">_</span><span class="p">.</span><span class="nx">result</span><span class="p">(</span><span class="k">this</span><span class="p">,</span> <span class="s1">&#39;poolDefaults&#39;</span><span class="p">),</span> <span class="nx">poolConfig</span><span class="p">),</span> <span class="k">this</span><span class="p">);</span>
2013-09-13 13:50:41 -04:00
<span class="p">},</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Execute a query on the specified Builder or QueryBuilder
interface. If a <code>connection</code> is specified, use it, otherwise
acquire a connection, and then dispose of it when we're done.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">query</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">builder</span><span class="p">)</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">conn</span><span class="p">,</span> <span class="nx">client</span> <span class="o">=</span> <span class="k">this</span><span class="p">;</span>
<span class="kd">var</span> <span class="nx">sql</span> <span class="o">=</span> <span class="nx">builder</span><span class="p">.</span><span class="nx">toSql</span><span class="p">(</span><span class="nx">builder</span><span class="p">);</span>
2013-09-13 16:58:38 -04:00
<span class="kd">var</span> <span class="nx">bindings</span> <span class="o">=</span> <span class="nx">builder</span><span class="p">.</span><span class="nx">getBindings</span><span class="p">();</span>
2013-09-13 13:50:41 -04:00
<span class="kd">var</span> <span class="nx">chain</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">getConnection</span><span class="p">(</span><span class="nx">builder</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="nx">connection</span><span class="p">)</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="nx">client</span><span class="p">.</span><span class="nx">isDebugging</span> <span class="o">||</span> <span class="nx">builder</span><span class="p">.</span><span class="nx">flags</span><span class="p">.</span><span class="nx">debug</span><span class="p">)</span> <span class="p">{</span>
2013-09-13 13:50:41 -04:00
<span class="nx">client</span><span class="p">.</span><span class="nx">debug</span><span class="p">(</span><span class="nx">sql</span><span class="p">,</span> <span class="nx">bindings</span><span class="p">,</span> <span class="nx">connection</span><span class="p">,</span> <span class="nx">builder</span><span class="p">);</span>
<span class="p">}</span>
<span class="nx">conn</span> <span class="o">=</span> <span class="nx">connection</span><span class="p">;</span>
<span class="k">if</span> <span class="p">(</span><span class="nx">_</span><span class="p">.</span><span class="nx">isArray</span><span class="p">(</span><span class="nx">sql</span><span class="p">))</span> <span class="p">{</span>
2013-11-25 02:06:42 -05:00
<span class="kd">var</span> <span class="nx">current</span> <span class="o">=</span> <span class="nx">Promise</span><span class="p">.</span><span class="nx">fulfilled</span><span class="p">();</span>
<span class="k">return</span> <span class="nx">Promise</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="nx">sql</span><span class="p">,</span> <span class="kd">function</span><span class="p">(</span><span class="nx">query</span><span class="p">,</span> <span class="nx">i</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">current</span> <span class="o">=</span> <span class="nx">current</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="nx">builder</span><span class="p">.</span><span class="nx">currentIndex</span> <span class="o">=</span> <span class="nx">i</span><span class="p">;</span>
<span class="k">return</span> <span class="nx">client</span><span class="p">.</span><span class="nx">runQuery</span><span class="p">(</span><span class="nx">connection</span><span class="p">,</span> <span class="nx">query</span><span class="p">,</span> <span class="nx">bindings</span><span class="p">,</span> <span class="nx">builder</span><span class="p">);</span>
<span class="p">});</span>
<span class="k">return</span> <span class="nx">current</span><span class="p">;</span>
<span class="p">});</span>
2013-09-13 13:50:41 -04:00
<span class="p">}</span>
<span class="k">return</span> <span class="nx">client</span><span class="p">.</span><span class="nx">runQuery</span><span class="p">(</span><span class="nx">connection</span><span class="p">,</span> <span class="nx">sql</span><span class="p">,</span> <span class="nx">bindings</span><span class="p">,</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>If the builder came with a supplied connection, then we won't do
anything to it (most commonly in the case of transactions)... otherwise,
ensure the connection gets dumped back into the client pool.</p></div></div><div class="code"><div class="wrapper"> <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">builder</span><span class="p">.</span><span class="nx">usingConnection</span><span class="p">)</span> <span class="p">{</span>
2013-09-13 13:50:41 -04:00
<span class="nx">chain</span> <span class="o">=</span> <span class="nx">chain</span><span class="p">.</span><span class="nx">ensure</span><span class="p">(</span><span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
2013-10-02 10:47:43 -04:00
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">conn</span><span class="p">)</span> <span class="p">{</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>The connection must have failed to initialize. Avoid pushing undefined
into the connection pool.</p></div></div><div class="code"><div class="wrapper"> <span class="k">return</span><span class="p">;</span>
<span class="p">}</span>
2013-09-13 13:50:41 -04:00
<span class="nx">client</span><span class="p">.</span><span class="nx">pool</span><span class="p">.</span><span class="nx">release</span><span class="p">(</span><span class="nx">conn</span><span class="p">);</span>
<span class="p">});</span>
<span class="p">}</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Since we usually only need the <code>sql</code> and <code>bindings</code> to help us debug the query, output them
into a new error... this way, it <code>console.log</code>'s nicely for debugging, but you can also
parse them out with a <code>JSON.parse(error.message)</code>. Also, use the original <code>clientError</code> from the
2013-11-25 02:06:42 -05:00
database client is retained as a property on the <code>newError</code>, for any additional info.</p></div></div><div class="code"><div class="wrapper"> <span class="k">return</span> <span class="nx">chain</span><span class="p">.</span><span class="nx">then</span><span class="p">(</span><span class="nx">builder</span><span class="p">.</span><span class="nx">handleResponse</span><span class="p">).</span><span class="nx">caught</span><span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">error</span><span class="p">)</span> <span class="p">{</span>
2013-10-07 08:27:16 -04:00
<span class="kd">var</span> <span class="nx">newError</span> <span class="o">=</span> <span class="k">new</span> <span class="nb">Error</span><span class="p">(</span><span class="nx">error</span><span class="p">.</span><span class="nx">message</span> <span class="o">+</span> <span class="s1">&#39;, sql: &#39;</span> <span class="o">+</span> <span class="nx">sql</span> <span class="o">+</span> <span class="s1">&#39;, bindings: &#39;</span> <span class="o">+</span> <span class="nx">bindings</span><span class="p">);</span>
<span class="nx">newError</span><span class="p">.</span><span class="nx">sql</span> <span class="o">=</span> <span class="nx">sql</span><span class="p">;</span>
<span class="nx">newError</span><span class="p">.</span><span class="nx">bindings</span> <span class="o">=</span> <span class="nx">bindings</span><span class="p">;</span>
<span class="nx">newError</span><span class="p">.</span><span class="nx">clientError</span> <span class="o">=</span> <span class="nx">error</span><span class="p">;</span>
<span class="k">throw</span> <span class="nx">newError</span><span class="p">;</span>
2013-09-24 09:15:50 -04:00
<span class="p">});</span>
2013-09-13 13:50:41 -04:00
<span class="p">},</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Debug a 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="nx">sql</span><span class="p">,</span> <span class="nx">bindings</span><span class="p">,</span> <span class="nx">connection</span><span class="p">,</span> <span class="nx">builder</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">({</span><span class="nx">sql</span><span class="o">:</span> <span class="nx">sql</span><span class="p">,</span> <span class="nx">bindings</span><span class="o">:</span> <span class="nx">bindings</span><span class="p">,</span> <span class="nx">__cid</span><span class="o">:</span> <span class="nx">connection</span><span class="p">.</span><span class="nx">__cid</span><span class="p">});</span>
<span class="p">},</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Retrieves a connection from the connection pool,
returning a promise.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">getConnection</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">builder</span><span class="p">)</span> <span class="p">{</span>
2013-11-25 02:06:42 -05:00
<span class="k">if</span> <span class="p">(</span><span class="nx">builder</span> <span class="o">&amp;&amp;</span> <span class="nx">builder</span><span class="p">.</span><span class="nx">usingConnection</span><span class="p">)</span> <span class="k">return</span> <span class="nx">Promise</span><span class="p">.</span><span class="nx">fulfilled</span><span class="p">(</span><span class="nx">builder</span><span class="p">.</span><span class="nx">usingConnection</span><span class="p">);</span>
<span class="k">return</span> <span class="nx">Promise</span><span class="p">.</span><span class="nx">promisify</span><span class="p">(</span><span class="k">this</span><span class="p">.</span><span class="nx">pool</span><span class="p">.</span><span class="nx">acquire</span><span class="p">,</span> <span class="k">this</span><span class="p">.</span><span class="nx">pool</span><span class="p">)();</span>
2013-09-13 13:50:41 -04:00
<span class="p">},</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Releases a connection from the connection pool,
returning a promise.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">releaseConnection</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">conn</span><span class="p">)</span> <span class="p">{</span>
2013-11-25 02:06:42 -05:00
<span class="k">return</span> <span class="nx">Promise</span><span class="p">.</span><span class="nx">promisify</span><span class="p">(</span><span class="k">this</span><span class="p">.</span><span class="nx">pool</span><span class="p">.</span><span class="nx">release</span><span class="p">)(</span><span class="nx">conn</span><span class="p">);</span>
2013-09-13 13:50:41 -04:00
<span class="p">},</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Begins a transaction statement on the instance,
resolving with the connection of the current transaction.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">startTransaction</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">getConnection</span><span class="p">()</span>
<span class="p">.</span><span class="nx">tap</span><span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">connection</span><span class="p">)</span> <span class="p">{</span>
2013-11-25 02:06:42 -05:00
<span class="k">return</span> <span class="nx">Promise</span><span class="p">.</span><span class="nx">promisify</span><span class="p">(</span><span class="nx">connection</span><span class="p">.</span><span class="nx">query</span><span class="p">,</span> <span class="nx">connection</span><span class="p">)(</span><span class="s1">&#39;begin;&#39;</span><span class="p">,</span> <span class="p">[]);</span>
2013-09-13 13:50:41 -04:00
<span class="p">});</span>
<span class="p">},</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Finishes the transaction statement on the instance.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">finishTransaction</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="nx">transaction</span><span class="p">,</span> <span class="nx">msg</span><span class="p">)</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">client</span> <span class="o">=</span> <span class="k">this</span><span class="p">;</span>
<span class="kd">var</span> <span class="nx">dfd</span> <span class="o">=</span> <span class="nx">transaction</span><span class="p">.</span><span class="nx">dfd</span><span class="p">;</span>
2013-11-25 02:06:42 -05:00
<span class="nx">Promise</span><span class="p">.</span><span class="nx">promisify</span><span class="p">(</span><span class="nx">transaction</span><span class="p">.</span><span class="nx">connection</span><span class="p">.</span><span class="nx">query</span><span class="p">,</span> <span class="nx">transaction</span><span class="p">.</span><span class="nx">connection</span><span class="p">)(</span><span class="nx">type</span> <span class="o">+</span> <span class="s1">&#39;;&#39;</span><span class="p">,</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="nx">resp</span><span class="p">)</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="nx">type</span> <span class="o">===</span> <span class="s1">&#39;commit&#39;</span><span class="p">)</span> <span class="nx">dfd</span><span class="p">.</span><span class="nx">fulfill</span><span class="p">(</span><span class="nx">msg</span> <span class="o">||</span> <span class="nx">resp</span><span class="p">);</span>
2013-09-13 13:50:41 -04:00
<span class="k">if</span> <span class="p">(</span><span class="nx">type</span> <span class="o">===</span> <span class="s1">&#39;rollback&#39;</span><span class="p">)</span> <span class="nx">dfd</span><span class="p">.</span><span class="nx">reject</span><span class="p">(</span><span class="nx">msg</span> <span class="o">||</span> <span class="nx">resp</span><span class="p">);</span>
<span class="p">},</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">err</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">dfd</span><span class="p">.</span><span class="nx">reject</span><span class="p">(</span><span class="nx">err</span><span class="p">);</span>
<span class="p">}).</span><span class="nx">ensure</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="nx">client</span><span class="p">.</span><span class="nx">releaseConnection</span><span class="p">(</span><span class="nx">transaction</span><span class="p">.</span><span class="nx">connection</span><span class="p">).</span><span class="nx">tap</span><span class="p">(</span><span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="nx">transaction</span><span class="p">.</span><span class="nx">connection</span> <span class="o">=</span> <span class="kc">null</span><span class="p">;</span>
<span class="p">});</span>
<span class="p">});</span>
<span class="p">}</span>
<span class="p">});</span>
<span class="nx">exports</span><span class="p">.</span><span class="nx">ServerBase</span> <span class="o">=</span> <span class="nx">ServerBase</span><span class="p">;</span></div></div></div></div></body></html>