2013-03-12 11:52:08 -04:00
|
|
|
|
<!DOCTYPE HTML>
|
|
|
|
|
|
<html>
|
|
|
|
|
|
<head>
|
|
|
|
|
|
<meta http-equiv="content-type" content="text/html;charset=UTF-8" />
|
|
|
|
|
|
<meta http-equiv="X-UA-Compatible" content="chrome=1" />
|
|
|
|
|
|
<meta name="viewport" content="width=device-width">
|
|
|
|
|
|
<link rel="canonical" href="http://knexjs.org" />
|
|
|
|
|
|
<link rel="icon" href="docs/images/favicon.ico" />
|
|
|
|
|
|
<title>Knex.js</title>
|
|
|
|
|
|
<style>
|
|
|
|
|
|
body {
|
|
|
|
|
|
font-size: 14px;
|
|
|
|
|
|
line-height: 22px;
|
2013-05-04 19:13:07 -04:00
|
|
|
|
background: #f4f4f4;
|
|
|
|
|
|
color: #000;
|
2013-03-12 11:52:08 -04:00
|
|
|
|
font-family: Helvetica Neue, Helvetica, Arial;
|
|
|
|
|
|
}
|
|
|
|
|
|
.interface {
|
|
|
|
|
|
font-family: "Lucida Grande", "Lucida Sans Unicode", Helvetica, Arial, sans-serif !important;
|
|
|
|
|
|
}
|
|
|
|
|
|
div#sidebar {
|
|
|
|
|
|
background: #fff;
|
|
|
|
|
|
position: fixed;
|
|
|
|
|
|
top: 0; left: 0; bottom: 0;
|
|
|
|
|
|
width: 200px;
|
|
|
|
|
|
overflow-y: auto;
|
|
|
|
|
|
overflow-x: hidden;
|
|
|
|
|
|
-webkit-overflow-scrolling: touch;
|
|
|
|
|
|
padding: 15px 0 30px 30px;
|
|
|
|
|
|
border-right: 1px solid #bbb;
|
|
|
|
|
|
box-shadow: 0 0 20px #ccc; -webkit-box-shadow: 0 0 20px #ccc; -moz-box-shadow: 0 0 20px #ccc;
|
|
|
|
|
|
}
|
2013-05-04 19:13:07 -04:00
|
|
|
|
a.toc_title, a.toc_title:visited {
|
|
|
|
|
|
display: block;
|
|
|
|
|
|
color: black;
|
|
|
|
|
|
font-weight: bold;
|
|
|
|
|
|
margin-top: 15px;
|
|
|
|
|
|
}
|
|
|
|
|
|
a.toc_title:hover {
|
|
|
|
|
|
text-decoration: underline;
|
|
|
|
|
|
}
|
|
|
|
|
|
#sidebar .version {
|
|
|
|
|
|
font-size: 10px;
|
|
|
|
|
|
font-weight: normal;
|
|
|
|
|
|
}
|
|
|
|
|
|
ul.toc_section {
|
|
|
|
|
|
font-size: 11px;
|
|
|
|
|
|
line-height: 14px;
|
|
|
|
|
|
margin: 5px 0 0 0;
|
|
|
|
|
|
padding-left: 0px;
|
|
|
|
|
|
list-style-type: none;
|
|
|
|
|
|
font-family: Lucida Grande;
|
|
|
|
|
|
}
|
|
|
|
|
|
.toc_section li {
|
|
|
|
|
|
cursor: pointer;
|
|
|
|
|
|
margin: 0 0 3px 0;
|
|
|
|
|
|
}
|
|
|
|
|
|
.toc_section li a {
|
|
|
|
|
|
text-decoration: none;
|
|
|
|
|
|
color: black;
|
2013-03-12 11:52:08 -04:00
|
|
|
|
}
|
2013-05-04 19:13:07 -04:00
|
|
|
|
.toc_section li a:hover {
|
|
|
|
|
|
text-decoration: underline;
|
2013-03-12 11:52:08 -04:00
|
|
|
|
}
|
|
|
|
|
|
div.container {
|
|
|
|
|
|
width: 550px;
|
|
|
|
|
|
margin: 40px 0 50px 260px;
|
|
|
|
|
|
}
|
2013-05-13 10:38:28 -04:00
|
|
|
|
div.container ul.small {
|
|
|
|
|
|
font-size: 12px;
|
|
|
|
|
|
}
|
2013-03-12 11:52:08 -04:00
|
|
|
|
img#logo {
|
2013-05-12 20:55:02 -04:00
|
|
|
|
width: 450px;
|
2013-03-12 11:52:08 -04:00
|
|
|
|
}
|
2013-05-04 19:13:07 -04:00
|
|
|
|
div.warning {
|
|
|
|
|
|
margin-top: 15px;
|
|
|
|
|
|
font: bold 11px Arial;
|
|
|
|
|
|
color: #770000;
|
2013-03-12 11:52:08 -04:00
|
|
|
|
}
|
2013-05-04 19:13:07 -04:00
|
|
|
|
p {
|
|
|
|
|
|
margin: 20px 0;
|
2013-03-12 11:52:08 -04:00
|
|
|
|
width: 550px;
|
|
|
|
|
|
}
|
|
|
|
|
|
a, a:visited {
|
|
|
|
|
|
color: #444;
|
|
|
|
|
|
}
|
|
|
|
|
|
a:active, a:hover {
|
|
|
|
|
|
color: #000;
|
|
|
|
|
|
}
|
|
|
|
|
|
h1, h2, h3, h4, h5, h6 {
|
|
|
|
|
|
padding-top: 20px;
|
|
|
|
|
|
}
|
|
|
|
|
|
h2 {
|
2013-05-04 19:13:07 -04:00
|
|
|
|
font-size: 20px;
|
2013-03-12 11:52:08 -04:00
|
|
|
|
}
|
|
|
|
|
|
b.header {
|
2013-05-04 19:13:07 -04:00
|
|
|
|
font-size: 16px;
|
|
|
|
|
|
line-height: 30px;
|
2013-03-12 11:52:08 -04:00
|
|
|
|
}
|
2013-08-07 13:20:25 -04:00
|
|
|
|
span.small {
|
|
|
|
|
|
font-size: 12px;
|
|
|
|
|
|
font-style: italic;
|
|
|
|
|
|
}
|
2013-03-12 11:52:08 -04:00
|
|
|
|
span.alias {
|
|
|
|
|
|
font-size: 14px;
|
|
|
|
|
|
font-style: italic;
|
|
|
|
|
|
margin-left: 20px;
|
|
|
|
|
|
}
|
2013-05-04 19:13:07 -04:00
|
|
|
|
table, tr, td {
|
|
|
|
|
|
margin: 0; padding: 0;
|
2013-03-12 11:52:08 -04:00
|
|
|
|
}
|
2013-05-04 19:13:07 -04:00
|
|
|
|
td {
|
|
|
|
|
|
padding: 2px 12px 2px 0;
|
2013-03-12 11:52:08 -04:00
|
|
|
|
}
|
2013-05-04 19:13:07 -04:00
|
|
|
|
table .rule {
|
|
|
|
|
|
height: 1px;
|
|
|
|
|
|
background: #ccc;
|
|
|
|
|
|
margin: 5px 0;
|
2013-03-12 11:52:08 -04:00
|
|
|
|
}
|
2013-05-04 19:13:07 -04:00
|
|
|
|
ul {
|
|
|
|
|
|
list-style-type: circle;
|
|
|
|
|
|
padding: 0 0 0 20px;
|
|
|
|
|
|
}
|
|
|
|
|
|
li {
|
|
|
|
|
|
width: 500px;
|
|
|
|
|
|
margin-bottom: 10px;
|
2013-03-12 11:52:08 -04:00
|
|
|
|
}
|
2013-05-04 19:13:07 -04:00
|
|
|
|
code, pre, tt {
|
|
|
|
|
|
font-family: Monaco, Consolas, "Lucida Console", monospace;
|
2013-03-12 11:52:08 -04:00
|
|
|
|
font-size: 12px;
|
2013-05-04 19:13:07 -04:00
|
|
|
|
line-height: 18px;
|
|
|
|
|
|
font-style: normal;
|
2013-03-12 11:52:08 -04:00
|
|
|
|
}
|
2013-05-04 19:13:07 -04:00
|
|
|
|
tt {
|
|
|
|
|
|
padding: 0px 3px;
|
|
|
|
|
|
background: #fff;
|
|
|
|
|
|
border: 1px solid #ddd;
|
|
|
|
|
|
zoom: 1;
|
2013-03-12 11:52:08 -04:00
|
|
|
|
}
|
2013-05-04 19:13:07 -04:00
|
|
|
|
code {
|
|
|
|
|
|
margin-left: 20px;
|
|
|
|
|
|
}
|
|
|
|
|
|
pre {
|
|
|
|
|
|
font-size: 12px;
|
|
|
|
|
|
padding: 2px 0 2px 15px;
|
|
|
|
|
|
border-left: 5px solid #bbb;
|
|
|
|
|
|
margin: 0px 0 30px;
|
2013-03-12 11:52:08 -04:00
|
|
|
|
}
|
|
|
|
|
|
@media only screen and (-webkit-min-device-pixel-ratio: 1.5) and (max-width: 640px),
|
|
|
|
|
|
only screen and (-o-min-device-pixel-ratio: 3/2) and (max-width: 640px),
|
|
|
|
|
|
only screen and (min-device-pixel-ratio: 1.5) and (max-width: 640px) {
|
|
|
|
|
|
img {
|
|
|
|
|
|
max-width: 100%;
|
|
|
|
|
|
}
|
|
|
|
|
|
div#sidebar {
|
|
|
|
|
|
-webkit-overflow-scrolling: initial;
|
|
|
|
|
|
position: relative;
|
|
|
|
|
|
width: 90%;
|
|
|
|
|
|
height: 120px;
|
|
|
|
|
|
left: 0;
|
|
|
|
|
|
top: -7px;
|
|
|
|
|
|
padding: 10px 0 10px 30px;
|
|
|
|
|
|
border: 0;
|
|
|
|
|
|
}
|
|
|
|
|
|
img#logo {
|
|
|
|
|
|
width: auto;
|
|
|
|
|
|
height: auto;
|
|
|
|
|
|
}
|
|
|
|
|
|
div.container {
|
|
|
|
|
|
margin: 0;
|
|
|
|
|
|
width: 100%;
|
|
|
|
|
|
}
|
|
|
|
|
|
p, div.container ul {
|
|
|
|
|
|
max-width: 98%;
|
|
|
|
|
|
overflow-x: scroll;
|
|
|
|
|
|
}
|
|
|
|
|
|
pre {
|
|
|
|
|
|
overflow: scroll;
|
|
|
|
|
|
}
|
|
|
|
|
|
}
|
|
|
|
|
|
</style>
|
|
|
|
|
|
</head>
|
|
|
|
|
|
<body>
|
|
|
|
|
|
|
|
|
|
|
|
<div id="sidebar" class="interface">
|
|
|
|
|
|
|
2013-04-01 23:04:02 -04:00
|
|
|
|
<a class="toc_title" href="#">
|
2013-08-22 21:42:18 -04:00
|
|
|
|
Knex.js <span class="version">(0.2.4)</span>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</a>
|
|
|
|
|
|
<ul class="toc_section">
|
2013-03-12 12:23:45 -04:00
|
|
|
|
<li>» <a href="https://github.com/tgriesser/knex">GitHub Repository</a></li>
|
2013-03-12 12:48:58 -04:00
|
|
|
|
<li>» <a href="http://knexjs.org/docs/knex.html">Annotated Source</a></li>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
<a class="toc_title" href="#installation">
|
|
|
|
|
|
Installation
|
|
|
|
|
|
</a>
|
|
|
|
|
|
|
|
|
|
|
|
<a class="toc_title" href="#Initialize">
|
|
|
|
|
|
Initialize
|
|
|
|
|
|
</a>
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<ul class="toc_section">
|
|
|
|
|
|
<li>– <a href="#Init-multi-instance">multi-instance</a></li>
|
|
|
|
|
|
</ul>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
|
|
|
|
|
|
<a class="toc_title" href="#Builder">
|
|
|
|
|
|
Builder
|
|
|
|
|
|
</a>
|
|
|
|
|
|
<ul class="toc_section">
|
|
|
|
|
|
<li>– <a href="#Builder-main"><b>constructor</b></a></li>
|
2013-05-04 20:36:02 -04:00
|
|
|
|
<li>– <a href="#Builder-select">select</a></li>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<li>– <a href="#Builder-from">from</a></li>
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<li>– <a href="#Builder-where">where <b>+18 methods</b></a></li>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<li>– <a href="#Builder-distinct">distinct</a></li>
|
|
|
|
|
|
<li>– <a href="#Builder-join">join</a></li>
|
|
|
|
|
|
<li>– <a href="#Builder-groupBy">groupBy</a></li>
|
|
|
|
|
|
<li>– <a href="#Builder-orderBy">orderBy</a></li>
|
|
|
|
|
|
<li>– <a href="#Builder-having">having</a></li>
|
|
|
|
|
|
<li>– <a href="#Builder-offset">offset</a></li>
|
|
|
|
|
|
<li>– <a href="#Builder-limit">limit</a></li>
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<li>– <a href="#Builder-union">union</a></li>
|
|
|
|
|
|
<li>– <a href="#Builder-unionAll">unionAll</a></li>
|
|
|
|
|
|
<li>– <a href="#Builder-insert">insert</a></li>
|
2013-07-17 13:52:58 -04:00
|
|
|
|
<li>– <a href="#Builder-returning">returning</a></li>
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<li>– <a href="#Builder-update">update</a></li>
|
|
|
|
|
|
<li>– <a href="#Builder-del">del / delete</a></li>
|
2013-07-17 13:52:58 -04:00
|
|
|
|
<li>– <a href="#Builder-transacting">transacting</a></li>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<li>– <a href="#Builder-count">count</a></li>
|
|
|
|
|
|
<li>– <a href="#Builder-min">min</a></li>
|
|
|
|
|
|
<li>– <a href="#Builder-max">max</a></li>
|
|
|
|
|
|
<li>– <a href="#Builder-sum">sum</a></li>
|
|
|
|
|
|
<li>– <a href="#Builder-increment">increment</a></li>
|
|
|
|
|
|
<li>– <a href="#Builder-decrement">decrement</a></li>
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<li>– <a href="#Builder-truncate">truncate</a></li>
|
2013-05-10 14:12:28 -04:00
|
|
|
|
<li>– <a href="#Builder-debug">debug</a></li>
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<li><b><a href="#Builder-Interface">Interface:</a></b></li>
|
2013-05-08 20:16:39 -04:00
|
|
|
|
<li>– <a href="#Builder-then">then</a></li>
|
|
|
|
|
|
<li>– <a href="#Builder-exec">exec</a></li>
|
2013-08-22 21:34:31 -04:00
|
|
|
|
<li>– <a href="#Builder-toString">toString</a></li>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
<a class="toc_title" href="#Transaction">
|
|
|
|
|
|
Transaction
|
|
|
|
|
|
</a>
|
|
|
|
|
|
|
|
|
|
|
|
<a class="toc_title" href="#Schema">
|
|
|
|
|
|
Schema
|
|
|
|
|
|
</a>
|
|
|
|
|
|
<ul class="toc_section">
|
2013-03-12 12:23:45 -04:00
|
|
|
|
<li>– <a href="#Schema-createTable">createTable</a></li>
|
2013-05-08 20:16:39 -04:00
|
|
|
|
<li>– <a href="#Schema-renameTable">renameTable</a></li>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<li>– <a href="#Schema-dropTable">dropTable</a></li>
|
2013-05-08 20:16:39 -04:00
|
|
|
|
<li>– <a href="#Schema-hasTable">hasTable</a></li>
|
2013-03-12 12:23:45 -04:00
|
|
|
|
<li>– <a href="#Schema-dropTableIfExists">dropTableIfExists</a></li>
|
|
|
|
|
|
<li>– <a href="#Schema-table">table</a></li>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<li><b><a href="#Schema-Building">Schema Building:</a></b></li>
|
|
|
|
|
|
<li>– <a href="#Schema-dropColumn">dropColumn</a></li>
|
|
|
|
|
|
<li>– <a href="#Schema-dropColumns">dropColumns</a></li>
|
|
|
|
|
|
<li>– <a href="#Schema-increments">increments</a></li>
|
2013-03-12 12:23:45 -04:00
|
|
|
|
<li>– <a href="#Schema-integer">integer</a></li>
|
|
|
|
|
|
<li>– <a href="#Schema-text">text</a></li>
|
|
|
|
|
|
<li>– <a href="#Schema-string">string</a></li>
|
|
|
|
|
|
<li>– <a href="#Schema-float">float</a></li>
|
|
|
|
|
|
<li>– <a href="#Schema-decimal">decimal</a></li>
|
|
|
|
|
|
<li>– <a href="#Schema-boolean">boolean</a></li>
|
|
|
|
|
|
<li>– <a href="#Schema-date">date</a></li>
|
|
|
|
|
|
<li>– <a href="#Schema-dateTime">dateTime</a></li>
|
|
|
|
|
|
<li>– <a href="#Schema-time">time</a></li>
|
|
|
|
|
|
<li>– <a href="#Schema-timestamp">timestamp</a></li>
|
|
|
|
|
|
<li>– <a href="#Schema-binary">binary</a></li>
|
|
|
|
|
|
<li>– <a href="#Schema-enum">enum / enu</a></li>
|
2013-06-16 22:31:29 +10:00
|
|
|
|
<li>– <a href="#Schema-json">json</a></li>
|
2013-07-17 10:26:24 -04:00
|
|
|
|
<li>– <a href="#Schema-uuid">uuid</a></li>
|
2013-06-16 20:49:04 +10:00
|
|
|
|
<li>– <a href="#Schema-comment">comment</a></li>
|
2013-05-04 21:37:10 -04:00
|
|
|
|
<li><a href="#Chainable"><b>Chainable:</b></li>
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<li>– <a href="#Chainable-index">index</a></li>
|
|
|
|
|
|
<li>– <a href="#Chainable-primary">primary</a></li>
|
|
|
|
|
|
<li>– <a href="#Chainable-unique">unique</a></li>
|
2013-05-04 21:37:10 -04:00
|
|
|
|
<li>– <a href="#Chainable-defaultTo">defaultTo</a></li>
|
|
|
|
|
|
<li>– <a href="#Chainable-unsigned">unsigned</a></li>
|
|
|
|
|
|
<li>– <a href="#Chainable-nullable">nullable</a></li>
|
2013-05-15 19:25:51 -04:00
|
|
|
|
<li>– <a href="#Chainable-after">after</a></li>
|
2013-06-16 20:49:04 +10:00
|
|
|
|
<li>– <a href="#Chainable-comment">comment</a></li>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</ul>
|
|
|
|
|
|
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<a class="toc_title" href="#Raw">
|
|
|
|
|
|
Raw
|
|
|
|
|
|
</a>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
|
|
|
|
|
|
<a class="toc_title" href="#faq">
|
|
|
|
|
|
F.A.Q.
|
|
|
|
|
|
</a>
|
|
|
|
|
|
|
|
|
|
|
|
<a class="toc_title" href="#changelog">
|
|
|
|
|
|
Change Log
|
|
|
|
|
|
</a>
|
|
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
<div class="container">
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
2013-05-12 20:55:02 -04:00
|
|
|
|
<img id="logo" src="docs/images/knex.png" alt="Knex.js">
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
2013-08-22 16:04:20 -04:00
|
|
|
|
Knex.js is a query builder for <b>Postgres</b>, <b>MySQL</b> and <b>SQLite3</b>, designed to be flexible,
|
2013-05-22 13:14:51 -04:00
|
|
|
|
portable, and fun to use. It features both traditional node style <a href="#Builder-exec">callbacks</a>
|
|
|
|
|
|
as well as a <a href="#Builder-then">promise</a> interface for cleaner async flow control, full featured
|
|
|
|
|
|
query and schema builders, transaction support, connection pooling and node.js adapters for
|
2013-05-13 10:38:28 -04:00
|
|
|
|
postgres, mysql, and sqlite3 - standardizing responses between the three.
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
The project is <a href="http://github.com/tgriesser/knex">hosted on GitHub</a>,
|
|
|
|
|
|
and the <a href="docs/knex.html">annotated source code</a> is available,
|
2013-05-04 21:37:10 -04:00
|
|
|
|
and has a comprehensive <a href="https://travis-ci.org/tgriesser/knex">test suite</a>.
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
Knex is available for use under the <a href="http://github.com/tgriesser/knex/blob/master/LICENSE">MIT software license</a>.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
You can report bugs and discuss features on the
|
|
|
|
|
|
<a href="http://github.com/tgriesser/knex/issues">GitHub issues page</a>,
|
|
|
|
|
|
add pages to the <a href="https://github.com/tgriesser/knex/wiki">wiki</a>
|
|
|
|
|
|
or send tweets to <a href="http://twitter.com/tgriesser">@tgriesser</a>.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-08-07 12:24:36 -04:00
|
|
|
|
<p>
|
|
|
|
|
|
Big thanks to all of the great <a href="https://github.com/tgriesser/knex/graphs/contributors">contributions</a> to the project.
|
|
|
|
|
|
</a>
|
|
|
|
|
|
|
2013-08-22 21:42:18 -04:00
|
|
|
|
<h2>Latest Release: 0.2.4 - <span class="small"><a href="#changelog">Change Log</a></span></h2>
|
2013-05-13 10:38:28 -04:00
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
Current Develop —
|
|
|
|
|
|
<a href="https://travis-ci.org/tgriesser/knex">
|
|
|
|
|
|
<img src="https://travis-ci.org/tgriesser/knex.png?branch=master" alt="Travis Badge">
|
|
|
|
|
|
</a>
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<p>
|
2013-05-22 13:14:51 -04:00
|
|
|
|
Special thanks to <a href="https://twitter.com/taylorotwell">Taylor Otwell</a> and his work
|
2013-06-18 10:04:59 -04:00
|
|
|
|
on the <a href="http://laravel.com/docs/queries">Laravel Query Builder</a>,
|
2013-05-04 20:06:39 -04:00
|
|
|
|
from which much of the code and syntax is derived.
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<h2 id="installation">
|
|
|
|
|
|
Installation
|
|
|
|
|
|
</h2>
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
2013-05-04 20:06:39 -04:00
|
|
|
|
All dependencies are specified in <tt>package.json</tt> file but include <tt>underscore.js</tt>,
|
2013-05-22 13:14:51 -04:00
|
|
|
|
<tt>when.js</tt>, and the <tt>generic-pool</tt> library. You then need to install
|
|
|
|
|
|
either <tt>mysql</tt>, <tt>pg</tt>, or <tt>sqlite3</tt> from <tt>npm</tt> if you wish
|
|
|
|
|
|
to use one of these databases with node.js, or create your own client
|
2013-03-12 11:52:08 -04:00
|
|
|
|
adapter and specify it in <a href="#Initialize">Knex.Initialize</a>.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<pre>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
$ npm install knex
|
|
|
|
|
|
|
|
|
|
|
|
# Then add one of the following:
|
|
|
|
|
|
$ npm install mysql
|
|
|
|
|
|
$ npm install pg
|
|
|
|
|
|
$ npm install sqlite3
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
|
|
<h2 id="Initialize">Knex.Initialize</h2>
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
2013-05-05 18:29:28 -04:00
|
|
|
|
<tt>Knex.Initialize</tt> is the initializing function that must be called prior to using
|
2013-05-22 13:14:51 -04:00
|
|
|
|
Knex, accepting a few parameters. The <tt>client</tt> parameter is required
|
2013-05-05 18:29:28 -04:00
|
|
|
|
and determines which client adapter will be used with the library.
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<pre>
|
2013-03-12 12:58:33 -04:00
|
|
|
|
Knex.Initialize({
|
2013-03-12 11:52:08 -04:00
|
|
|
|
client: 'mysql',
|
|
|
|
|
|
connection: {
|
|
|
|
|
|
host : '127.0.0.1',
|
2013-05-14 17:31:54 -04:00
|
|
|
|
user : 'your_database_user',
|
|
|
|
|
|
password : 'your_database_password',
|
2013-03-12 11:52:08 -04:00
|
|
|
|
database : 'myapp_test',
|
|
|
|
|
|
charset : 'utf8'
|
2013-03-12 12:40:53 -04:00
|
|
|
|
}
|
|
|
|
|
|
});
|
2013-05-05 18:29:28 -04:00
|
|
|
|
</pre>
|
2013-03-12 12:40:53 -04:00
|
|
|
|
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<p id="Init-multi-instance">
|
2013-05-22 13:14:51 -04:00
|
|
|
|
It is also possible to use Knex with multiple database connection instances if you'd like,
|
|
|
|
|
|
by creating named instances. To do this, pass the name of the connection as the first
|
2013-05-08 20:16:39 -04:00
|
|
|
|
parameter into <tt>Knex.Initialize</tt> and it will return that instance, which may
|
2013-05-05 18:29:28 -04:00
|
|
|
|
also be referenced by name under <tt>Knex.Instances</tt>.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
|
var SqliteDB = Knex.Initialize('sqlitedb', {
|
2013-03-12 12:40:53 -04:00
|
|
|
|
client: 'sqlite',
|
|
|
|
|
|
connection: {
|
|
|
|
|
|
database : './testdb'
|
2013-03-12 11:52:08 -04:00
|
|
|
|
}
|
|
|
|
|
|
});
|
2013-05-05 18:29:28 -04:00
|
|
|
|
|
2013-08-22 16:04:20 -04:00
|
|
|
|
var MySQL2 = Knex.Initialize('mysql2', {
|
2013-05-05 18:29:28 -04:00
|
|
|
|
client: 'mysql',
|
|
|
|
|
|
connection: { ... }
|
|
|
|
|
|
});
|
|
|
|
|
|
|
2013-08-22 16:04:20 -04:00
|
|
|
|
// Knex.Instances['mysql2'] === MySQL2;
|
2013-05-05 18:29:28 -04:00
|
|
|
|
// Knex.Instances['sqlitedb'] === SqliteDB;
|
|
|
|
|
|
|
2013-08-22 16:04:20 -04:00
|
|
|
|
MySQL2('accounts')
|
2013-05-05 18:29:28 -04:00
|
|
|
|
.select()
|
|
|
|
|
|
.then(function(resp) {
|
|
|
|
|
|
// ...
|
|
|
|
|
|
});
|
|
|
|
|
|
|
|
|
|
|
|
SqliteDB('users')
|
|
|
|
|
|
.insert({email: 'test@email.com'})
|
|
|
|
|
|
.exec(function(err, resp) {
|
|
|
|
|
|
// ...
|
|
|
|
|
|
});
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
|
|
<h2 id="Builder">Knex.Builder</h2>
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
The <tt>Knex.Builder</tt> is the interface used for building and executing standard SQL queries,
|
|
|
|
|
|
such as <tt>select</tt>, <tt>insert</tt>, <tt>update</tt>, <tt>delete</tt>. The query is run
|
2013-05-22 13:14:51 -04:00
|
|
|
|
by specifying a <a href="#Builder-table">tableName</a>, adding additional query parameters, and
|
2013-05-08 20:16:39 -04:00
|
|
|
|
executing the query with one of the public interface methods.
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-main">
|
2013-05-04 20:36:02 -04:00
|
|
|
|
<b class="header">Knex</b><code>Knex(tableName)...</code>
|
|
|
|
|
|
<br />
|
2013-05-05 18:29:28 -04:00
|
|
|
|
The <b>Knex</b> query builder starts off by specifying a <b>tableName</b> you wish to query against,
|
2013-05-22 13:14:51 -04:00
|
|
|
|
which returns a chainable interface, similar to a jQuery chain. You can then call any additional
|
|
|
|
|
|
query builder methods needed to construct the query, eventually calling either
|
2013-05-04 20:36:02 -04:00
|
|
|
|
<a href="#Builder-then">then</a> or <a href="#Builder-exec">exec</a>, to execute the query with a
|
|
|
|
|
|
promise or a callback, respectively.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-select">
|
|
|
|
|
|
<b class="header">select</b><code>.select([*columns])</code>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<br />
|
2013-05-04 20:36:02 -04:00
|
|
|
|
Creates a <tt>select</tt> query, taking an optional array of <b>columns</b> for the query, eventually
|
|
|
|
|
|
defaulting to <tt>*</tt> if none are specified when the query is built. The response of a select call will
|
2013-05-22 13:14:51 -04:00
|
|
|
|
return with the
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-05-04 20:36:02 -04:00
|
|
|
|
<pre>
|
2013-05-08 20:16:39 -04:00
|
|
|
|
// select "title", "author", "year" from "books"
|
2013-05-05 18:29:28 -04:00
|
|
|
|
Knex('books').select('title', 'author', 'year');
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-05-08 20:16:39 -04:00
|
|
|
|
// select * from "books"
|
2013-05-05 18:29:28 -04:00
|
|
|
|
Knex('books').select();
|
2013-05-04 20:36:02 -04:00
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<p id="Builder-from">
|
|
|
|
|
|
<b class="header">from</b><code>.from([tableName])</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Specifies the table used in the current query, replacing the current table name if
|
2013-05-05 18:29:28 -04:00
|
|
|
|
one has already been specified. This is typically used in the sub-queries performed
|
2013-05-13 10:38:28 -04:00
|
|
|
|
in the advanced <a href="#Builder-where">where</a> or <a href="#Builder-union">union</a> methods.
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-where">
|
2013-05-04 20:36:02 -04:00
|
|
|
|
<b class="header">where</b><code>.where(~dynamic~)</code>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<br />
|
2013-05-14 17:31:54 -04:00
|
|
|
|
There are several helpers for creating dynamic <tt>where</tt> clauses on queries. Take a look at a few
|
|
|
|
|
|
examples to see how these may be mixed and matched to create fluent constraints on the query.
|
|
|
|
|
|
</p>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
|
|
|
|
|
|
<pre>
|
2013-05-14 17:31:54 -04:00
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
// Basic Uses:
|
|
|
|
|
|
|
2013-05-14 17:31:54 -04:00
|
|
|
|
// objects
|
|
|
|
|
|
Knex('users').where({
|
2013-05-22 13:14:51 -04:00
|
|
|
|
first_name: 'Test',
|
2013-05-14 17:31:54 -04:00
|
|
|
|
last_name: 'User'
|
|
|
|
|
|
}).select('id').then(...
|
|
|
|
|
|
|
|
|
|
|
|
// key, value
|
|
|
|
|
|
Knex('users').where('id', 1).select('first_name', 'last_name').then(...
|
|
|
|
|
|
|
|
|
|
|
|
// operators: '=', '<', '>', '<=', '>=', 'like', 'not like', 'between', 'ilike'
|
2013-05-13 10:38:28 -04:00
|
|
|
|
Knex('users').where('votes', '>', 100).exec(function(err, resp) { ... });
|
|
|
|
|
|
|
2013-05-14 17:31:54 -04:00
|
|
|
|
// chained with "andWhere" / "orWhere"
|
2013-05-13 10:38:28 -04:00
|
|
|
|
Knex('users').where('votes', '>', 100)
|
2013-05-14 17:31:54 -04:00
|
|
|
|
.andWhere('status', 'active')
|
2013-05-13 10:38:28 -04:00
|
|
|
|
.orWhere('name', 'John')
|
|
|
|
|
|
.then(function(resp) { ... })
|
|
|
|
|
|
|
2013-05-14 17:31:54 -04:00
|
|
|
|
// Even more where types (see list below):
|
|
|
|
|
|
|
2013-05-13 10:38:28 -04:00
|
|
|
|
Knex('users').whereBetween('votes', [1, 100]).exec(...
|
2013-03-12 11:52:08 -04:00
|
|
|
|
|
2013-05-13 10:38:28 -04:00
|
|
|
|
Knex('users').whereIn('id', [1, 2, 3]).then(...
|
2013-03-12 11:52:08 -04:00
|
|
|
|
|
2013-05-13 10:38:28 -04:00
|
|
|
|
Knex('users').whereNotIn('id', [1, 2, 3]).then(...
|
|
|
|
|
|
|
|
|
|
|
|
Knex('users').whereNull('updated_at').exec(...
|
2013-05-04 21:37:10 -04:00
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</pre>
|
|
|
|
|
|
|
2013-05-14 17:31:54 -04:00
|
|
|
|
<p>
|
|
|
|
|
|
<b>Grouped Where Clauses:</b>
|
|
|
|
|
|
</p>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<pre>
|
|
|
|
|
|
// select * from users where name = 'John' or (votes > 100 and title <> 'Admin')
|
|
|
|
|
|
Knex('users')
|
|
|
|
|
|
.where('name', '=', 'John')
|
|
|
|
|
|
.orWhere(function() {
|
|
|
|
|
|
this.where('votes', '>', 100).andWhere('title', '<>', 'Admin');
|
|
|
|
|
|
})
|
|
|
|
|
|
.then(function() {...
|
|
|
|
|
|
</pre>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<p>
|
|
|
|
|
|
<b>Exists Statements:</b>
|
|
|
|
|
|
</p>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<pre>
|
|
|
|
|
|
Knex('users')
|
|
|
|
|
|
.whereExists(function() {
|
|
|
|
|
|
this.select(Knex.raw(1))
|
|
|
|
|
|
.from('orders')
|
|
|
|
|
|
.whereRaw('orders.user_id = users.id');
|
|
|
|
|
|
})
|
|
|
|
|
|
.then(...
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
2013-05-14 17:31:54 -04:00
|
|
|
|
<p>
|
|
|
|
|
|
Most of the where clauses may also accept a function as the second argument, to generate a sub-select
|
|
|
|
|
|
on the query:
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
|
|
|
|
|
|
|
// select author_id, content from comments where author_id in (select id from accounts where type = 'admin')
|
|
|
|
|
|
Knex('comments').whereIn('author_id', function() {
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-05-14 17:31:54 -04:00
|
|
|
|
this.select('id').from('accounts').where('type', 'admin');
|
|
|
|
|
|
|
|
|
|
|
|
}).select('author_id', 'content').then(...
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
These different where clauses may be joined together in any number of ways to make valid SQL statements.
|
|
|
|
|
|
</p>
|
2013-05-13 10:38:28 -04:00
|
|
|
|
|
|
|
|
|
|
<ul class="small">
|
2013-08-07 12:24:36 -04:00
|
|
|
|
<li><a href="docs/knex.html#section-56">where</a></li>
|
|
|
|
|
|
<li><a href="docs/knex.html#section-57">andWhere</a></li>
|
|
|
|
|
|
<li><a href="docs/knex.html#section-58">orWhere</a></li>
|
|
|
|
|
|
<li><a href="docs/knex.html#section-59">whereRaw</a></li>
|
|
|
|
|
|
<li><a href="docs/knex.html#section-60">orWhereRaw</a></li>
|
|
|
|
|
|
<li><a href="docs/knex.html#section-61">whereExists</a></li>
|
|
|
|
|
|
<li><a href="docs/knex.html#section-62">orWhereExists</a></li>
|
|
|
|
|
|
<li><a href="docs/knex.html#section-63">whereNotExists</a></li>
|
|
|
|
|
|
<li><a href="docs/knex.html#section-64">orWhereNotExists</a></li>
|
|
|
|
|
|
<li><a href="docs/knex.html#section-65">whereIn</a></li>
|
|
|
|
|
|
<li><a href="docs/knex.html#section-66">orWhereIn</a></li>
|
|
|
|
|
|
<li><a href="docs/knex.html#section-67">whereNotIn</a></li>
|
|
|
|
|
|
<li><a href="docs/knex.html#section-68">orWhereNotIn</a></li>
|
|
|
|
|
|
<li><a href="docs/knex.html#section-69">whereNull</a></li>
|
|
|
|
|
|
<li><a href="docs/knex.html#section-70">orWhereNull</a></li>
|
|
|
|
|
|
<li><a href="docs/knex.html#section-71">whereNotNull</a></li>
|
|
|
|
|
|
<li><a href="docs/knex.html#section-72">orWhereNotNull</a></li>
|
|
|
|
|
|
<li><a href="docs/knex.html#section-73">whereBetween</a></li>
|
|
|
|
|
|
<li><a href="docs/knex.html#section-74">orWhereBetween</a></li>
|
2013-05-13 10:38:28 -04:00
|
|
|
|
</ul>
|
|
|
|
|
|
</p>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
|
|
|
|
|
|
<p id="Builder-distinct">
|
|
|
|
|
|
<b class="header">distinct</b><code>.distinct()</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Sets a <tt>distinct</tt> clause on the query.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<pre>
|
2013-05-05 18:29:28 -04:00
|
|
|
|
// select distinct 'first_name' from customers
|
2013-03-12 11:52:08 -04:00
|
|
|
|
Knex('customers')
|
2013-05-05 18:29:28 -04:00
|
|
|
|
.distinct('first_name', 'last_name')
|
|
|
|
|
|
.select()
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-join">
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<b class="header">join</b><code>.join(table, first, operator, second, [type])</code>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<br />
|
2013-05-13 10:38:28 -04:00
|
|
|
|
The <tt>join</tt> builder can be used to specify joins between tables,
|
|
|
|
|
|
with the first argument being the joining <b>table</b>, the next three arguments
|
|
|
|
|
|
being the <b>first</b> join column, the join <b>operator</b> and the <b>second</b>
|
|
|
|
|
|
join column, respectively. The last argument is optional and spefies the type of join.
|
|
|
|
|
|
</p>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
|
|
|
|
|
|
<pre>
|
2013-05-13 10:38:28 -04:00
|
|
|
|
Knex('users')
|
|
|
|
|
|
.join('contacts', 'users.id', '=', 'contacts.user_id')
|
|
|
|
|
|
.join('orders', 'users.id', '=', 'orders.user_id', 'outer')
|
|
|
|
|
|
.select('users.id', 'contacts.phone', 'orders.price')
|
|
|
|
|
|
.then(function() { ... });
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</pre>
|
|
|
|
|
|
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<p>
|
|
|
|
|
|
For grouped joins, specify a function as the second argument for the
|
|
|
|
|
|
join query, and use <tt>on</tt> and <tt>orOn</tt> to create joins that are
|
|
|
|
|
|
grouped with parentheses.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<pre>
|
2013-05-13 10:38:28 -04:00
|
|
|
|
Knex('users')
|
|
|
|
|
|
.join('contacts', function() {
|
|
|
|
|
|
this.on('users.id', '=', 'contacts.user_id').orOn(...);
|
|
|
|
|
|
})
|
|
|
|
|
|
.exec(function(err, resp) { ... });
|
|
|
|
|
|
</pre>
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-groupBy">
|
|
|
|
|
|
<b class="header">groupBy</b><code>.groupBy(*names)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Adds a <tt>group by</tt> clause to the query.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-orderBy">
|
|
|
|
|
|
<b class="header">orderBy</b><code>.orderBy(column, [direction])</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Adds an <tt>order by</tt> clause to the query.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-having">
|
|
|
|
|
|
<b class="header">having</b><code>.having(column, operator, value)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Adds a <tt>having</tt> clause to the query.
|
|
|
|
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
|
Knex('users')
|
|
|
|
|
|
.groupBy('count')
|
|
|
|
|
|
.orderBy('name', 'desc')
|
|
|
|
|
|
.having('count', '>', 100)
|
|
|
|
|
|
.select()
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</pre>
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-offset">
|
|
|
|
|
|
<b class="header">offset</b><code>.offset(value)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Adds an <tt>offset</tt> clause to the query.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-limit">
|
|
|
|
|
|
<b class="header">limit</b><code>.limit(value)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Adds a <tt>limit</tt> clause to the query.
|
2013-05-04 20:36:02 -04:00
|
|
|
|
</p>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
|
Knex('users')
|
|
|
|
|
|
.limit(10)
|
|
|
|
|
|
.offset(30)
|
2013-05-22 13:14:51 -04:00
|
|
|
|
.select()
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</pre>
|
|
|
|
|
|
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<p id="Builder-union">
|
|
|
|
|
|
<b class="header">union</b><code>.union(query)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Creates a <tt>union</tt> query, taking a callback to build the union statement.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-unionAll">
|
|
|
|
|
|
<b class="header">unionAll</b><code>.unionAll(query)</code>
|
|
|
|
|
|
<br />
|
2013-05-22 13:14:51 -04:00
|
|
|
|
Creates a <tt>union all</tt> query, with the same method signature as
|
2013-05-13 10:38:28 -04:00
|
|
|
|
the <a href="#Builder-union">union</a> method.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
|
Knex('users').whereNull('last_name').union(function() {
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-05-13 10:38:28 -04:00
|
|
|
|
this.select('*').from('users').whereNull('first_name');
|
|
|
|
|
|
|
|
|
|
|
|
}).select().then(function() { ... });
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
2013-05-04 20:36:02 -04:00
|
|
|
|
<p id="Builder-insert">
|
2013-07-17 13:52:58 -04:00
|
|
|
|
<b class="header">insert</b><code>.insert(data, [returning])</code>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<br />
|
2013-05-04 20:36:02 -04:00
|
|
|
|
Creates an <tt>insert</tt> query, taking either a hash of properties to be inserted into the row, or
|
2013-05-22 13:14:51 -04:00
|
|
|
|
an array of inserts, to be executed as a single insert command. Resolves the promise / fulfills the callback
|
2013-05-13 10:38:28 -04:00
|
|
|
|
with an array containing the first insert id of the inserted model, or an array containing all inserted <tt>ids</tt>
|
|
|
|
|
|
for postgresql.
|
2013-05-04 20:36:02 -04:00
|
|
|
|
</p>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
|
|
|
|
|
|
<pre>
|
2013-07-17 13:52:58 -04:00
|
|
|
|
// Returns [1] in "mysql", "sqlite"; [] in "postgresql" unless the 'returning' parameter is set.
|
2013-05-04 20:06:39 -04:00
|
|
|
|
Knex('books').insert({title: 'Slaughterhouse Five'})
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-05-13 10:38:28 -04:00
|
|
|
|
// Returns [2] in "mysql", "sqlite"; [2, 3] in "postgresql"
|
2013-03-12 11:52:08 -04:00
|
|
|
|
Knex('books')
|
2013-07-17 13:52:58 -04:00
|
|
|
|
.insert([{title: 'Great Gatsby'}, {title: 'Fahrenheit 451'}], 'id')
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-returning">
|
|
|
|
|
|
<b class="header">returning</b><code>.returning(column)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Only utilitzed by PostgreSQL databases, the returning method specifies which column should be returned
|
|
|
|
|
|
by the <a href="#Builder-insert">insert</a> method.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
|
// Returns [1]
|
|
|
|
|
|
Knex('books')
|
|
|
|
|
|
.returning('id')
|
|
|
|
|
|
.insert({title: 'Slaughterhouse Five'})
|
|
|
|
|
|
|
|
|
|
|
|
// Returns [2] in "mysql", "sqlite"; [2, 3] in "postgresql"
|
|
|
|
|
|
Knex('books')
|
|
|
|
|
|
.returning('id')
|
2013-05-22 13:14:51 -04:00
|
|
|
|
.insert([{title: 'Great Gatsby'}, {title: 'Fahrenheit 451'}])
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-update">
|
2013-05-04 20:06:39 -04:00
|
|
|
|
<b class="header">update</b><code>.update(data)</code>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<br />
|
2013-05-13 10:38:28 -04:00
|
|
|
|
Creates an <tt>update</tt> query, taking a hash of properties to be updated based on the
|
2013-05-22 13:14:51 -04:00
|
|
|
|
other query constraints. Resolves the promise / fulfills the callback with the number
|
2013-05-13 10:38:28 -04:00
|
|
|
|
of affected rows for the query.
|
2013-05-05 12:38:32 -04:00
|
|
|
|
</p>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
|
|
|
|
|
|
<pre>
|
2013-05-13 10:38:28 -04:00
|
|
|
|
Knex('books')
|
|
|
|
|
|
.where('published_date', '<', 2000)
|
|
|
|
|
|
.update({
|
|
|
|
|
|
status: 'archived'
|
|
|
|
|
|
})
|
|
|
|
|
|
.then(...
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-del">
|
2013-05-04 20:06:39 -04:00
|
|
|
|
<b class="header">del / delete</b><code>.del()</code>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<br />
|
|
|
|
|
|
Aliased to <tt>del</tt> as <tt>delete</tt> is a reserved word in javascript, this method deletes
|
2013-05-22 13:14:51 -04:00
|
|
|
|
one or more rows, based on other conditions specified in the query. Resolves the promise / fulfills the
|
2013-05-13 10:38:28 -04:00
|
|
|
|
callback with the number of affected rows for the query.
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-05-08 20:16:39 -04:00
|
|
|
|
<pre>
|
|
|
|
|
|
Knex('accounts')
|
|
|
|
|
|
.where('activated', false)
|
|
|
|
|
|
.del()
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
2013-07-17 13:52:58 -04:00
|
|
|
|
<p id="Builder-transacting">
|
|
|
|
|
|
<b class="header">transacting</b><code>.transacting(transactionObj)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Used by <a href="#Transaction">Knex.Transaction</a>, the transacting method may be chained to any
|
|
|
|
|
|
query and passed the object you wish to join the query as part of the transaction for.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
|
Knex.Transaction(function(t) {
|
|
|
|
|
|
|
|
|
|
|
|
Knex('books')
|
|
|
|
|
|
.transacting(t)
|
|
|
|
|
|
.insert({name: 'Old Books'})
|
|
|
|
|
|
.then(function(row) {
|
|
|
|
|
|
|
|
|
|
|
|
return When.all(_.map([
|
|
|
|
|
|
{title: 'Canterbury Tales'},
|
|
|
|
|
|
{title: 'Moby Dick'},
|
|
|
|
|
|
{title: 'Hamlet'}
|
|
|
|
|
|
], function(info) {
|
|
|
|
|
|
|
|
|
|
|
|
info.row_id = row.id;
|
|
|
|
|
|
|
|
|
|
|
|
// Some validation could take place here.
|
|
|
|
|
|
return Knex('book').transacting(t).insert(info);
|
|
|
|
|
|
|
|
|
|
|
|
}));
|
|
|
|
|
|
})
|
|
|
|
|
|
.then(function() {
|
|
|
|
|
|
t.commit('You saved 3 books');
|
|
|
|
|
|
}, t.rollback);
|
|
|
|
|
|
|
|
|
|
|
|
}).then(function(resp) {
|
|
|
|
|
|
console.log(resp);
|
|
|
|
|
|
}, function(err) {
|
|
|
|
|
|
console.log(err.message);
|
|
|
|
|
|
});
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<p id="Builder-count">
|
2013-05-04 20:06:39 -04:00
|
|
|
|
<b class="header">count</b><code>.count(column)</code>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<br />
|
2013-05-13 10:38:28 -04:00
|
|
|
|
Performs a count on the specified <b>column</b>.
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-min">
|
2013-05-04 20:06:39 -04:00
|
|
|
|
<b class="header">min</b><code>.min(column)</code>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<br />
|
2013-05-13 10:38:28 -04:00
|
|
|
|
Gets the minimum value for the specified <b>column</b>.
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-max">
|
2013-05-04 20:06:39 -04:00
|
|
|
|
<b class="header">max</b><code>.max(column)</code>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<br />
|
2013-05-13 10:38:28 -04:00
|
|
|
|
Gets the maximum value for the specified <b>column</b>.
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-sum">
|
2013-05-04 20:06:39 -04:00
|
|
|
|
<b class="header">sum</b><code>.sum(column)</code>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<br />
|
2013-05-13 10:38:28 -04:00
|
|
|
|
Retrieve the sum of the values of a given <b>column</b>.
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-increment">
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<b class="header">increment</b><code>.increment(column, amount)</code>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<br />
|
2013-05-13 10:38:28 -04:00
|
|
|
|
Increments a <b>column</b> value by the specified <b>amount</b>.
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-decrement">
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<b class="header">decrement</b><code>.decrement(column, amount)</code>
|
2013-05-10 14:12:28 -04:00
|
|
|
|
<br />
|
2013-05-13 10:38:28 -04:00
|
|
|
|
Decrements a <b>column</b> value by the specified <b>amount</b>.
|
2013-05-10 14:12:28 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-truncate">
|
|
|
|
|
|
<b class="header">truncate</b><code>.truncate()</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Truncates the current table.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-debug">
|
|
|
|
|
|
<b class="header">debug</b><code>.debug()</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Turns on debugging for the current query chain.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<h3 id="Builder-Interface">Builder Interface Methods:</h3>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-then">
|
|
|
|
|
|
<b class="header">then</b><code>.then(onFulfilled, onRejected)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Coerces the current query builder chain into a promise state, accepting the resolve
|
2013-06-09 17:09:57 -04:00
|
|
|
|
and reject handlers as specified by the <a href="http://promises-aplus.github.com/promises-spec">Promises/A+ spec</a>.
|
2013-05-13 10:38:28 -04:00
|
|
|
|
As stated in the spec, more than one call to the <tt>then</tt> method for the current query chain will resolve
|
|
|
|
|
|
with the same value, in the order they were called; the query will not be executed multiple times.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-exec">
|
|
|
|
|
|
<b class="header">exec</b><code>.exec(callback)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
If you'd prefer a callback interface over promises, the <b>exec</b> function
|
|
|
|
|
|
accepts a standard node style callback for executing the query chain. Note that as
|
|
|
|
|
|
with the <a href="#Builder-then">then</a> method, subsequent calls to the same
|
|
|
|
|
|
query chain will return the same result.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Builder-toString">
|
|
|
|
|
|
<b class="header">toString</b><code>.toString()</code>
|
|
|
|
|
|
<br />
|
2013-05-22 13:14:51 -04:00
|
|
|
|
Returns an array of query strings filled out with the
|
2013-05-13 10:38:28 -04:00
|
|
|
|
correct values based on bindings, etc. Useful for debugging.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<h2 id="Transaction">Knex.Transaction</h2>
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
Transactions are handled by passing a handler function into <tt>Knex.Transaction</tt>.
|
|
|
|
|
|
The handler function accepts a single argument, the promise for committing or rolling back
|
|
|
|
|
|
the transaction. This argument is then passed into any queries which are involved in the current
|
|
|
|
|
|
transcaction, working by explicitly passing the .
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<pre>
|
2013-04-29 15:52:16 -04:00
|
|
|
|
Knex.Transaction(function(t) {
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-04-29 15:52:16 -04:00
|
|
|
|
Knex('books')
|
|
|
|
|
|
.transacting(t)
|
|
|
|
|
|
.insert({name: 'Old Books'})
|
|
|
|
|
|
.then(function(row) {
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-05-13 10:38:28 -04:00
|
|
|
|
return When.all(_.map([
|
2013-04-29 15:52:16 -04:00
|
|
|
|
{title: 'Canterbury Tales'},
|
|
|
|
|
|
{title: 'Moby Dick'},
|
|
|
|
|
|
{title: 'Hamlet'}
|
|
|
|
|
|
], function(info) {
|
|
|
|
|
|
|
|
|
|
|
|
info.row_id = row.id;
|
|
|
|
|
|
|
|
|
|
|
|
// Some validation could take place here.
|
|
|
|
|
|
return Knex('book').transacting(t).insert(info);
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-04-29 15:52:16 -04:00
|
|
|
|
}));
|
|
|
|
|
|
})
|
|
|
|
|
|
.then(t.commit, t.rollback);
|
|
|
|
|
|
|
|
|
|
|
|
}).then(function() {
|
|
|
|
|
|
console.log('3 new books saved.');
|
|
|
|
|
|
}, function() {
|
|
|
|
|
|
console.log('Error saving the books.');
|
|
|
|
|
|
});
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</pre>
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<h2 id="Schema">Knex.Schema</h2>
|
|
|
|
|
|
|
2013-03-12 12:23:45 -04:00
|
|
|
|
<p id="Schema-createTable">
|
2013-05-04 20:06:39 -04:00
|
|
|
|
<b class="header">createTable</b><code>Knex.Schema.createTable(tableName, callback)</code>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<br />
|
2013-05-22 13:14:51 -04:00
|
|
|
|
Creates a new table on the database, with a callback function to modify the table's
|
2013-03-12 12:23:45 -04:00
|
|
|
|
structure, using the <a href="#Schema-Building">schema-building</a> commands.
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<pre>
|
2013-05-15 19:25:51 -04:00
|
|
|
|
Knex.Schema.createTable('users', function (table) {
|
2013-03-12 11:52:08 -04:00
|
|
|
|
table.string('name');
|
|
|
|
|
|
table.timestamps();
|
|
|
|
|
|
}).then(function () {
|
|
|
|
|
|
console.log('Users Table is Created!');
|
|
|
|
|
|
});
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<p id="Schema-renameTable">
|
|
|
|
|
|
<b class="header">renameTable</b><code>Knex.Schema.renameTable(from, to)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Renames a table <b>from</b> a current tableName <b>to</b> another.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-03-12 12:23:45 -04:00
|
|
|
|
<p id="Schema-dropTable">
|
2013-05-04 20:06:39 -04:00
|
|
|
|
<b class="header">dropTable</b><code>Knex.Schema.dropTable(tableName)</code>
|
2013-03-12 12:23:45 -04:00
|
|
|
|
<br />
|
2013-05-13 10:38:28 -04:00
|
|
|
|
Drops a table, specified by <b>tableName</b>.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Schema-hasTable">
|
|
|
|
|
|
<b class="header">hasTable</b><code>Knex.Schema.hasTable(tableName)</code>
|
|
|
|
|
|
<br />
|
2013-08-07 12:24:36 -04:00
|
|
|
|
Checks for a table's existence by <b>tableName</b>, resolving with a boolean to
|
|
|
|
|
|
signal if the table exists.
|
2013-03-12 12:23:45 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<pre>
|
2013-08-07 12:24:36 -04:00
|
|
|
|
Knex.Schema.hasTable('users').then(function(exists) {
|
|
|
|
|
|
if (!exists) {
|
|
|
|
|
|
return Knex.Schema.createTable('users', function(t) {
|
|
|
|
|
|
t.increments('id').primary();
|
|
|
|
|
|
t.string('first_name', 100);
|
|
|
|
|
|
t.string('last_name', 100);
|
|
|
|
|
|
t.text('bio');
|
|
|
|
|
|
});
|
|
|
|
|
|
}
|
2013-05-13 10:38:28 -04:00
|
|
|
|
});
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
2013-03-12 12:23:45 -04:00
|
|
|
|
<p id="Schema-dropTableIfExists">
|
2013-05-04 20:06:39 -04:00
|
|
|
|
<b class="header">dropTableIfExists</b><code>Knex.Schema.dropTableIfExists(tableName)</code>
|
2013-03-12 12:23:45 -04:00
|
|
|
|
<br />
|
|
|
|
|
|
Drops a table conditionally if the table exists, specified by <tt>tableName</tt>.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<p id="Schema-table">
|
2013-05-04 20:06:39 -04:00
|
|
|
|
<b class="header">table</b><code>Knex.Schema.table(tableName, callback)</code>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<br />
|
|
|
|
|
|
Chooses a database table, and then modifies the table, using the <a href="#Schema-Building">Schema Building</a>
|
2013-05-05 18:29:28 -04:00
|
|
|
|
functions inside of the callback.
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
|
Knex.Schema.table('users', function (table) {
|
|
|
|
|
|
table.dropColumn('name');
|
|
|
|
|
|
table.string('first_name');
|
|
|
|
|
|
table.string('last_name');
|
|
|
|
|
|
}).then(function () {
|
|
|
|
|
|
console.log('Users Table is Updated!');
|
|
|
|
|
|
});
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h3 id="Schema-Building">Schema Building:</h3>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Schema-dropColumn">
|
|
|
|
|
|
<b class="header">dropColumn</b><code>table.dropColumn(name)</code>
|
|
|
|
|
|
<br />
|
2013-05-13 10:38:28 -04:00
|
|
|
|
Drops a column, specified by the column's <b>name</b>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Schema-dropColumns">
|
|
|
|
|
|
<b class="header">dropColumns</b><code>table.dropColumns(*columns)</code>
|
|
|
|
|
|
<br />
|
2013-05-13 10:38:28 -04:00
|
|
|
|
Drops multiple columns, taking a variable number of column names.
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Schema-increments">
|
|
|
|
|
|
<b class="header">increments</b><code>table.increments(name)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Adds an auto incrementing column. This will be used as the primary key for the column.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Schema-integer">
|
|
|
|
|
|
<b class="header">integer</b><code>table.integer(name)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Adds an integer column.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Schema-text">
|
|
|
|
|
|
<b class="header">text</b><code>table.text(name)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Adds a text column.
|
|
|
|
|
|
</p>
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<p id="Schema-string">
|
|
|
|
|
|
<b class="header">string</b><code>table.string(name)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Adds a string column.
|
|
|
|
|
|
</p>
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<p id="Schema-float">
|
|
|
|
|
|
<b class="header">float</b><code>table.float(column, [precision], [scale])</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Adds a float column, with optional precision and scale.
|
|
|
|
|
|
</p>
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<p id="Schema-decimal">
|
|
|
|
|
|
<b class="header">decimal</b><code>table.decimal(column, [precision], [scale])</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Adds a decimal column, with optional precision and scale.
|
|
|
|
|
|
</p>
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<p id="Schema-boolean">
|
|
|
|
|
|
<b class="header">boolean</b><code>table.boolean(name)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Adds a boolean column.
|
|
|
|
|
|
</p>
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<p id="Schema-date">
|
|
|
|
|
|
<b class="header">date</b><code>table.date(name)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Adds a date column.
|
|
|
|
|
|
</p>
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<p id="Schema-dateTime">
|
|
|
|
|
|
<b class="header">dateTime</b><code>table.dateTime(name)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Adds a dateTime column.
|
|
|
|
|
|
</p>
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<p id="Schema-time">
|
|
|
|
|
|
<b class="header">time</b><code>table.time(name)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Adds a time column.
|
|
|
|
|
|
</p>
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<p id="Schema-timestamp">
|
|
|
|
|
|
<b class="header">timestamp</b><code>table.timestamp(name)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Adds a timestamp column.
|
|
|
|
|
|
</p>
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-07-17 10:26:24 -04:00
|
|
|
|
<p id="Schema-timestamps">
|
|
|
|
|
|
<b class="header">timestamps</b><code>table.timestamps()</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Adds a <tt>created_at</tt> and <tt>updated_at</tt> column on the database,
|
|
|
|
|
|
setting these each to <a href="#Schema-dateTime">dateTime</a> types.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<p id="Schema-binary">
|
|
|
|
|
|
<b class="header">binary</b><code>table.binary(name)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Adds a binary column.
|
|
|
|
|
|
</p>
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-07-17 10:26:24 -04:00
|
|
|
|
<p id="Schema-enum">
|
|
|
|
|
|
<b class="header">enum / enu</b><code>table.enu(col, values)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Adds a enum column, (aliased to <tt>enu</tt>, as enum is a reserved word in javascript).
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-06-16 22:31:29 +10:00
|
|
|
|
<p id="Schema-json">
|
|
|
|
|
|
<b class="header">json</b><code>table.json(name)</code>
|
|
|
|
|
|
<br />
|
2013-07-17 10:26:24 -04:00
|
|
|
|
Adds a json column, using the built-in json type in postgresql, defaulting to a text column
|
|
|
|
|
|
in older versions of postgresql or in unsupported databases.
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
2013-05-22 13:14:51 -04:00
|
|
|
|
|
2013-07-17 10:26:24 -04:00
|
|
|
|
<p id="Schema-uuid">
|
|
|
|
|
|
<b class="header">uuid</b><code>table.uuid(name)</code>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<br />
|
2013-07-17 10:26:24 -04:00
|
|
|
|
Adds a uuid column - this uses the built-in uuid type in postgresql, and falling back to a
|
|
|
|
|
|
<tt>char(36)</tt> in other databases.
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-05-15 19:39:20 -04:00
|
|
|
|
<p id="Schema-engine">
|
|
|
|
|
|
<b class="header">engine</b><code>table.engine(val)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Sets the engine for the database, only available within a <tt>createTable</tt> call, and only
|
2013-08-22 16:04:20 -04:00
|
|
|
|
applicable to MySQL.
|
2013-05-15 19:39:20 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-06-16 20:49:04 +10:00
|
|
|
|
<p id="Schema-comment">
|
|
|
|
|
|
<b class="header">comment</b><code>table.comment(value)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Sets the comment for a table.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-05-04 21:37:10 -04:00
|
|
|
|
<h3 id="Chainable">Chainable Methods:</h3>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
The following three methods may be chained on the schema building methods, as modifiers to the column.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<p id="Chainable-index">
|
|
|
|
|
|
<b class="header">index</b><code>column.index()</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Specifies an integer as index. No-op if this is chained off of a non-integer field.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-05-15 19:25:51 -04:00
|
|
|
|
<p id="Chainable-primary">
|
|
|
|
|
|
<b class="header">primary</b><code>column.primary()</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Sets the field as the primary key for the table.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="Chainable-unique">
|
|
|
|
|
|
<b class="header">unique</b><code>column.unique()</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Sets the column as unique.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-05-04 21:37:10 -04:00
|
|
|
|
<p id="Chainable-defaultTo">
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<b class="header">defaultTo</b><code>column.defaultTo(value)</code>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<br />
|
|
|
|
|
|
Sets the default value for the column on an insert.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-05-04 21:37:10 -04:00
|
|
|
|
<p id="Chainable-unsigned">
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<b class="header">unsigned</b><code>column.unsigned()</code>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<br />
|
|
|
|
|
|
Specifies an integer as unsigned. No-op if this is chained off of a non-integer field.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-05-04 21:37:10 -04:00
|
|
|
|
<p id="Chainable-nullable">
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<b class="header">nullable</b><code>column.nullable()</code>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<br />
|
|
|
|
|
|
Allows a field to be nullable. No-op if chained off of a non-nullable field.
|
2013-05-04 21:37:10 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-05-15 19:25:51 -04:00
|
|
|
|
<p id="Chainable-after">
|
|
|
|
|
|
<b class="header">after</b><code>column.after(field)</code>
|
2013-05-04 21:37:10 -04:00
|
|
|
|
<br />
|
2013-08-22 16:04:20 -04:00
|
|
|
|
Sets the column to be inserted after another, only used in MySQL alter tables.
|
2013-05-04 21:37:10 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-06-16 20:49:04 +10:00
|
|
|
|
<p id="Chainable-comment">
|
|
|
|
|
|
<b class="header">comment</b><code>column.comment(value)</code>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
Sets the comment for a column.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-05-04 21:37:10 -04:00
|
|
|
|
<pre>
|
2013-05-28 09:10:42 -04:00
|
|
|
|
Knex.Schema.createTable('accounts', function() {
|
2013-05-04 21:37:10 -04:00
|
|
|
|
t.increments().primary();
|
|
|
|
|
|
t.string('email').unique();
|
|
|
|
|
|
});
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<h2 id="Raw">Knex.Raw</h2>
|
|
|
|
|
|
|
|
|
|
|
|
<h3 id="Raw-Expression">Raw Expressions:</h3>
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
2013-05-22 13:14:51 -04:00
|
|
|
|
Sometimes you may need to use a raw expression in a query. These expressions will be injected
|
|
|
|
|
|
into the query as strings, so be careful not to create any SQL injection points!
|
2013-05-13 10:38:28 -04:00
|
|
|
|
To create a raw expression, you may use the <tt>Knex.Raw</tt> function.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
|
Knex('users')
|
|
|
|
|
|
.select(Knex.Raw('count(*) as user_count, status'))
|
|
|
|
|
|
.where('status', '<>', 1)
|
|
|
|
|
|
.groupBy('status')
|
2013-05-14 17:31:54 -04:00
|
|
|
|
.then(...
|
2013-05-13 10:38:28 -04:00
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
|
|
<h3 id="Raw-Queries">Raw Queries:</h3>
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
The <tt>Knex.Raw</tt> may also be used to build a full query and execute it, as a
|
2013-05-22 13:14:51 -04:00
|
|
|
|
standard query builder query would be executed. The benefit of this is that it uses the connection
|
2013-05-13 10:38:28 -04:00
|
|
|
|
pool and provides a standard interface for the different client libraries.
|
|
|
|
|
|
Note that the response will be whatever the underlying sql library would typically return on a
|
2013-05-28 10:15:06 -04:00
|
|
|
|
normal query, so you may need to look at the documentation for the base library the queries are
|
|
|
|
|
|
executing against to determine how to handle the response.
|
2013-05-22 13:14:51 -04:00
|
|
|
|
</p>
|
2013-05-13 10:38:28 -04:00
|
|
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
|
Knex.Raw('select * from users where id = 1').then(function(resp) {
|
|
|
|
|
|
...
|
|
|
|
|
|
});
|
|
|
|
|
|
</pre>
|
2013-05-03 00:20:51 -04:00
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<h2 id="faq">F.A.Q.</h2>
|
|
|
|
|
|
|
2013-05-10 14:12:28 -04:00
|
|
|
|
<p id="faq-debug">
|
|
|
|
|
|
<b class="header">How do I debug?</b><br />
|
|
|
|
|
|
If you pass <tt>{debug: true}</tt> as one of the options in your initialize settings, you can see
|
|
|
|
|
|
all of the query calls being made. Sometimes you need to dive a bit further into
|
2013-05-22 13:14:51 -04:00
|
|
|
|
the various calls and see what all is going on behind the scenes. I'd recommend
|
2013-05-10 14:12:28 -04:00
|
|
|
|
<a href="https://github.com/dannycoates/node-inspector">node-inspector</a>, which allows you to debug
|
|
|
|
|
|
code with <tt>debugger</tt> statements like you would in the browser.
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-05-10 14:12:28 -04:00
|
|
|
|
<p id="faq-tests">
|
|
|
|
|
|
<b class="header">How do I run the test suite?</b><br />
|
2013-05-13 10:38:28 -04:00
|
|
|
|
The test suite looks for an environment variable called <tt>KNEX_TEST</tt> for the path to the database
|
|
|
|
|
|
configuration. If you run the following command:
|
|
|
|
|
|
<tt>$ export KNEX_TEST='/path/to/your/knex_config.js'</tt>, replacing with the path to your config file,
|
2013-05-22 13:14:51 -04:00
|
|
|
|
and the config file is valid, the test suite should run with <tt>npm test</tt>. If you're going to
|
|
|
|
|
|
add a test, you may want to follow similar patterns, used in the test suite,
|
2013-05-13 10:38:28 -04:00
|
|
|
|
setting <tt>$ export KNEX_DEV=1</tt> to save the outputs data from the tests into the <tt>shared/output.js</tt> file.
|
2013-05-10 14:12:28 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p id="faq-nonode">
|
|
|
|
|
|
<b class="header">Can I use Knex outside of Node.js</b><br />
|
|
|
|
|
|
While there isn't a client adapter yet, it should be possible to run
|
2013-05-22 13:14:51 -04:00
|
|
|
|
it could be adapted to work with other javascript environments supporting a <tt>sqlite3</tt>
|
2013-05-10 14:12:28 -04:00
|
|
|
|
database, by providing a custom <a href="http://knexjs.org/#Adapters">Knex adapter</a>.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<h2 id="changelog">Change Log</h2>
|
|
|
|
|
|
|
2013-08-22 21:42:18 -04:00
|
|
|
|
<p>
|
|
|
|
|
|
<b class="header">0.2.4</b> — <small><i>Aug 22, 2013</i></small><br />
|
|
|
|
|
|
Fix SQLite3 delete not returning affected row count (#45).
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-08-22 16:46:13 -04:00
|
|
|
|
<p>
|
|
|
|
|
|
<b class="header">0.2.3</b> — <small><i>Aug 22, 2013</i></small><br />
|
|
|
|
|
|
Fix insert with default values in PostgreSQL and SQLite3, (#44).
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-08-20 00:50:04 -04:00
|
|
|
|
<p>
|
|
|
|
|
|
<b class="header">0.2.2</b> — <small><i>Aug 20, 2013</i></small><br />
|
|
|
|
|
|
Allowing <tt>Raw</tt> queries to be passed as the primary table names.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-08-13 17:50:22 -04:00
|
|
|
|
<p>
|
|
|
|
|
|
<b class="header">0.2.1</b> — <small><i>Aug 13, 2013</i></small><br />
|
|
|
|
|
|
Fix for an array passed to <tt>insert</tt> being mutated.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-08-07 12:24:36 -04:00
|
|
|
|
<p>
|
|
|
|
|
|
<b class="header">0.2.0</b> — <small><i>Aug 7, 2013</i></small><br />
|
|
|
|
|
|
<b>Breaking changes:</b>
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li>
|
|
|
|
|
|
<a href="#Schema-hasTable">hasTable</a> now returns a boolean rather than a failed promise.
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li>
|
|
|
|
|
|
Changed syntax for insert in postgresql, where the <tt>id</tt> is not assumed on inserts (#18).
|
|
|
|
|
|
The second parameter of <a href="#Builder-insert">insert</a> is now required to return an array of insert id's for the last insert.
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li>
|
|
|
|
|
|
The <a href="#Schema-timestamp">timestamp</a> method on the schema builder now uses a <tt>dateTime</tt> rather than a <tt>timestamp</tt>.
|
|
|
|
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
Restored basic binding support on <tt>Raw</tt> queries (#19).
|
|
|
|
|
|
Added support for the JSON and UUID datatypes in postgres (#20).
|
|
|
|
|
|
Fix enabling enum in postgresql (#21).
|
|
|
|
|
|
Added foreign key support (#24).
|
|
|
|
|
|
Bugfix for column ordering on insert (#31).
|
|
|
|
|
|
Other minor bugfixes, documentation cleanup, & tweaks.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-07-07 13:59:49 -04:00
|
|
|
|
<p>
|
|
|
|
|
|
<b class="header">0.1.8</b> — <small><i>July 7, 2013</i></small><br />
|
|
|
|
|
|
Somehow missing the <tt>!=</tt> operator. Using <tt>_.find</tt> rather than <tt>_.where</tt> in <tt>getCommandsByName</tt>(#22).
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-06-12 08:44:49 -04:00
|
|
|
|
<p>
|
|
|
|
|
|
<b class="header">0.1.7</b> — <small><i>June 12, 2013</i></small><br />
|
|
|
|
|
|
Ensures unhandled errors in the <tt>exec</tt> callback interface are re-thrown.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-06-09 16:57:31 -04:00
|
|
|
|
<p>
|
|
|
|
|
|
<b class="header">0.1.6</b> — <small><i>June 9, 2013</i></small><br />
|
|
|
|
|
|
Renaming <tt>beforeCreate</tt> to <tt>afterCreate</tt>. Better handling of errors in the connection pooling.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-06-09 14:05:30 -04:00
|
|
|
|
<p>
|
|
|
|
|
|
<b class="header">0.1.5</b> — <small><i>June 9, 2013</i></small><br />
|
|
|
|
|
|
Added the ability to specify <tt>beforeCreate</tt> and <tt>beforeDestroy</tt> hooks on the initialize's <tt>options.pool</tt>
|
|
|
|
|
|
to perform any necessary database setup/teardown on connections before use (#14). <tt>where</tt> and <tt>having</tt>
|
|
|
|
|
|
may now accept <tt>Knex.Raw</tt> instances, for consistency (#15). Added an <tt>orHaving</tt> method to the builder.
|
|
|
|
|
|
The ability to specify bindings on Raw queries has been removed.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-05-22 13:14:51 -04:00
|
|
|
|
<p>
|
|
|
|
|
|
<b class="header">0.1.4</b> — <small><i>May 22, 2013</i></small><br />
|
|
|
|
|
|
<tt>defaultTo</tt> now accepts <tt>"false"</tt> for boolean columns, allows for empty strings as default values.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-05-18 00:07:28 -04:00
|
|
|
|
<p>
|
|
|
|
|
|
<b class="header">0.1.3</b> — <small><i>May 18, 2013</i></small><br />
|
|
|
|
|
|
Enabling table aliases (#11). Fix for issues with transactions not functioning (#12).
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-05-15 19:39:20 -04:00
|
|
|
|
<p>
|
|
|
|
|
|
<b class="header">0.1.2</b> — <small><i>May 15, 2013</i></small><br />
|
2013-05-22 13:14:51 -04:00
|
|
|
|
Bug fixes for <tt>groupBy</tt> (#7). Mysql using collation, charset config settings in <tt>createTable</tt>.
|
2013-05-18 00:07:28 -04:00
|
|
|
|
Added engine on <tt>schemaBuilder</tt> specifier (#6). Other doc fixes, tests.
|
2013-05-15 19:39:20 -04:00
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-05-14 17:31:54 -04:00
|
|
|
|
<p>
|
|
|
|
|
|
<b class="header">0.1.1</b> — <small><i>May 14, 2013</i></small><br />
|
2013-05-22 13:14:51 -04:00
|
|
|
|
Bug fixes for sub-queries, minor changes to initializing "main" instance, adding "pg" as
|
2013-05-14 17:31:54 -04:00
|
|
|
|
a valid parameter for the client name in the connection settings.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
2013-03-12 11:52:08 -04:00
|
|
|
|
<p>
|
2013-05-13 10:38:28 -04:00
|
|
|
|
<b class="header">0.1.0</b> — <small><i>May 13, 2013</i></small><br />
|
2013-03-12 11:52:08 -04:00
|
|
|
|
Initial Knex release.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
</div>
|
2013-04-01 00:50:50 -04:00
|
|
|
|
<script src="docs/public/scripts/ga.js" type="text/javascript" charset="utf-8"></script>
|
2013-03-12 11:52:08 -04:00
|
|
|
|
</body>
|
|
|
|
|
|
</html>
|
