yujunjun/knex
1
0
Fork 0
mirror of https://github.com/knex/knex.git synced 2025-08-03 06:12:10 +00:00
Code Issues Packages Projects Releases Wiki Activity
knex/docs/knex.html
Tim Griesser 53998e3dd0 Updating docs for 0.5.0
2013-11-25 12:31:42 -05:00

90 lines
21 KiB
HTML
Raw Blame History

<!DOCTYPE html><html lang="en"><head><title>knex</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="knex"><meta name="groc-project-path" content="knex.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">knex.js</div></div><div id="document"><div class="segment"><div class="comments"><div class="wrapper"><h2 id="knexjs-050">Knex.js 0.5.0</h2></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><pre><code>(c) 2013 Tim Griesser
Knex may be freely distributed under the MIT license.
For details and documentation:
http://knexjs.org
</code></pre></div></div><div class="code"><div class="wrapper"><span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">define</span><span class="p">)</span> <span class="p">{</span>
<span class="s2">&quot;use strict&quot;</span><span class="p">;</span>
<span class="nx">define</span><span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">require</span><span class="p">,</span> <span class="nx">exports</span><span class="p">,</span> <span class="nx">module</span><span class="p">)</span> <span class="p">{</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Base library dependencies of the app.</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></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Require the main constructors necessary for a <code>Knex</code> instance,
each of which are injected with the current instance, so they maintain
the correct client reference &amp; grammar.</p></div></div><div class="code"><div class="wrapper"> <span class="kd">var</span> <span class="nx">Raw</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;./lib/raw&#39;</span><span class="p">).</span><span class="nx">Raw</span><span class="p">;</span>
<span class="kd">var</span> <span class="nx">Transaction</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;./lib/transaction&#39;</span><span class="p">).</span><span class="nx">Transaction</span><span class="p">;</span>
<span class="kd">var</span> <span class="nx">Builder</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;./lib/builder&#39;</span><span class="p">).</span><span class="nx">Builder</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;./lib/promise&#39;</span><span class="p">).</span><span class="nx">Promise</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;./clients/base&#39;</span><span class="p">).</span><span class="nx">ClientBase</span><span class="p">;</span>
<span class="kd">var</span> <span class="nx">SchemaBuilder</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;./lib/schemabuilder&#39;</span><span class="p">).</span><span class="nx">SchemaBuilder</span><span class="p">;</span>
<span class="kd">var</span> <span class="nx">SchemaInterface</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;./lib/schemainterface&#39;</span><span class="p">).</span><span class="nx">SchemaInterface</span><span class="p">;</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>The <code>Knex</code> module, taking either a fully initialized
database client, or a configuration to initialize one. This is something
you'll typically only want to call once per application cycle.</p></div></div><div class="code"><div class="wrapper"> <span class="kd">var</span> <span class="nx">Knex</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="kd">var</span> <span class="nx">Dialect</span><span class="p">,</span> <span class="nx">client</span><span class="p">;</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>If the client isn't actually a client, we need to configure it into one.
On the client, this isn't acceptable, since we need to return immediately
rather than wait on an async load of a client library.</p></div></div><div class="code"><div class="wrapper"> <span class="k">if</span> <span class="p">(</span><span class="nx">config</span> <span class="k">instanceof</span> <span class="nx">ClientBase</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">client</span> <span class="o">=</span> <span class="nx">config</span><span class="p">;</span>
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="k">typeof</span> <span class="nx">define</span> <span class="o">===</span> <span class="s1">&#39;function&#39;</span> <span class="o">&amp;&amp;</span> <span class="nx">define</span><span class="p">.</span><span class="nx">amd</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;A valid `Knex` client must be passed into the Knex constructor.&#39;</span><span class="p">);</span>
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">clientName</span> <span class="o">=</span> <span class="nx">config</span><span class="p">.</span><span class="nx">client</span><span class="p">;</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">Clients</span><span class="p">[</span><span class="nx">clientName</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="nx">clientName</span> <span class="o">+</span> <span class="s1">&#39; is not a valid Knex client, did you misspell it?&#39;</span><span class="p">);</span>
<span class="p">}</span>
<span class="nx">Dialect</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="nx">Clients</span><span class="p">[</span><span class="nx">clientName</span><span class="p">]);</span>
<span class="nx">client</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Dialect</span><span class="p">.</span><span class="nx">Client</span><span class="p">(</span><span class="nx">_</span><span class="p">.</span><span class="nx">omit</span><span class="p">(</span><span class="nx">config</span><span class="p">,</span> <span class="s1">&#39;client&#39;</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>Enables the <code>knex('tableName')</code> shorthand syntax.</p></div></div><div class="code"><div class="wrapper"> <span class="kd">var</span> <span class="nx">knex</span> <span class="o">=</span> <span class="kd">function</span><span class="p">(</span><span class="nx">tableName</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="nx">knex</span><span class="p">.</span><span class="nx">builder</span><span class="p">(</span><span class="nx">tableName</span><span class="p">);</span>
<span class="p">};</span>
<span class="nx">knex</span><span class="p">.</span><span class="nx">grammar</span> <span class="o">=</span> <span class="nx">client</span><span class="p">.</span><span class="nx">grammar</span><span class="p">;</span>
<span class="nx">knex</span><span class="p">.</span><span class="nx">schemaGrammar</span> <span class="o">=</span> <span class="nx">client</span><span class="p">.</span><span class="nx">schemaGrammar</span><span class="p">;</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Main namespaces for key library components.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">knex</span><span class="p">.</span><span class="nx">schema</span> <span class="o">=</span> <span class="p">{};</span>
<span class="nx">knex</span><span class="p">.</span><span class="nx">migrate</span> <span class="o">=</span> <span class="p">{};</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Enable the <code>Builder('tableName')</code> syntax, as is used in the main <code>knex('tableName')</code>.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">knex</span><span class="p">.</span><span class="nx">builder</span> <span class="o">=</span> <span class="kd">function</span><span class="p">(</span><span class="nx">tableName</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="nx">Builder</span><span class="p">(</span><span class="nx">knex</span><span class="p">);</span>
<span class="k">return</span> <span class="nx">tableName</span> <span class="o">?</span> <span class="nx">builder</span><span class="p">.</span><span class="nx">from</span><span class="p">(</span><span class="nx">tableName</span><span class="p">)</span> <span class="o">:</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>Attach each of the <code>Schema</code> "interface" methods directly onto to <code>knex.schema</code> namespace, e.g.:
<code>knex.schema.table('tableName', function() {...</code>
<code>knex.schema.createTable('tableName', function() {...</code>
<code>knex.schema.dropTableIfExists('tableName');</code></p></div></div><div class="code"><div class="wrapper"> <span class="nx">_</span><span class="p">.</span><span class="nx">each</span><span class="p">(</span><span class="nx">SchemaInterface</span><span class="p">,</span> <span class="kd">function</span><span class="p">(</span><span class="nx">val</span><span class="p">,</span> <span class="nx">key</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">knex</span><span class="p">.</span><span class="nx">schema</span><span class="p">[</span><span class="nx">key</span><span class="p">]</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">schemaBuilder</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">SchemaBuilder</span><span class="p">(</span><span class="nx">knex</span><span class="p">);</span>
<span class="kd">var</span> <span class="nx">table</span> <span class="o">=</span> <span class="nx">schemaBuilder</span><span class="p">.</span><span class="nx">table</span> <span class="o">=</span> <span class="nx">_</span><span class="p">.</span><span class="nx">first</span><span class="p">(</span><span class="nx">arguments</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">table</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="nx">Promise</span><span class="p">.</span><span class="nx">reject</span><span class="p">(</span><span class="k">new</span> <span class="nb">Error</span><span class="p">(</span><span class="s1">&#39;The table must be defined for the &#39;</span> <span class="o">+</span> <span class="nx">key</span> <span class="o">+</span> <span class="s1">&#39; method.&#39;</span><span class="p">));</span>
<span class="p">}</span>
<span class="k">return</span> <span class="nx">SchemaInterface</span><span class="p">[</span><span class="nx">key</span><span class="p">].</span><span class="nx">apply</span><span class="p">(</span><span class="nx">schemaBuilder</span><span class="p">,</span> <span class="nx">_</span><span class="p">.</span><span class="nx">rest</span><span class="p">(</span><span class="nx">arguments</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>Method to run a new <code>Raw</code> query on the current client.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">knex</span><span class="p">.</span><span class="nx">raw</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="p">{</span>
<span class="k">return</span> <span class="k">new</span> <span class="nx">Raw</span><span class="p">(</span><span class="nx">knex</span><span class="p">).</span><span class="nx">query</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="p">};</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Keep a reference to the current client.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">knex</span><span class="p">.</span><span class="nx">client</span> <span class="o">=</span> <span class="nx">client</span><span class="p">;</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Keep in sync with package.json</p></div></div><div class="code"><div class="wrapper"> <span class="nx">knex</span><span class="p">.</span><span class="nx">VERSION</span> <span class="o">=</span> <span class="s1">&#39;0.5.0&#39;</span><span class="p">;</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Runs a new transaction, taking a container and returning a promise
for when the transaction is resolved.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">knex</span><span class="p">.</span><span class="nx">transaction</span> <span class="o">=</span> <span class="kd">function</span><span class="p">(</span><span class="nx">container</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="k">new</span> <span class="nx">Transaction</span><span class="p">(</span><span class="nx">knex</span><span class="p">).</span><span class="nx">run</span><span class="p">(</span><span class="nx">container</span><span class="p">);</span>
<span class="p">};</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Attach each of the <code>Migrate</code> "interface" methods directly onto to <code>knex.migrate</code> namespace, e.g.:
knex.migrate.latest().then(...
knex.migrate.currentVersion(...</p></div></div><div class="code"><div class="wrapper"> <span class="nx">_</span><span class="p">.</span><span class="nx">each</span><span class="p">([</span><span class="s1">&#39;make&#39;</span><span class="p">,</span> <span class="s1">&#39;latest&#39;</span><span class="p">,</span> <span class="s1">&#39;rollback&#39;</span><span class="p">,</span> <span class="s1">&#39;currentVersion&#39;</span><span class="p">],</span> <span class="kd">function</span><span class="p">(</span><span class="nx">method</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">knex</span><span class="p">.</span><span class="nx">migrate</span><span class="p">[</span><span class="nx">method</span><span class="p">]</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">Migrate</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;./lib/migrate&#39;</span><span class="p">);</span>
<span class="kd">var</span> <span class="nx">migration</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Migrate</span><span class="p">(</span><span class="nx">knex</span><span class="p">);</span>
<span class="k">return</span> <span class="nx">migration</span><span class="p">[</span><span class="nx">method</span><span class="p">].</span><span class="nx">apply</span><span class="p">(</span><span class="nx">migration</span><span class="p">,</span> <span class="nx">arguments</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>Return the new <code>Knex</code> instance.</p></div></div><div class="code"><div class="wrapper"> <span class="k">return</span> <span class="nx">knex</span><span class="p">;</span>
<span class="p">};</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>The client names we'll allow in the <code>{name: lib}</code> pairing.</p></div></div><div class="code"><div class="wrapper"> <span class="kd">var</span> <span class="nx">Clients</span> <span class="o">=</span> <span class="nx">Knex</span><span class="p">.</span><span class="nx">Clients</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">&#39;mysql&#39;</span> <span class="o">:</span> <span class="s1">&#39;./clients/server/mysql.js&#39;</span><span class="p">,</span>
<span class="s1">&#39;pg&#39;</span> <span class="o">:</span> <span class="s1">&#39;./clients/server/postgres.js&#39;</span><span class="p">,</span>
<span class="s1">&#39;postgres&#39;</span> <span class="o">:</span> <span class="s1">&#39;./clients/server/postgres.js&#39;</span><span class="p">,</span>
<span class="s1">&#39;postgresql&#39;</span> <span class="o">:</span> <span class="s1">&#39;./clients/server/postgres.js&#39;</span><span class="p">,</span>
<span class="s1">&#39;sqlite&#39;</span> <span class="o">:</span> <span class="s1">&#39;./clients/server/sqlite3.js&#39;</span><span class="p">,</span>
<span class="s1">&#39;sqlite3&#39;</span> <span class="o">:</span> <span class="s1">&#39;./clients/server/sqlite3.js&#39;</span>
<span class="p">};</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>Used primarily to type-check a potential <code>Knex</code> client in <code>Bookshelf.js</code>,
by examining whether the object's <code>client</code> is an <code>instanceof Knex.ClientBase</code>.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">Knex</span><span class="p">.</span><span class="nx">ClientBase</span> <span class="o">=</span> <span class="nx">ClientBase</span><span class="p">;</span></div></div></div><div class="segment"><div class="comments"><div class="wrapper"><p>finally, export the <code>Knex</code> object for node and the browser.</p></div></div><div class="code"><div class="wrapper"> <span class="nx">module</span><span class="p">.</span><span class="nx">exports</span> <span class="o">=</span> <span class="nx">Knex</span><span class="p">;</span>
<span class="nx">Knex</span><span class="p">.</span><span class="nx">initialize</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">return</span> <span class="nx">Knex</span><span class="p">(</span><span class="nx">config</span><span class="p">);</span>
<span class="p">};</span>
<span class="p">});</span>
<span class="p">})(</span>
<span class="k">typeof</span> <span class="nx">define</span> <span class="o">===</span> <span class="s1">&#39;function&#39;</span> <span class="o">&amp;&amp;</span> <span class="nx">define</span><span class="p">.</span><span class="nx">amd</span> <span class="o">?</span> <span class="nx">define</span> <span class="o">:</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">factory</span><span class="p">)</span> <span class="p">{</span> <span class="nx">factory</span><span class="p">(</span><span class="nx">require</span><span class="p">,</span> <span class="nx">exports</span><span class="p">,</span> <span class="nx">module</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