forked from knex/documentation
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
1010 lines (942 loc) · 508 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!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="apple-touch-icon" sizes="180x180" href="assets/favicons/apple-touch-icon.png" />
<link rel="icon" type="image/png" href="assets/favicons/favicon-32x32.png" sizes="32x32" />
<link rel="icon" type="image/png" href="assets/favicons/favicon-16x16.png" sizes="16x16" />
<link rel="manifest" href="assets/favicons/manifest.json" />
<link rel="mask-icon" href="assets/favicons/safari-pinned-tab.svg" color="#e16426" />
<meta name="theme-color" content="#ffffff" />
<link rel="stylesheet" href="build/bundle.css" />
<title>Knex.js - A SQL Query Builder for Javascript</title>
</head>
<body>
<div id="documentation"><div data-reactroot="" data-reactid="1" data-react-checksum="-1497673958"><div id="sidebar" class="interface" data-reactid="2"><a class="toc_title" href="#changelog" data-reactid="3"><!-- react-text: 4 -->Knex.js <!-- /react-text --><span class="version" data-reactid="5"><!-- react-text: 6 -->(<!-- /react-text --><!-- react-text: 7 -->0.20.0<!-- /react-text --><!-- react-text: 8 -->)<!-- /react-text --></span></a><ul class="toc_section" data-reactid="9"><li data-reactid="10"><!-- react-text: 11 -->» <!-- /react-text --><a href="https://github.com/tgriesser/knex" data-reactid="12">GitHub Repository</a></li><li data-reactid="13"><!-- react-text: 14 -->» <!-- /react-text --><a href="#support" data-reactid="15">Support</a></li><li data-reactid="16"><!-- react-text: 17 -->» <!-- /react-text --><a href="#faq" data-reactid="18">FAQ</a></li><li data-reactid="19"><!-- react-text: 20 -->» <!-- /react-text --><a href="#changelog" data-reactid="21">Change Log</a></li></ul><a class="toc_title" href="#Installation" data-reactid="22">Installation</a><ul class="toc_section" data-reactid="23"><li data-reactid="24"><!-- react-text: 25 -->– <!-- /react-text --><a href="#Installation-node" data-reactid="26">Node.js</a></li><li data-reactid="27"><!-- react-text: 28 -->– <!-- /react-text --><a href="#Installation-browser" data-reactid="29">Browser</a></li><li data-reactid="30"><b data-reactid="31"><a href="#Installation-client" data-reactid="32">Config Options:</a></b></li><li data-reactid="33"><!-- react-text: 34 --> – <!-- /react-text --><a href="#Installation-client" data-reactid="35">client</a></li><li data-reactid="36"><!-- react-text: 37 --> – <!-- /react-text --><a href="#Installation-debug" data-reactid="38">debug</a></li><li data-reactid="39"><!-- react-text: 40 --> – <!-- /react-text --><a href="#Installation-asyncStackTraces" data-reactid="41">Async stacktraces</a></li><li data-reactid="42"><!-- react-text: 43 --> – <!-- /react-text --><a href="#Installation-pooling" data-reactid="44">pooling</a></li><li data-reactid="45"><!-- react-text: 46 --> – <!-- /react-text --><a href="#Installation-pooling-afterCreate" data-reactid="47">afterCreate</a></li><li data-reactid="48"><!-- react-text: 49 --> – <!-- /react-text --><a href="#Installation-acquireConnectionTimeout" data-reactid="50">acquireConnectionTimeout</a></li><li data-reactid="51"><!-- react-text: 52 --> – <!-- /react-text --><a href="#Installation-fetchAsString" data-reactid="53">fetchAsString</a></li><li data-reactid="54"><!-- react-text: 55 --> – <!-- /react-text --><a href="#Installation-migrations" data-reactid="56">migrations</a></li><li data-reactid="57"><!-- react-text: 58 --> – <!-- /react-text --><a href="#Installation-post-process-response" data-reactid="59">postProcessResponse</a></li><li data-reactid="60"><!-- react-text: 61 --> – <!-- /react-text --><a href="#Installation-wrap-identifier" data-reactid="62">wrapIdentifier</a></li><li data-reactid="63"><!-- react-text: 64 --> – <!-- /react-text --><a href="#Installation-log" data-reactid="65">log</a></li></ul><a class="toc_title" href="#typescript-support" data-reactid="66">TypeScript Support</a><a class="toc_title" href="#Builder" data-reactid="67">Query Builder</a><ul class="toc_section" data-reactid="68"><li data-reactid="69"><!-- react-text: 70 -->– <!-- /react-text --><a href="#Builder-identifier-syntax" data-reactid="71"><b data-reactid="72">Identifier Syntax</b></a></li><li data-reactid="73"><!-- react-text: 74 -->– <!-- /react-text --><a href="#Builder-knex" data-reactid="75"><b data-reactid="76">constructor</b></a></li><li data-reactid="77"><!-- react-text: 78 -->– <!-- /react-text --><a href="#Builder-timeout" data-reactid="79">timeout</a></li><li data-reactid="80"><!-- react-text: 81 -->– <!-- /react-text --><a href="#Builder-select" data-reactid="82">select</a></li><li data-reactid="83"><!-- react-text: 84 -->– <!-- /react-text --><a href="#Builder-as" data-reactid="85">as</a></li><li data-reactid="86"><!-- react-text: 87 -->– <!-- /react-text --><a href="#Builder-column" data-reactid="88">column</a></li><li data-reactid="89"><!-- react-text: 90 -->– <!-- /react-text --><a href="#Builder-from" data-reactid="91">from</a></li><li data-reactid="92"><!-- react-text: 93 -->– <!-- /react-text --><a href="#Builder-with" data-reactid="94">with</a></li><li data-reactid="95"><!-- react-text: 96 -->– <!-- /react-text --><a href="#Builder-withRecursive" data-reactid="97">withRecursive</a></li><li data-reactid="98"><!-- react-text: 99 -->– <!-- /react-text --><a href="#Builder-withSchema" data-reactid="100">withSchema</a></li><li data-reactid="101"><b data-reactid="102"><a href="#Builder-wheres" data-reactid="103">Where Methods:</a></b></li><li data-reactid="104"><!-- react-text: 105 --> – <!-- /react-text --><a href="#Builder-where" data-reactid="106">where</a></li><li data-reactid="107"><!-- react-text: 108 --> – <!-- /react-text --><a href="#Builder-whereNot" data-reactid="109">whereNot</a></li><li data-reactid="110"><!-- react-text: 111 --> – <!-- /react-text --><a href="#Builder-whereIn" data-reactid="112">whereIn</a></li><li data-reactid="113"><!-- react-text: 114 --> – <!-- /react-text --><a href="#Builder-whereNotIn" data-reactid="115">whereNotIn</a></li><li data-reactid="116"><!-- react-text: 117 --> – <!-- /react-text --><a href="#Builder-whereNull" data-reactid="118">whereNull</a></li><li data-reactid="119"><!-- react-text: 120 --> – <!-- /react-text --><a href="#Builder-whereNotNull" data-reactid="121">whereNotNull</a></li><li data-reactid="122"><!-- react-text: 123 --> – <!-- /react-text --><a href="#Builder-whereExists" data-reactid="124">whereExists</a></li><li data-reactid="125"><!-- react-text: 126 --> – <!-- /react-text --><a href="#Builder-whereNotExists" data-reactid="127">whereNotExists</a></li><li data-reactid="128"><!-- react-text: 129 --> – <!-- /react-text --><a href="#Builder-whereBetween" data-reactid="130">whereBetween</a></li><li data-reactid="131"><!-- react-text: 132 --> – <!-- /react-text --><a href="#Builder-whereNotBetween" data-reactid="133">whereNotBetween</a></li><li data-reactid="134"><!-- react-text: 135 --> – <!-- /react-text --><a href="#Builder-whereRaw" data-reactid="136">whereRaw</a></li><li data-reactid="137"><b data-reactid="138"><a href="#Builder-join" data-reactid="139">Join Methods:</a></b></li><li data-reactid="140"><!-- react-text: 141 --> – <!-- /react-text --><a href="#Builder-innerJoin" data-reactid="142">innerJoin</a></li><li data-reactid="143"><!-- react-text: 144 --> – <!-- /react-text --><a href="#Builder-leftJoin" data-reactid="145">leftJoin</a></li><li data-reactid="146"><!-- react-text: 147 --> – <!-- /react-text --><a href="#Builder-leftOuterJoin" data-reactid="148">leftOuterJoin</a></li><li data-reactid="149"><!-- react-text: 150 --> – <!-- /react-text --><a href="#Builder-rightJoin" data-reactid="151">rightJoin</a></li><li data-reactid="152"><!-- react-text: 153 --> – <!-- /react-text --><a href="#Builder-rightOuterJoin" data-reactid="154">rightOuterJoin</a></li><li data-reactid="155"><!-- react-text: 156 --> – <!-- /react-text --><a href="#Builder-fullOuterJoin" data-reactid="157">fullOuterJoin</a></li><li data-reactid="158"><!-- react-text: 159 --> – <!-- /react-text --><a href="#Builder-crossJoin" data-reactid="160">crossJoin</a></li><li data-reactid="161"><!-- react-text: 162 --> – <!-- /react-text --><a href="#Builder-joinRaw" data-reactid="163">joinRaw</a></li><li data-reactid="164"><b data-reactid="165"><a href="#Builder-on" data-reactid="166">On Methods:</a></b></li><li data-reactid="167"><!-- react-text: 168 --> – <!-- /react-text --><a href="#Builder-onIn" data-reactid="169">onIn</a></li><li data-reactid="170"><!-- react-text: 171 --> – <!-- /react-text --><a href="#Builder-onNotIn" data-reactid="172">onNotIn</a></li><li data-reactid="173"><!-- react-text: 174 --> – <!-- /react-text --><a href="#Builder-onNull" data-reactid="175">onNull</a></li><li data-reactid="176"><!-- react-text: 177 --> – <!-- /react-text --><a href="#Builder-onNotNull" data-reactid="178">onNotNull</a></li><li data-reactid="179"><!-- react-text: 180 --> – <!-- /react-text --><a href="#Builder-onExists" data-reactid="181">onExists</a></li><li data-reactid="182"><!-- react-text: 183 --> – <!-- /react-text --><a href="#Builder-onNotExists" data-reactid="184">onNotExists</a></li><li data-reactid="185"><!-- react-text: 186 --> – <!-- /react-text --><a href="#Builder-onBetween" data-reactid="187">onBetween</a></li><li data-reactid="188"><!-- react-text: 189 --> – <!-- /react-text --><a href="#Builder-onNotBetween" data-reactid="190">onNotBetween</a></li><li data-reactid="191"><b data-reactid="192"><a href="#Builder-havings" data-reactid="193">Having Methods:</a></b></li><li data-reactid="194"><!-- react-text: 195 --> – <!-- /react-text --><a href="#Builder-having" data-reactid="196">having</a></li><li data-reactid="197"><!-- react-text: 198 --> – <!-- /react-text --><a href="#Builder-havingIn" data-reactid="199">havingIn</a></li><li data-reactid="200"><!-- react-text: 201 --> – <!-- /react-text --><a href="#Builder-havingNotIn" data-reactid="202">havingNotIn</a></li><li data-reactid="203"><!-- react-text: 204 --> – <!-- /react-text --><a href="#Builder-havingNull" data-reactid="205">havingNull</a></li><li data-reactid="206"><!-- react-text: 207 --> – <!-- /react-text --><a href="#Builder-havingNotNull" data-reactid="208">havingNotNull</a></li><li data-reactid="209"><!-- react-text: 210 --> – <!-- /react-text --><a href="#Builder-havingExists" data-reactid="211">havingExists</a></li><li data-reactid="212"><!-- react-text: 213 --> – <!-- /react-text --><a href="#Builder-havingNotExists" data-reactid="214">havingNotExists</a></li><li data-reactid="215"><!-- react-text: 216 --> – <!-- /react-text --><a href="#Builder-havingBetween" data-reactid="217">havingBetween</a></li><li data-reactid="218"><!-- react-text: 219 --> – <!-- /react-text --><a href="#Builder-havingNotBetween" data-reactid="220">havingNotBetween</a></li><li data-reactid="221"><!-- react-text: 222 --> – <!-- /react-text --><a href="#Builder-havingRaw" data-reactid="223">havingRaw</a></li><li data-reactid="224"><b data-reactid="225"><a href="#Builder-clear" data-reactid="226">Clear Methods:</a></b></li><li data-reactid="227"><!-- react-text: 228 --> – <!-- /react-text --><a href="#Builder-clearSelect" data-reactid="229">clearSelect</a></li><li data-reactid="230"><!-- react-text: 231 --> – <!-- /react-text --><a href="#Builder-clearWhere" data-reactid="232">clearWhere</a></li><li data-reactid="233"><!-- react-text: 234 --> – <!-- /react-text --><a href="#Builder-clearOrder" data-reactid="235">clearOrder</a></li><li data-reactid="236"><!-- react-text: 237 --> – <!-- /react-text --><a href="#Builder-clearHaving" data-reactid="238">clearHaving</a></li><li data-reactid="239"><!-- react-text: 240 --> – <!-- /react-text --><a href="#Builder-clearCounters" data-reactid="241">clearCounters</a></li><li data-reactid="242"><!-- react-text: 243 -->– <!-- /react-text --><a href="#Builder-distinct" data-reactid="244">distinct</a></li><li data-reactid="245"><!-- react-text: 246 -->– <!-- /react-text --><a href="#Builder-groupBy" data-reactid="247">groupBy</a></li><li data-reactid="248"><!-- react-text: 249 -->– <!-- /react-text --><a href="#Builder-groupByRaw" data-reactid="250">groupByRaw</a></li><li data-reactid="251"><!-- react-text: 252 -->– <!-- /react-text --><a href="#Builder-orderBy" data-reactid="253">orderBy</a></li><li data-reactid="254"><!-- react-text: 255 -->– <!-- /react-text --><a href="#Builder-orderByRaw" data-reactid="256">orderByRaw</a></li><li data-reactid="257"><!-- react-text: 258 -->– <!-- /react-text --><a href="#Builder-offset" data-reactid="259">offset</a></li><li data-reactid="260"><!-- react-text: 261 -->– <!-- /react-text --><a href="#Builder-limit" data-reactid="262">limit</a></li><li data-reactid="263"><!-- react-text: 264 -->– <!-- /react-text --><a href="#Builder-union" data-reactid="265">union</a></li><li data-reactid="266"><!-- react-text: 267 -->– <!-- /react-text --><a href="#Builder-unionAll" data-reactid="268">unionAll</a></li><li data-reactid="269"><!-- react-text: 270 -->– <!-- /react-text --><a href="#Builder-insert" data-reactid="271">insert</a></li><li data-reactid="272"><!-- react-text: 273 -->– <!-- /react-text --><a href="#Builder-returning" data-reactid="274">returning</a></li><li data-reactid="275"><!-- react-text: 276 -->– <!-- /react-text --><a href="#Builder-update" data-reactid="277">update</a></li><li data-reactid="278"><!-- react-text: 279 -->– <!-- /react-text --><a href="#Builder-del / delete" data-reactid="280">del / delete</a></li><li data-reactid="281"><!-- react-text: 282 -->– <!-- /react-text --><a href="#Builder-transacting" data-reactid="283">transacting</a></li><li data-reactid="284"><!-- react-text: 285 --> – <!-- /react-text --><a href="#Builder-forUpdate" data-reactid="286">forUpdate</a></li><li data-reactid="287"><!-- react-text: 288 --> – <!-- /react-text --><a href="#Builder-forShare" data-reactid="289">forShare</a></li><li data-reactid="290"><!-- react-text: 291 -->– <!-- /react-text --><a href="#Builder-skipLocked" data-reactid="292">skipLocked</a></li><li data-reactid="293"><!-- react-text: 294 -->– <!-- /react-text --><a href="#Builder-noWait" data-reactid="295">noWait</a></li><li data-reactid="296"><!-- react-text: 297 -->– <!-- /react-text --><a href="#Builder-count" data-reactid="298">count</a></li><li data-reactid="299"><!-- react-text: 300 -->– <!-- /react-text --><a href="#Builder-min" data-reactid="301">min</a></li><li data-reactid="302"><!-- react-text: 303 -->– <!-- /react-text --><a href="#Builder-max" data-reactid="304">max</a></li><li data-reactid="305"><!-- react-text: 306 -->– <!-- /react-text --><a href="#Builder-sum" data-reactid="307">sum</a></li><li data-reactid="308"><!-- react-text: 309 -->– <!-- /react-text --><a href="#Builder-avg" data-reactid="310">avg</a></li><li data-reactid="311"><!-- react-text: 312 -->– <!-- /react-text --><a href="#Builder-increment" data-reactid="313">increment</a></li><li data-reactid="314"><!-- react-text: 315 -->– <!-- /react-text --><a href="#Builder-decrement" data-reactid="316">decrement</a></li><li data-reactid="317"><!-- react-text: 318 -->– <!-- /react-text --><a href="#Builder-truncate" data-reactid="319">truncate</a></li><li data-reactid="320"><!-- react-text: 321 -->– <!-- /react-text --><a href="#Builder-pluck" data-reactid="322">pluck</a></li><li data-reactid="323"><!-- react-text: 324 -->– <!-- /react-text --><a href="#Builder-first" data-reactid="325">first</a></li><li data-reactid="326"><!-- react-text: 327 -->– <!-- /react-text --><a href="#Builder-clone" data-reactid="328">clone</a></li><li data-reactid="329"><!-- react-text: 330 -->– <!-- /react-text --><a href="#Builder-modify" data-reactid="331">modify</a></li><li data-reactid="332"><!-- react-text: 333 -->– <!-- /react-text --><a href="#Builder-columnInfo" data-reactid="334">columnInfo</a></li><li data-reactid="335"><!-- react-text: 336 -->– <!-- /react-text --><a href="#Builder-debug" data-reactid="337">debug</a></li><li data-reactid="338"><!-- react-text: 339 -->– <!-- /react-text --><a href="#Builder-connection" data-reactid="340">connection</a></li><li data-reactid="341"><!-- react-text: 342 -->– <!-- /react-text --><a href="#Builder-options" data-reactid="343">options</a></li><li data-reactid="344"><!-- react-text: 345 -->- <!-- /react-text --><a href="#Builder-queryContext" data-reactid="346">queryContext</a></li></ul><a class="toc_title" href="#Transactions" data-reactid="347">Transactions</a><ul class="toc_section" data-reactid="348"><li data-reactid="349"><!-- react-text: 350 -->– <!-- /react-text --><a href="#Transactions" data-reactid="351"><b data-reactid="352">overview</b></a></li></ul><a class="toc_title" href="#Schema" data-reactid="353">Schema Builder</a><ul class="toc_section" data-reactid="354"><li data-reactid="355"><!-- react-text: 356 -->– <!-- /react-text --><a href="#Schema-with" data-reactid="357">with</a></li><li data-reactid="358"><!-- react-text: 359 -->– <!-- /react-text --><a href="#Schema-withSchema" data-reactid="360">withSchema</a></li><li data-reactid="361"><!-- react-text: 362 -->– <!-- /react-text --><a href="#Schema-createTable" data-reactid="363">createTable</a></li><li data-reactid="364"><!-- react-text: 365 -->– <!-- /react-text --><a href="#Schema-renameTable" data-reactid="366">renameTable</a></li><li data-reactid="367"><!-- react-text: 368 -->– <!-- /react-text --><a href="#Schema-dropTable" data-reactid="369">dropTable</a></li><li data-reactid="370"><!-- react-text: 371 -->– <!-- /react-text --><a href="#Schema-hasColumn" data-reactid="372">hasColumn</a></li><li data-reactid="373"><!-- react-text: 374 -->– <!-- /react-text --><a href="#Schema-hasTable" data-reactid="375">hasTable</a></li><li data-reactid="376"><!-- react-text: 377 -->– <!-- /react-text --><a href="#Schema-dropTableIfExists" data-reactid="378">dropTableIfExists</a></li><li data-reactid="379"><!-- react-text: 380 -->– <!-- /react-text --><a href="#Schema-table" data-reactid="381">table</a></li><li data-reactid="382"><!-- react-text: 383 -->– <!-- /react-text --><a href="#Schema-raw" data-reactid="384">raw</a></li><li data-reactid="385"><!-- react-text: 386 -->– <!-- /react-text --><a href="#Schema-queryContext" data-reactid="387">queryContext</a></li><li data-reactid="388"><b data-reactid="389"><a href="#Schema-Building" data-reactid="390">Schema Building:</a></b></li><li data-reactid="391"><!-- react-text: 392 -->– <!-- /react-text --><a href="#Schema-dropColumn" data-reactid="393">dropColumn</a></li><li data-reactid="394"><!-- react-text: 395 -->– <!-- /react-text --><a href="#Schema-dropColumns" data-reactid="396">dropColumns</a></li><li data-reactid="397"><!-- react-text: 398 -->– <!-- /react-text --><a href="#Schema-renameColumn" data-reactid="399">renameColumn</a></li><li data-reactid="400"><!-- react-text: 401 -->– <!-- /react-text --><a href="#Schema-increments" data-reactid="402">increments</a></li><li data-reactid="403"><!-- react-text: 404 -->– <!-- /react-text --><a href="#Schema-integer" data-reactid="405">integer</a></li><li data-reactid="406"><!-- react-text: 407 -->– <!-- /react-text --><a href="#Schema-bigInteger" data-reactid="408">bigInteger</a></li><li data-reactid="409"><!-- react-text: 410 -->– <!-- /react-text --><a href="#Schema-text" data-reactid="411">text</a></li><li data-reactid="412"><!-- react-text: 413 -->– <!-- /react-text --><a href="#Schema-string" data-reactid="414">string</a></li><li data-reactid="415"><!-- react-text: 416 -->– <!-- /react-text --><a href="#Schema-float" data-reactid="417">float</a></li><li data-reactid="418"><!-- react-text: 419 -->– <!-- /react-text --><a href="#Schema-decimal" data-reactid="420">decimal</a></li><li data-reactid="421"><!-- react-text: 422 -->– <!-- /react-text --><a href="#Schema-boolean" data-reactid="423">boolean</a></li><li data-reactid="424"><!-- react-text: 425 -->– <!-- /react-text --><a href="#Schema-date" data-reactid="426">date</a></li><li data-reactid="427"><!-- react-text: 428 -->– <!-- /react-text --><a href="#Schema-datetime" data-reactid="429">datetime</a></li><li data-reactid="430"><!-- react-text: 431 -->– <!-- /react-text --><a href="#Schema-time" data-reactid="432">time</a></li><li data-reactid="433"><!-- react-text: 434 -->– <!-- /react-text --><a href="#Schema-timestamp" data-reactid="435">timestamp</a></li><li data-reactid="436"><!-- react-text: 437 -->– <!-- /react-text --><a href="#Schema-timestamps" data-reactid="438">timestamps</a></li><li data-reactid="439"><!-- react-text: 440 -->– <!-- /react-text --><a href="#Schema-dropTimestamps" data-reactid="441">dropTimestamps</a></li><li data-reactid="442"><!-- react-text: 443 -->– <!-- /react-text --><a href="#Schema-binary" data-reactid="444">binary</a></li><li data-reactid="445"><!-- react-text: 446 -->– <!-- /react-text --><a href="#Schema-enum" data-reactid="447">enum / enu</a></li><li data-reactid="448"><!-- react-text: 449 -->– <!-- /react-text --><a href="#Schema-json" data-reactid="450">json</a></li><li data-reactid="451"><!-- react-text: 452 -->– <!-- /react-text --><a href="#Schema-jsonb" data-reactid="453">jsonb</a></li><li data-reactid="454"><!-- react-text: 455 -->– <!-- /react-text --><a href="#Schema-uuid" data-reactid="456">uuid</a></li><li data-reactid="457"><!-- react-text: 458 -->– <!-- /react-text --><a href="#Schema-comment" data-reactid="459">comment</a></li><li data-reactid="460"><!-- react-text: 461 -->– <!-- /react-text --><a href="#Schema-engine" data-reactid="462">engine</a></li><li data-reactid="463"><!-- react-text: 464 -->– <!-- /react-text --><a href="#Schema-charset" data-reactid="465">charset</a></li><li data-reactid="466"><!-- react-text: 467 -->– <!-- /react-text --><a href="#Schema-collate" data-reactid="468">collate</a></li><li data-reactid="469"><!-- react-text: 470 -->– <!-- /react-text --><a href="#Schema-inherits" data-reactid="471">inherits</a></li><li data-reactid="472"><!-- react-text: 473 -->– <!-- /react-text --><a href="#Schema-specificType" data-reactid="474">specificType</a></li><li data-reactid="475"><!-- react-text: 476 -->– <!-- /react-text --><a href="#Schema-index" data-reactid="477">index</a></li><li data-reactid="478"><!-- react-text: 479 -->– <!-- /react-text --><a href="#Schema-dropIndex" data-reactid="480">dropIndex</a></li><li data-reactid="481"><!-- react-text: 482 -->– <!-- /react-text --><a href="#Schema-unique" data-reactid="483">unique</a></li><li data-reactid="484"><!-- react-text: 485 -->– <!-- /react-text --><a href="#Schema-foreign" data-reactid="486">foreign</a></li><li data-reactid="487"><!-- react-text: 488 -->– <!-- /react-text --><a href="#Schema-dropForeign" data-reactid="489">dropForeign</a></li><li data-reactid="490"><!-- react-text: 491 -->– <!-- /react-text --><a href="#Schema-dropUnique" data-reactid="492">dropUnique</a></li><li data-reactid="493"><!-- react-text: 494 -->– <!-- /react-text --><a href="#Schema-dropPrimary" data-reactid="495">dropPrimary</a></li><li data-reactid="496"><!-- react-text: 497 -->– <!-- /react-text --><a href="#Schema-table-queryContext" data-reactid="498">queryContext</a></li><li data-reactid="499"><a href="#Chainable" data-reactid="500"><b data-reactid="501">Chainable:</b></a></li><li data-reactid="502"><!-- react-text: 503 -->– <!-- /react-text --><a href="#Schema-alter" data-reactid="504">alter</a></li><li data-reactid="505"><!-- react-text: 506 -->– <!-- /react-text --><a href="#Schema-index" data-reactid="507">index</a></li><li data-reactid="508"><!-- react-text: 509 -->– <!-- /react-text --><a href="#Schema-primary" data-reactid="510">primary</a></li><li data-reactid="511"><!-- react-text: 512 -->– <!-- /react-text --><a href="#Schema-unique" data-reactid="513">unique</a></li><li data-reactid="514"><!-- react-text: 515 -->– <!-- /react-text --><a href="#Schema-references" data-reactid="516">references</a></li><li data-reactid="517"><!-- react-text: 518 -->– <!-- /react-text --><a href="#Schema-inTable" data-reactid="519">inTable</a></li><li data-reactid="520"><!-- react-text: 521 -->– <!-- /react-text --><a href="#Schema-onDelete" data-reactid="522">onDelete</a></li><li data-reactid="523"><!-- react-text: 524 -->– <!-- /react-text --><a href="#Schema-onUpdate" data-reactid="525">onUpdate</a></li><li data-reactid="526"><!-- react-text: 527 -->– <!-- /react-text --><a href="#Schema-defaultTo" data-reactid="528">defaultTo</a></li><li data-reactid="529"><!-- react-text: 530 -->– <!-- /react-text --><a href="#Schema-unsigned" data-reactid="531">unsigned</a></li><li data-reactid="532"><!-- react-text: 533 -->– <!-- /react-text --><a href="#Schema-notNullable" data-reactid="534">notNullable</a></li><li data-reactid="535"><!-- react-text: 536 -->– <!-- /react-text --><a href="#Schema-nullable" data-reactid="537">nullable</a></li><li data-reactid="538"><!-- react-text: 539 -->– <!-- /react-text --><a href="#Schema-first" data-reactid="540">first</a></li><li data-reactid="541"><!-- react-text: 542 -->– <!-- /react-text --><a href="#Schema-after" data-reactid="543">after</a></li><li data-reactid="544"><!-- react-text: 545 -->– <!-- /react-text --><a href="#Column-comment" data-reactid="546">comment</a></li><li data-reactid="547"><!-- react-text: 548 -->– <!-- /react-text --><a href="#Column-collate" data-reactid="549">collate</a></li></ul><a class="toc_title" href="#Raw" data-reactid="550">Raw</a><ul class="toc_section" data-reactid="551"><li data-reactid="552"><!-- react-text: 553 -->– <!-- /react-text --><a href="#Raw-Bindings" data-reactid="554">Raw Parameter Binding</a></li><li data-reactid="555"><!-- react-text: 556 -->– <!-- /react-text --><a href="#Raw-Expressions" data-reactid="557">Raw Expressions</a></li><li data-reactid="558"><!-- react-text: 559 -->– <!-- /react-text --><a href="#Raw-Queries" data-reactid="560">Raw Queries</a></li><li data-reactid="561"><!-- react-text: 562 -->- <!-- /react-text --><a href="#Raw-queries-wrapped" data-reactid="563">Wrapped Queries</a></li></ul><a class="toc_title" href="#Ref" data-reactid="564">Ref</a><ul class="toc_section" data-reactid="565"><li data-reactid="566"><!-- react-text: 567 -->– <!-- /react-text --><a href="#Ref-Usage" data-reactid="568">Usage</a></li><li data-reactid="569"><!-- react-text: 570 -->– <!-- /react-text --><a href="#Ref-withSchema" data-reactid="571">withSchema</a></li><li data-reactid="572"><!-- react-text: 573 -->– <!-- /react-text --><a href="#Ref-alias" data-reactid="574">alias</a></li></ul><a class="toc_title" href="#Utility" data-reactid="575">Utility</a><ul class="toc_section" data-reactid="576"><li data-reactid="577"><!-- react-text: 578 -->- <!-- /react-text --><a href="#Utility-BatchInsert" data-reactid="579">Batch Insert</a></li></ul><a class="toc_title" href="#Interfaces" data-reactid="580">Interfaces</a><ul class="toc_section" data-reactid="581"><li data-reactid="582"><b data-reactid="583"><a href="#Interfaces-Promises" data-reactid="584">Promises</a></b></li><li data-reactid="585"><!-- react-text: 586 --> – <!-- /react-text --><a href="#Interfaces-then" data-reactid="587">then</a></li><li data-reactid="588"><!-- react-text: 589 --> – <!-- /react-text --><a href="#Interfaces-catch" data-reactid="590">catch</a></li><li data-reactid="591"><!-- react-text: 592 --> – <!-- /react-text --><a href="#Interfaces-return" data-reactid="593">return</a></li><li data-reactid="594"><b data-reactid="595"><a href="#Interfaces-Callbacks" data-reactid="596">Callbacks</a></b></li><li data-reactid="597"><!-- react-text: 598 --> – <!-- /react-text --><a href="#Interfaces-asCallback" data-reactid="599">asCallback</a></li><li data-reactid="600"><b data-reactid="601"><a href="#Interfaces-Streams" data-reactid="602">Streams</a></b></li><li data-reactid="603"><!-- react-text: 604 --> – <!-- /react-text --><a href="#Interfaces-stream" data-reactid="605">stream</a></li><li data-reactid="606"><!-- react-text: 607 --> – <!-- /react-text --><a href="#Interfaces-pipe" data-reactid="608">pipe</a></li><li data-reactid="609"><b data-reactid="610"><a href="#Interfaces-Events" data-reactid="611">Events</a></b></li><li data-reactid="612"><!-- react-text: 613 --> – <!-- /react-text --><a href="#Interfaces-query" data-reactid="614">query</a></li><li data-reactid="615"><!-- react-text: 616 --> – <!-- /react-text --><a href="#Interfaces-query-error" data-reactid="617">query-error</a></li><li data-reactid="618"><!-- react-text: 619 --> – <!-- /react-text --><a href="#Interfaces-query-response" data-reactid="620">query-response</a></li><li data-reactid="621"><b data-reactid="622"><a href="#Interfaces-Other" data-reactid="623">Other:</a></b></li><li data-reactid="624"><!-- react-text: 625 --> – <!-- /react-text --><a href="#Interfaces-toString" data-reactid="626">toString</a></li><li data-reactid="627"><!-- react-text: 628 --> – <!-- /react-text --><a href="#Interfaces-toSQL" data-reactid="629">toSQL</a></li><li data-reactid="630"><!-- react-text: 631 --> – <!-- /react-text --><a href="#Interfaces-toSQL" data-reactid="632">toSQL().toNative()</a></li></ul><a class="toc_title" href="#Migrations" data-reactid="633">Migrations</a><ul class="toc_section" data-reactid="634"><li data-reactid="635"><a href="#Migrations-CLI" data-reactid="636"><b data-reactid="637">CLI</b></a></li><li data-reactid="638"><!-- react-text: 639 -->– <!-- /react-text --><a href="#Migrations-CLI" data-reactid="640">Migrations</a></li><li data-reactid="641"><!-- react-text: 642 -->– <!-- /react-text --><a href="#Seeds-CLI" data-reactid="643">Seed files</a></li><li data-reactid="644"><!-- react-text: 645 -->– <!-- /react-text --><a href="#knexfile" data-reactid="646">knexfile.js</a></li><li data-reactid="647"><a href="#Migrations-API" data-reactid="648"><b data-reactid="649">Migration API</b></a></li><li data-reactid="650"><!-- react-text: 651 -->– <!-- /react-text --><a href="#Migrations-make" data-reactid="652">make</a></li><li data-reactid="653"><!-- react-text: 654 -->– <!-- /react-text --><a href="#Migrations-latest" data-reactid="655">latest</a></li><li data-reactid="656"><!-- react-text: 657 -->– <!-- /react-text --><a href="#Migrations-rollback" data-reactid="658">rollback</a></li><ii data-reactid="659"><!-- react-text: 660 -->- <!-- /react-text --><a href="#Migrations-up" data-reactid="661">up</a></ii><ii data-reactid="662"><!-- react-text: 663 -->- <!-- /react-text --><a href="#Migrations-down" data-reactid="664">down</a></ii><li data-reactid="665"><!-- react-text: 666 -->– <!-- /react-text --><a href="#Migrations-currentVersion" data-reactid="667">currentVersion</a></li><li data-reactid="668"><!-- react-text: 669 -->– <!-- /react-text --><a href="#Migrations-list" data-reactid="670">list</a></li><li data-reactid="671"><a href="#Notes-about-locks" data-reactid="672"><b data-reactid="673">Notes about locks</b></a></li><li data-reactid="674"><a href="#Seeds-API" data-reactid="675"><b data-reactid="676">Seed API</b></a></li><li data-reactid="677"><!-- react-text: 678 -->– <!-- /react-text --><a href="#Seeds-make" data-reactid="679">make</a></li><li data-reactid="680"><!-- react-text: 681 -->– <!-- /react-text --><a href="#Seeds-run" data-reactid="682">run</a></li></ul><a class="toc_title" href="#support" data-reactid="683">Support</a><a class="toc_title" href="#faq" data-reactid="684">F.A.Q.</a><a class="toc_title" href="#changelog" data-reactid="685">Change Log</a></div><div class="language" data-reactid="686"><!-- react-text: 687 -->Show example query output as:<!-- /react-text --><br data-reactid="688"/><select data-reactid="689"><option selected="" value="mysql" data-reactid="690">MySQL / MariaDB</option><option value="pg" data-reactid="691">PostgreSQL</option><option value="redshift" data-reactid="692">Amazon Redshift</option><option value="sqlite3" data-reactid="693">SQLite3</option><option value="oracle" data-reactid="694">Oracle</option><option value="mssql" data-reactid="695">MSSQL</option></select></div><a href="https://github.com/tgriesser/knex" data-reactid="696"><img style="position:fixed;top:0;right:0;border:0;" src="assets/images/github.png" alt="Fork me on GitHub" data-reactid="697"/></a><div class="container" data-reactid="698"><div id="Prelude" data-reactid="699"><div data-reactid="700"><p data-reactid="701"><img height="108" id="logo" src="assets/images/knex.png" alt="Knex.js" /></p><p data-reactid="702"><strong>Knex.js</strong> is a "batteries included" SQL query builder for <strong>Postgres</strong>, <strong>MSSQL</strong>, <strong>MySQL</strong>, <strong>MariaDB</strong>, <strong>SQLite3</strong>, <strong>Oracle</strong>, and <strong>Amazon Redshift</strong> designed to be flexible, portable, and fun to use. It features both traditional node style <a href="#Interfaces-Callbacks">callbacks</a> as well as a <a href="#Interfaces-Promises">promise</a> interface for cleaner async flow control, <a href="#Interfaces-Streams">a stream interface</a>, full featured <a href="#Builder">query</a> and <a href="#Schema">schema</a> builders, <a href="#Transactions"><strong>transaction support (with savepoints)</strong></a>, connection <a href="#Installation-pooling">pooling</a> and standardized responses between different query clients and dialects.</p><p data-reactid="703">The project is <a href="http://github.com/knex/knex">hosted on GitHub</a>, and has a comprehensive <a href="https://travis-ci.org/knex/knex">test suite</a>.</p><p data-reactid="704">Knex is available for use under the <a href="http://github.com/knex/knex/blob/master/LICENSE">MIT software license</a>.</p><p data-reactid="705">You can report bugs and discuss features on the <a href="http://github.com/knex/knex/issues">GitHub issues page</a>, add pages to the <a href="https://github.com/knex/knex/wiki">wiki</a> or send tweets to <a href="http://twitter.com/tgriesser">@tgriesser</a>.</p><p data-reactid="706">Thanks to all of the great <a href="https://github.com/knex/knex/graphs/contributors">contributions</a> to the project.</p></div><p class="info" data-reactid="707">Special thanks to <a href="https://twitter.com/taylorotwell">Taylor Otwell</a> and his work on the <a href="http://laravel.com/docs/queries">Laravel Query Builder</a>, from which much of the builder's code and syntax was originally derived.</p><h2 data-reactid="708">Latest Release: 0.20.0 - <span class="small"><a href="#changelog">Change Log</a></span></h2><p data-reactid="709">Current Develop — <a href="https://travis-ci.org/knex/knex"><img src="https://travis-ci.org/knex/knex.png?branch=master" alt="Travis Badge"></a></p></div><div id="Upgrading" data-reactid="710"></div><div id="Installation" data-reactid="711"><h2 id="Installation" data-reactid="712">Installation</h2><p data-reactid="713">Knex can be used as an SQL query builder in both Node.JS and the browser, limited to WebSQL's constraints (like the inability to drop tables or read schemas). Composing SQL queries in the browser for execution on the server is highly discouraged, as this can be the cause of serious security vulnerabilities. The browser builds outside of WebSQL are primarily for learning purposes - for example, you can pop open the console and build queries on this page using the <a href="javascript:alert(knex)">knex</a> object.</p><h3 id="Installation-node" data-reactid="714">Node.js</h3><p data-reactid="715">The primary target environment for Knex is Node.js, you will need to install the <code>knex</code> library, and then install the appropriate database library: <a href="https://github.com/brianc/node-postgres"><code>pg</code></a> for PostgreSQL and Amazon Redshift, <a href="https://github.com/felixge/node-mysql"><code>mysql</code></a> for MySQL or MariaDB, <a href="https://github.com/mapbox/node-sqlite3"><code>sqlite3</code></a> for SQLite3, or <a href="https://github.com/patriksimek/node-mssql"><code>mssql</code></a> for MSSQL.</p><pre data-reactid="716"><code data-reactid="717">$ npm install knex --save
# Then add one of the following (adding a --save) flag:
$ npm install pg
$ npm install sqlite3
$ npm install mysql
$ npm install mysql2
$ npm install oracledb
$ npm install mssql</code></pre><p data-reactid="718"><em>If you want to use a MariaDB instance, you can use the <code>mysql</code> driver.</em></p><h3 id="Installation-browser" data-reactid="719">Browser</h3><p data-reactid="720">Knex can be built using a JavaScript build tool such as <a href="http://browserify.org/">browserify</a> or <a href="https://github.com/webpack/webpack">webpack</a>. In fact, this documentation uses a webpack build which <a href="https://github.com/knex/documentation/blob/a4de1b2eb50d6699f126be8d134f3d1acc4fc69d/components/Container.jsx#L3">includes knex</a>. View source on this page to see the browser build in-action (the global <code>knex</code> variable).</p><h3 id="Installation-client" data-reactid="721">Initializing the Library</h3><p data-reactid="722">The <code>knex</code> module is itself a function which takes a configuration object for Knex, accepting a few parameters. The <code>client</code> parameter is required and determines which client adapter will be used with the library.</p><pre data-reactid="723"><code class="hljs js" data-reactid="724"><span class="hljs-keyword">var</span> knex = <span class="hljs-built_in">require</span>(<span class="hljs-string">'knex'</span>)({
<span class="hljs-attr">client</span>: <span class="hljs-string">'mysql'</span>,
<span class="hljs-attr">connection</span>: {
<span class="hljs-attr">host</span> : <span class="hljs-string">'127.0.0.1'</span>,
<span class="hljs-attr">user</span> : <span class="hljs-string">'your_database_user'</span>,
<span class="hljs-attr">password</span> : <span class="hljs-string">'your_database_password'</span>,
<span class="hljs-attr">database</span> : <span class="hljs-string">'myapp_test'</span>
}
});</code></pre><p data-reactid="725">The connection options are passed directly to the appropriate database client to create the connection, and may be either an object, or a connection string:</p><p class="info" data-reactid="726">Note: Knex's PostgreSQL client allows you to set the initial search path for each connection automatically using an additional option "searchPath" as shown below.</p><pre data-reactid="727"><code class="hljs js" data-reactid="728"><span class="hljs-keyword">var</span> pg = <span class="hljs-built_in">require</span>(<span class="hljs-string">'knex'</span>)({
<span class="hljs-attr">client</span>: <span class="hljs-string">'pg'</span>,
<span class="hljs-attr">connection</span>: process.env.PG_CONNECTION_STRING,
<span class="hljs-attr">searchPath</span>: [<span class="hljs-string">'knex'</span>, <span class="hljs-string">'public'</span>],
});</code></pre><p class="info" data-reactid="729">Note: When you use the SQLite3 adapter, there is a filename required, not a network connection. For example:</p><pre data-reactid="730"><code class="hljs js" data-reactid="731"><span class="hljs-keyword">var</span> knex = <span class="hljs-built_in">require</span>(<span class="hljs-string">'knex'</span>)({
<span class="hljs-attr">client</span>: <span class="hljs-string">'sqlite3'</span>,
<span class="hljs-attr">connection</span>: {
<span class="hljs-attr">filename</span>: <span class="hljs-string">"./mydb.sqlite"</span>
}
});</code></pre><p class="info" data-reactid="732">Note: The database version can be added in knex configuration, when you use the PostgreSQL adapter to connect a non-standard database.</p><pre data-reactid="733"><code class="hljs js" data-reactid="734"><span class="hljs-keyword">var</span> knex = <span class="hljs-built_in">require</span>(<span class="hljs-string">'knex'</span>)({
<span class="hljs-attr">client</span>: <span class="hljs-string">'pg'</span>,
<span class="hljs-attr">version</span>: <span class="hljs-string">'7.2'</span>,
<span class="hljs-attr">connection</span>: {
<span class="hljs-attr">host</span> : <span class="hljs-string">'127.0.0.1'</span>,
<span class="hljs-attr">user</span> : <span class="hljs-string">'your_database_user'</span>,
<span class="hljs-attr">password</span> : <span class="hljs-string">'your_database_password'</span>,
<span class="hljs-attr">database</span> : <span class="hljs-string">'myapp_test'</span>
}
});</code></pre><pre data-reactid="735"><code class="hljs js" data-reactid="736"><span class="hljs-keyword">var</span> knex = <span class="hljs-built_in">require</span>(<span class="hljs-string">'knex'</span>)({
<span class="hljs-attr">client</span>: <span class="hljs-string">'mysql'</span>,
<span class="hljs-attr">version</span>: <span class="hljs-string">'5.7'</span>,
<span class="hljs-attr">connection</span>: {
<span class="hljs-attr">host</span> : <span class="hljs-string">'127.0.0.1'</span>,
<span class="hljs-attr">user</span> : <span class="hljs-string">'your_database_user'</span>,
<span class="hljs-attr">password</span> : <span class="hljs-string">'your_database_password'</span>,
<span class="hljs-attr">database</span> : <span class="hljs-string">'myapp_test'</span>
}
});</code></pre><p data-reactid="737">You can also connect via an unix domain socket, which will ignore host and port.</p><pre data-reactid="738"><code class="hljs js" data-reactid="739"><span class="hljs-keyword">var</span> knex = <span class="hljs-built_in">require</span>(<span class="hljs-string">'knex'</span>)({
<span class="hljs-attr">client</span>: <span class="hljs-string">'mysql'</span>,
<span class="hljs-attr">connection</span>: {
<span class="hljs-attr">socketPath</span> : <span class="hljs-string">'/path/to/socket.sock'</span>,
<span class="hljs-attr">user</span> : <span class="hljs-string">'your_database_user'</span>,
<span class="hljs-attr">password</span> : <span class="hljs-string">'your_database_password'</span>,
<span class="hljs-attr">database</span> : <span class="hljs-string">'myapp_test'</span>
}
});</code></pre><p data-reactid="740"><code>userParams</code> is an optional parameter that allows you to pass arbitrary parameters which will be accessible via <code>knex.userParams</code> property:</p><pre data-reactid="741"><code class="hljs js" data-reactid="742"><span class="hljs-keyword">var</span> knex = <span class="hljs-built_in">require</span>(<span class="hljs-string">'knex'</span>)({
<span class="hljs-attr">client</span>: <span class="hljs-string">'mysql'</span>,
<span class="hljs-attr">connection</span>: {
<span class="hljs-attr">host</span> : <span class="hljs-string">'127.0.0.1'</span>,
<span class="hljs-attr">user</span> : <span class="hljs-string">'your_database_user'</span>,
<span class="hljs-attr">password</span> : <span class="hljs-string">'your_database_password'</span>,
<span class="hljs-attr">database</span> : <span class="hljs-string">'myapp_test'</span>
},
<span class="hljs-attr">userParams</span>: {
<span class="hljs-attr">userParam1</span>: <span class="hljs-string">'451'</span>
}
});</code></pre><p class="info" data-reactid="743">Initializing the library should normally only ever happen once in your application, as it creates a connection pool for the current database, you should use the instance returned from the initialize call throughout your library.</p><p data-reactid="744">Specify the client for the particular flavour of SQL you are interested in.</p><pre data-reactid="745"><code class="hljs js" data-reactid="746"><span class="hljs-keyword">var</span> pg = <span class="hljs-built_in">require</span>(<span class="hljs-string">'knex'</span>)({<span class="hljs-attr">client</span>: <span class="hljs-string">'pg'</span>});
knex(<span class="hljs-string">'table'</span>).insert({<span class="hljs-attr">a</span>: <span class="hljs-string">'b'</span>}).returning(<span class="hljs-string">'*'</span>).toString();
<span class="hljs-comment">// "insert into "table" ("a") values ('b')"</span>
pg(<span class="hljs-string">'table'</span>).insert({<span class="hljs-attr">a</span>: <span class="hljs-string">'b'</span>}).returning(<span class="hljs-string">'*'</span>).toString();
<span class="hljs-comment">// "insert into "table" ("a") values ('b') returning *"</span></code></pre><h3 id="Installation-parametrization" data-reactid="747">Getting parametrized instance</h3><p data-reactid="748">You can call method <code>withUserParams</code> on a Knex instance if you want to get a copy (with same connections) with custom parameters (e. g. to execute same migrations with different parameters)</p><pre data-reactid="749"><code class="hljs js" data-reactid="750"><span class="hljs-keyword">var</span> knex = <span class="hljs-built_in">require</span>(<span class="hljs-string">'knex'</span>)({
<span class="hljs-comment">// Params</span>
});
<span class="hljs-keyword">var</span> knexWithParams = knex.withUserParams({<span class="hljs-attr">customUserParam</span>: <span class="hljs-string">'table1'</span>});
<span class="hljs-keyword">var</span> customUserParam = knexWithParams.userParams.customUserParam;</code></pre><h3 id="Installation-debug" data-reactid="751">Debugging</h3><p data-reactid="752">Passing a <code>debug: true</code> flag on your initialization object will turn on <a href="#Builder-debug">debugging</a> for all queries.</p><h3 id="Installation-asyncStackTraces" data-reactid="753">asyncStackTraces</h3><p data-reactid="754">Passing an <code>asyncStackTraces: true</code> flag on your initialization object will turn on stack trace capture for all query builders, raw queries and schema builders. When a DB driver returns an error, this previously captured stack trace is thrown instead of a new one. This helps to mitigate default behaviour of <code>await</code> in node.js/V8 which blows the stack away.
This has small performance overhead, so it is advised to use only for development. Turned off by default.</p><h3 id="Installation-pooling" data-reactid="755">Pooling</h3><div data-reactid="756"><p data-reactid="757">The client created by the configuration initializes a connection pool, using the <a href="https://github.com/vincit/tarn.js">tarn.js</a> library. This connection pool has a default setting of a <code>min: 2, max: 10</code> for the MySQL and PG libraries, and a single connection for sqlite3 (due to issues with utilizing multiple connections on a single file). To change the config settings for the pool, pass a <code>pool</code> option as one of the keys in the initialize block.</p><p data-reactid="758">Checkout the <a href="https://github.com/vincit/tarn.js">tarn.js</a> library for more information.</p></div><pre data-reactid="759"><code class="hljs js" data-reactid="760"><span class="hljs-keyword">var</span> knex = <span class="hljs-built_in">require</span>(<span class="hljs-string">'knex'</span>)({
<span class="hljs-attr">client</span>: <span class="hljs-string">'mysql'</span>,
<span class="hljs-attr">connection</span>: {
<span class="hljs-attr">host</span> : <span class="hljs-string">'127.0.0.1'</span>,
<span class="hljs-attr">user</span> : <span class="hljs-string">'your_database_user'</span>,
<span class="hljs-attr">password</span> : <span class="hljs-string">'your_database_password'</span>,
<span class="hljs-attr">database</span> : <span class="hljs-string">'myapp_test'</span>
},
<span class="hljs-attr">pool</span>: { <span class="hljs-attr">min</span>: <span class="hljs-number">0</span>, <span class="hljs-attr">max</span>: <span class="hljs-number">7</span> }
});</code></pre><p data-reactid="761">If you ever need to explicitly teardown the connection pool, you may use <code>knex.destroy([callback])</code>. You may use <code>knex.destroy</code> by passing a callback, or by chaining as a promise, just not both. To manually initialize a destroyed connection pool, you may use knex.initialize([config]), if no config is passed, it will use the first knex configuration used.</p><h3 id="Installation-pooling-afterCreate" data-reactid="762">afterCreate</h3><p data-reactid="763"><code>afterCreate</code> callback (rawDriverConnection, done) is called when the pool aquires a new connection from the database server. done(err, connection) callback must be called for <code>knex</code> to be able to decide if the connection is ok or if it should be discarded right away from the pool.</p><pre data-reactid="764"><code class="hljs js" data-reactid="765"><span class="hljs-keyword">var</span> knex = <span class="hljs-built_in">require</span>(<span class="hljs-string">'knex'</span>)({
<span class="hljs-attr">client</span>: <span class="hljs-string">'pg'</span>,
<span class="hljs-attr">connection</span>: {...},
<span class="hljs-attr">pool</span>: {
<span class="hljs-attr">afterCreate</span>: <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">conn, done</span>) </span>{
<span class="hljs-comment">// in this example we use pg driver's connection API</span>
conn.query(<span class="hljs-string">'SET timezone="UTC";'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">err</span>) </span>{
<span class="hljs-keyword">if</span> (err) {
<span class="hljs-comment">// first query failed, return error and don't try to make next query</span>
done(err, conn);
} <span class="hljs-keyword">else</span> {
<span class="hljs-comment">// do the second query...</span>
conn.query(<span class="hljs-string">'SELECT set_limit(0.01);'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">err</span>) </span>{
<span class="hljs-comment">// if err is not falsy, connection is discarded from pool</span>
<span class="hljs-comment">// if connection aquire was triggered by a query the error is passed to query promise</span>
done(err, conn);
});
}
});
}
}
});</code></pre><h3 id="Installation-acquireConnectionTimeout" data-reactid="766">acquireConnectionTimeout</h3><p data-reactid="767"><code>acquireConnectionTimeout</code> defaults to 60000ms and is used to determine how long knex should wait before throwing a timeout error when acquiring a connection is not possible. The most common cause for this is using up all the pool for transaction connections and then attempting to run queries outside of transactions while the pool is still full. The error thrown will provide information on the query the connection was for to simplify the job of locating the culprit.</p><pre data-reactid="768"><code class="hljs js" data-reactid="769"><span class="hljs-keyword">var</span> knex = <span class="hljs-built_in">require</span>(<span class="hljs-string">'knex'</span>)({
<span class="hljs-attr">client</span>: <span class="hljs-string">'pg'</span>,
<span class="hljs-attr">connection</span>: {...},
<span class="hljs-attr">pool</span>: {...},
<span class="hljs-attr">acquireConnectionTimeout</span>: <span class="hljs-number">10000</span>
});</code></pre><h3 id="Installation-fetchAsString" data-reactid="770">fetchAsString</h3><p data-reactid="771">Utilized by Oracledb. An array of types. The valid types are 'DATE', 'NUMBER' and 'CLOB'. When any column having one of the specified types is queried, the column data is returned as a string instead of the default representation.</p><pre data-reactid="772"><code class="hljs js" data-reactid="773"><span class="hljs-keyword">var</span> knex = <span class="hljs-built_in">require</span>(<span class="hljs-string">'knex'</span>)({
<span class="hljs-attr">client</span>: <span class="hljs-string">'oracledb'</span>,
<span class="hljs-attr">connection</span>: {...},
<span class="hljs-attr">fetchAsString</span>: [ <span class="hljs-string">'number'</span>, <span class="hljs-string">'clob'</span> ]
});</code></pre><h3 id="Installation-migrations" data-reactid="774">Migrations</h3><p data-reactid="775">For convenience, the any migration configuration may be specified when initializing the library. Read the <a href="#Migrations">Migrations</a> section for more information and a full list of configuration options.</p><pre data-reactid="776"><code class="hljs js" data-reactid="777"><span class="hljs-keyword">var</span> knex = <span class="hljs-built_in">require</span>(<span class="hljs-string">'knex'</span>)({
<span class="hljs-attr">client</span>: <span class="hljs-string">'mysql'</span>,
<span class="hljs-attr">connection</span>: {
<span class="hljs-attr">host</span> : <span class="hljs-string">'127.0.0.1'</span>,
<span class="hljs-attr">user</span> : <span class="hljs-string">'your_database_user'</span>,
<span class="hljs-attr">password</span> : <span class="hljs-string">'your_database_password'</span>,
<span class="hljs-attr">database</span> : <span class="hljs-string">'myapp_test'</span>
},
<span class="hljs-attr">migrations</span>: {
<span class="hljs-attr">tableName</span>: <span class="hljs-string">'migrations'</span>
}
});</code></pre><h3 id="Installation-post-process-response" data-reactid="778">postProcessResponse</h3><p data-reactid="779">Hook for modifying returned rows, before passing them forward to user. One can do for example snake_case -> camelCase conversion for returned columns with this hook. The <code>queryContext</code> is only available if configured for a query builder instance via <a href="#Builder-queryContext">queryContext</a>.</p><pre data-reactid="780"><code class="hljs js" data-reactid="781"><span class="hljs-keyword">var</span> knex = <span class="hljs-built_in">require</span>(<span class="hljs-string">'knex'</span>)({
<span class="hljs-attr">client</span>: <span class="hljs-string">'mysql'</span>,
<span class="hljs-comment">// overly simplified snake_case -> camelCase converter</span>
postProcessResponse: <span class="hljs-function">(<span class="hljs-params">result, queryContext</span>) =></span> {
<span class="hljs-comment">// <span class="hljs-doctag">TODO:</span> add special case for raw results (depends on dialect)</span>
<span class="hljs-keyword">if</span> (<span class="hljs-built_in">Array</span>.isArray(result)) {
<span class="hljs-keyword">return</span> result.map(<span class="hljs-function"><span class="hljs-params">row</span> =></span> convertToCamel(row));
} <span class="hljs-keyword">else</span> {
<span class="hljs-keyword">return</span> convertToCamel(result);
}
}
});</code></pre><h3 id="Installation-wrap-identifier" data-reactid="782">wrapIdentifier</h3><p data-reactid="783">Knex supports transforming identifier names automatically to quoted versions for each dialect. For example <code>'Table.columnName as foo'</code> for PostgreSQL is converted to "Table"."columnName" as "foo".</p><p data-reactid="784">With <code>wrapIdentifier</code> one may override the way how identifiers are transformed. It can be used to override default functionality and for example to help doing <code>camelCase</code> -> <code>snake_case</code> conversion.</p><p data-reactid="785">Conversion function <code>wrapIdentifier(value, dialectImpl, context): string</code> gets each part of the identifier as a single <code>value</code>, the original conversion function from the dialect implementation and the <code>queryContext</code>, which is only available if configured for a query builder instance via <a href="#Builder-queryContext">builder.queryContext</a>, and for schema builder instances via <a href="#Schema-queryContext">schema.queryContext</a> or <a href="#Schema-table-queryContext">table.queryContext</a>. For example, with the query builder, <code>knex('table').withSchema('foo').select('table.field as otherName').where('id', 1)</code> will call <code>wrapIdentifier</code> converter for following values <code>'table'</code>, <code>'foo'</code>, <code>'table'</code>, <code>'field'</code>, <code>'otherName'</code> and <code>'id'</code>.</p><pre data-reactid="786"><code class="hljs js" data-reactid="787"><span class="hljs-keyword">var</span> knex = <span class="hljs-built_in">require</span>(<span class="hljs-string">'knex'</span>)({
<span class="hljs-attr">client</span>: <span class="hljs-string">'mysql'</span>,
<span class="hljs-comment">// overly simplified camelCase -> snake_case converter</span>
wrapIdentifier: <span class="hljs-function">(<span class="hljs-params">value, origImpl, queryContext</span>) =></span> origImpl(convertToSnakeCase(value))
});</code></pre><h3 id="Installation-log" data-reactid="788">log</h3><p data-reactid="789">Knex contains some internal log functions for printing warnings, errors, deprecations, and debug information when applicable. These log functions typically log to the console, but can be overwritten using the log option and providing alternative functions. Different log functions can be used for separate knex instances.</p><pre data-reactid="790"><code class="hljs js" data-reactid="791"><span class="hljs-keyword">var</span> knex = <span class="hljs-built_in">require</span>(<span class="hljs-string">'knex'</span>)({
<span class="hljs-attr">log</span>: {
warn(message) {
},
error(message) {
},
deprecate(message) {
},
debug(message) {
},
}
});</code></pre></div><div id="TypeScript Support" data-reactid="792"><h2 id="typescript-support" data-reactid="793">TypeScript Support</h2><p data-reactid="794">While knex is written in JavaScript, officially supported TypeScript bindings are available (within the knex npm package).</p><p data-reactid="795">However it is to be noted that TypeScript support is currently best-effort. Knex has a very flexible API and not all usage patterns can be type-checked and in most such cases we err on the side of flexibility. In particular, lack of type errors doesn't currently guarantee that the generated queries will be correct and therefore writing tests for them is recommended even if you are using TypeScript.</p><p data-reactid="796">Many of the APIs accept <code>TRecord</code> and <code>TResult</code> type parameters, using which we can specify the type of a row in the database table and the type of the result of the query respectively. This is helpful for auto-completion when using TypeScript-aware editors like VSCode.</p></div><div id="Builder" data-reactid="797"><h2 id="Builder" data-reactid="798">Knex Query Builder</h2><p data-reactid="799">The heart of the library, the knex query builder is the interface used for building and executing standard SQL queries, such as <code>select</code>, <code>insert</code>, <code>update</code>, <code>delete</code>.</p><h3 id="Builder-identifier-syntax" data-reactid="800">Identifier Syntax</h3><div data-reactid="801"><p data-reactid="802">In many places in APIs identifiers like table name or column name can be passed to methods.</p><p data-reactid="803">Most commonly one needs just plain <code>tableName.columnName</code>, <code>tableName</code> or <code>columnName</code>, but in many cases one also needs to pass an alias how that identifier is referred later on in the query.</p><p data-reactid="804">There are two ways to declare an alias for identifier. One can directly give <code>as aliasName</code> suffix for the identifier (e.g. <code>identifierName as aliasName</code>) or one can pass an object <code>{ aliasName: 'identifierName' }</code>.</p><p data-reactid="805">If the object has multiple aliases <code>{ alias1: 'identifier1', alias2: 'identifier2' }</code>, then all the aliased identifiers are expanded to comma separated list.</p><p data-reactid="806">NOTE: identifier syntax has no place for selecting schema, so if you are doing <code>schemaName.tableName</code>, query might be rendered wrong. Use <code>.withSchema('schemaName')</code> instead.</p></div><pre class="display" data-reactid="807"><code class="js hljs" data-reactid="808">knex({ <span class="hljs-attr">a</span>: <span class="hljs-string">'table'</span>, <span class="hljs-attr">b</span>: <span class="hljs-string">'table'</span> })
.select({
<span class="hljs-attr">aTitle</span>: <span class="hljs-string">'a.title'</span>,
<span class="hljs-attr">bTitle</span>: <span class="hljs-string">'b.title'</span>
})
.whereRaw(<span class="hljs-string">'?? = ??'</span>, [<span class="hljs-string">'a.column_1'</span>, <span class="hljs-string">'b.column_2'</span>])</code><br data-reactid="809"/><!-- react-text: 810 -->Outputs:<!-- /react-text --><br data-reactid="811"/><code class="sql hljs" data-reactid="812"><span class="hljs-keyword">select</span> <span class="hljs-string">`a`</span>.<span class="hljs-string">`title`</span> <span class="hljs-keyword">as</span> <span class="hljs-string">`aTitle`</span>, <span class="hljs-string">`b`</span>.<span class="hljs-string">`title`</span> <span class="hljs-keyword">as</span> <span class="hljs-string">`bTitle`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`table`</span> <span class="hljs-keyword">as</span> <span class="hljs-string">`a`</span>, <span class="hljs-string">`table`</span> <span class="hljs-keyword">as</span> <span class="hljs-string">`b`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`a`</span>.<span class="hljs-string">`column_1`</span> = <span class="hljs-string">`b`</span>.<span class="hljs-string">`column_2`</span></code></pre><div id="Builder-knex" data-reactid="813"><b data-reactid="814">knex</b><!-- react-text: 815 --> — <!-- /react-text --><code data-reactid="816">knex(tableName, options={only: boolean}) / knex.[methodName]</code><p data-reactid="817">The query builder starts off either by specifying a tableName you wish to query against, or by calling any method directly on the knex object. This kicks off a jQuery-like chain, with which you can call additional query builder methods as needed to construct the query, eventually calling any of the interface methods, to either convert toString, or execute the query with a promise, callback, or stream. Optional second argument for passing options:* <strong>only</strong>: if <code>true</code>, the ONLY keyword is used before the <code>tableName</code> to discard inheriting tables' data. <strong>NOTE:</strong> only supported in PostgreSQL for now.</p><h3 data-reactid="818">Usage with TypeScript</h3><p data-reactid="819">If using TypeScript, you can pass the type of database row as a type parameter to get better autocompletion support down the chain.</p><pre data-reactid="820"><code class="hljs ts" data-reactid="821"><span class="hljs-keyword">interface</span> User {
id: <span class="hljs-built_in">number</span>;
name: <span class="hljs-built_in">string</span>;
age: <span class="hljs-built_in">number</span>;
}
knex(<span class="hljs-string">'users'</span>)
.where(<span class="hljs-string">'id'</span>)
.first(); <span class="hljs-comment">// Resolves to any</span>
knex<User>(<span class="hljs-string">'users'</span>) <span class="hljs-comment">// User is the type of row in database</span>
.where(<span class="hljs-string">'id'</span>, <span class="hljs-number">1</span>) <span class="hljs-comment">// Your IDE will be able to help with the completion of id</span>
.first(); <span class="hljs-comment">// Resolves to User | undefined</span></code></pre><p data-reactid="822">It is also possible to take advantage of auto-completion support (in TypeScript-aware IDEs) with generic type params when writing code in plain JavaScript through JSDoc comments.</p><pre data-reactid="823"><code class="hljs ts" data-reactid="824"><span class="hljs-comment">/**
* @typedef {Object} User
* @property {number} id
* @property {number} age
* @property {string} name
*
* @returns {Knex.QueryBuilder<User, {}>}
*/</span>
<span class="hljs-keyword">const</span> Users = <span class="hljs-function"><span class="hljs-params">()</span> =></span> knex(<span class="hljs-string">'Users'</span>)
Users().where(<span class="hljs-string">'id'</span>, <span class="hljs-number">1</span>) <span class="hljs-comment">// 'id' property can be autocompleted by editor</span></code></pre><h3 data-reactid="825">Caveat with type inference and mutable fluent APIs</h3><p data-reactid="826">Most of the knex APIs mutate current object and return it. This pattern does not work well with type-inference.</p><pre data-reactid="827"><code class="hljs ts" data-reactid="828">knex<User>(<span class="hljs-string">'users'</span>)
.select(<span class="hljs-string">'id'</span>)
.then(<span class="hljs-function">(<span class="hljs-params">users</span>) =></span> { <span class="hljs-comment">// Type of users is inferred as Pick<User, "id">[]</span>
<span class="hljs-comment">// Do something with users</span>
});
knex<User>(<span class="hljs-string">'users'</span>)
.select(<span class="hljs-string">'id'</span>)
.select(<span class="hljs-string">'age'</span>)
.then(<span class="hljs-function">(<span class="hljs-params">users</span>) =></span> { <span class="hljs-comment">// Type of users is inferred as Pick<User, "id" | "age">[]</span>
<span class="hljs-comment">// Do something with users</span>
});
<span class="hljs-comment">// The type of usersQueryBuilder is determined here</span>
<span class="hljs-keyword">const</span> usersQueryBuilder = knex<User>(<span class="hljs-string">'users'</span>).select(<span class="hljs-string">'id'</span>);
<span class="hljs-keyword">if</span> (someCondition) {
<span class="hljs-comment">// This select will not change the type of usersQueryBuilder</span>
<span class="hljs-comment">// We can not change the type of a pre-declared variabe in TypeScript</span>
usersQueryBuilder.select(<span class="hljs-string">'age'</span>);
}
usersQueryBuilder.then(<span class="hljs-function">(<span class="hljs-params">users</span>) =></span> {
<span class="hljs-comment">// Type of users here will be Pick<User, "id">[]</span>
<span class="hljs-comment">// which may not be what you expect.</span>
});
<span class="hljs-comment">// You can specify the type of result explicitly through a second type parameter:</span>
<span class="hljs-keyword">const</span> queryBuilder = knex<User, Pick<User, <span class="hljs-string">"id"</span> | <span class="hljs-string">"age"</span>>>(<span class="hljs-string">'users'</span>);
<span class="hljs-comment">// But there is no type constraint to ensure that these properties have actually been</span>
<span class="hljs-comment">// selected.</span>
<span class="hljs-comment">// So, this will compile:</span>
queryBuilder.select(<span class="hljs-string">'name'</span>).then(<span class="hljs-function">(<span class="hljs-params">users</span>) =></span> {
<span class="hljs-comment">// Type of users is Pick<User, "id"> but it will only have name</span>
})</code></pre><p data-reactid="829">If you don't want to manually specify the result type, it is recommended to always use the type of last value of the chain and assign result of any future chain continuation to a separate variable (which will have a different type).</p></div><div id="Builder-timeout" data-reactid="830"><b data-reactid="831">timeout</b><!-- react-text: 832 --> — <!-- /react-text --><code data-reactid="833">.timeout(ms, options={cancel: boolean})</code><p data-reactid="834">Sets a timeout for the query and will throw a TimeoutError if the timeout is exceeded. The error contains information about the query, bindings, and the timeout that was set. Useful for complex queries that you want to make sure are not taking too long to execute. Optional second argument for passing options:* <strong>cancel</strong>: if <code>true</code>, cancel query if timeout is reached. <strong>NOTE:</strong> only supported in MySQL and PostgreSQL for now.</p><pre class="display" data-reactid="835"><code class="js hljs" data-reactid="836">knex.select().from(<span class="hljs-string">'books'</span>).timeout(<span class="hljs-number">1000</span>)</code><br data-reactid="837"/><!-- react-text: 838 -->Outputs:<!-- /react-text --><br data-reactid="839"/><code class="sql hljs" data-reactid="840"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`books`</span></code></pre><pre class="display" data-reactid="841"><code class="js hljs" data-reactid="842">knex.select().from(<span class="hljs-string">'books'</span>).timeout(<span class="hljs-number">1000</span>, {<span class="hljs-attr">cancel</span>: <span class="hljs-literal">true</span>}) <span class="hljs-comment">// MySQL and PostgreSQL only</span></code><br data-reactid="843"/><!-- react-text: 844 -->Outputs:<!-- /react-text --><br data-reactid="845"/><code class="sql hljs" data-reactid="846"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`books`</span></code></pre></div><div id="Builder-select" data-reactid="847"><b data-reactid="848">select</b><!-- react-text: 849 --> — <!-- /react-text --><code data-reactid="850">.select([*columns])</code><p data-reactid="851">Creates a select query, taking an optional array of columns for the query, eventually defaulting to * if none are specified when the query is built. The response of a select call will resolve with an array of objects selected from the database.</p><pre class="display" data-reactid="852"><code class="js hljs" data-reactid="853">knex.select(<span class="hljs-string">'title'</span>, <span class="hljs-string">'author'</span>, <span class="hljs-string">'year'</span>).from(<span class="hljs-string">'books'</span>)</code><br data-reactid="854"/><!-- react-text: 855 -->Outputs:<!-- /react-text --><br data-reactid="856"/><code class="sql hljs" data-reactid="857"><span class="hljs-keyword">select</span> <span class="hljs-string">`title`</span>, <span class="hljs-string">`author`</span>, <span class="hljs-string">`year`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`books`</span></code></pre><pre class="display" data-reactid="858"><code class="js hljs" data-reactid="859">knex.select().table(<span class="hljs-string">'books'</span>)</code><br data-reactid="860"/><!-- react-text: 861 -->Outputs:<!-- /react-text --><br data-reactid="862"/><code class="sql hljs" data-reactid="863"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`books`</span></code></pre><h3 data-reactid="864">Usage with TypeScript</h3><p data-reactid="865">We are generally able to infer the result type based on the columns being selected as long as the select arguments match exactly the key names in record type. However, aliasing and scoping can get in the way of inference.</p><pre data-reactid="866"><code class="hljs ts" data-reactid="867">knex.select(<span class="hljs-string">'id'</span>).from<User>(<span class="hljs-string">'users'</span>); <span class="hljs-comment">// Resolves to Pick<User, "id">[]</span>
knex.select(<span class="hljs-string">'users.id'</span>).from<User>(<span class="hljs-string">'users'</span>); <span class="hljs-comment">// Resolves to any[]</span>
<span class="hljs-comment">// ^ TypeScript doesn't provide us a way to look into a string and infer the type</span>
<span class="hljs-comment">// from a substring, so we fall back to any</span>
<span class="hljs-comment">// We can side-step this using knex.ref:</span>
knex.select(knex.ref(<span class="hljs-string">'id'</span>).withSchema(<span class="hljs-string">'users'</span>)).from<User>(<span class="hljs-string">'users'</span>); <span class="hljs-comment">// Resolves to Pick<User, "id">[]</span>
knex.select(<span class="hljs-string">'id as identifier'</span>).from<User>(<span class="hljs-string">'users'</span>); <span class="hljs-comment">// Resolves to any[], for same reason as above</span>
<span class="hljs-comment">// Refs are handy here too:</span>
knex.select(knex.ref(<span class="hljs-string">'id'</span>).as(<span class="hljs-string">'identifier'</span>)).from<User>(<span class="hljs-string">'users'</span>); <span class="hljs-comment">// Resolves to { identifier: number; }[]</span></code></pre></div><div id="Builder-as" data-reactid="868"><b data-reactid="869">as</b><!-- react-text: 870 --> — <!-- /react-text --><code data-reactid="871">.as(name)</code><p data-reactid="872">Allows for aliasing a subquery, taking the string you wish to name the current query. If the query is not a sub-query, it will be ignored.</p><pre class="display" data-reactid="873"><code class="js hljs" data-reactid="874">knex.avg(<span class="hljs-string">'sum_column1'</span>).from(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.sum(<span class="hljs-string">'column1 as sum_column1'</span>).from(<span class="hljs-string">'t1'</span>).groupBy(<span class="hljs-string">'column1'</span>).as(<span class="hljs-string">'t1'</span>)
}).as(<span class="hljs-string">'ignored_alias'</span>)</code><br data-reactid="875"/><!-- react-text: 876 -->Outputs:<!-- /react-text --><br data-reactid="877"/><code class="sql hljs" data-reactid="878"><span class="hljs-keyword">select</span> <span class="hljs-keyword">avg</span>(<span class="hljs-string">`sum_column1`</span>) <span class="hljs-keyword">from</span> (<span class="hljs-keyword">select</span> <span class="hljs-keyword">sum</span>(<span class="hljs-string">`column1`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`sum_column1`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`t1`</span> <span class="hljs-keyword">group</span> <span class="hljs-keyword">by</span> <span class="hljs-string">`column1`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`t1`</span></code></pre></div><div id="Builder-column" data-reactid="879"><b data-reactid="880">column</b><!-- react-text: 881 --> — <!-- /react-text --><code data-reactid="882">.column(columns)</code><p data-reactid="883">Specifically set the columns to be selected on a select query, taking an array, an object or a list of column names. Passing an object will automatically alias the columns with the given keys.</p><pre class="display" data-reactid="884"><code class="js hljs" data-reactid="885">knex.column(<span class="hljs-string">'title'</span>, <span class="hljs-string">'author'</span>, <span class="hljs-string">'year'</span>).select().from(<span class="hljs-string">'books'</span>)</code><br data-reactid="886"/><!-- react-text: 887 -->Outputs:<!-- /react-text --><br data-reactid="888"/><code class="sql hljs" data-reactid="889"><span class="hljs-keyword">select</span> <span class="hljs-string">`title`</span>, <span class="hljs-string">`author`</span>, <span class="hljs-string">`year`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`books`</span></code></pre><pre class="display" data-reactid="890"><code class="js hljs" data-reactid="891">knex.column([<span class="hljs-string">'title'</span>, <span class="hljs-string">'author'</span>, <span class="hljs-string">'year'</span>]).select().from(<span class="hljs-string">'books'</span>)</code><br data-reactid="892"/><!-- react-text: 893 -->Outputs:<!-- /react-text --><br data-reactid="894"/><code class="sql hljs" data-reactid="895"><span class="hljs-keyword">select</span> <span class="hljs-string">`title`</span>, <span class="hljs-string">`author`</span>, <span class="hljs-string">`year`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`books`</span></code></pre><pre class="display" data-reactid="896"><code class="js hljs" data-reactid="897">knex.column(<span class="hljs-string">'title'</span>, {<span class="hljs-attr">by</span>: <span class="hljs-string">'author'</span>}, <span class="hljs-string">'year'</span>).select().from(<span class="hljs-string">'books'</span>)</code><br data-reactid="898"/><!-- react-text: 899 -->Outputs:<!-- /react-text --><br data-reactid="900"/><code class="sql hljs" data-reactid="901"><span class="hljs-keyword">select</span> <span class="hljs-string">`title`</span>, <span class="hljs-string">`author`</span> <span class="hljs-keyword">as</span> <span class="hljs-string">`by`</span>, <span class="hljs-string">`year`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`books`</span></code></pre></div><div id="Builder-from" data-reactid="902"><b data-reactid="903">from</b><!-- react-text: 904 --> — <!-- /react-text --><code data-reactid="905">.from([tableName], options={only: boolean})</code><p data-reactid="906">Specifies the table used in the current query, replacing the current table name if one has already been specified. This is typically used in the sub-queries performed in the advanced where or union methods. Optional second argument for passing options:* <strong>only</strong>: if <code>true</code>, the ONLY keyword is used before the <code>tableName</code> to discard inheriting tables' data. <strong>NOTE:</strong> only supported in PostgreSQL for now.</p><pre class="display" data-reactid="907"><code class="js hljs" data-reactid="908">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>)</code><br data-reactid="909"/><!-- react-text: 910 -->Outputs:<!-- /react-text --><br data-reactid="911"/><code class="sql hljs" data-reactid="912"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><h3 data-reactid="913">Usage with TypeScript</h3><p data-reactid="914">We can specify the type of database row through the TRecord type parameter</p><pre data-reactid="915"><code class="hljs ts" data-reactid="916">knex.select(<span class="hljs-string">'id'</span>).from(<span class="hljs-string">'users'</span>); <span class="hljs-comment">// Resolves to any[]</span>
knex.select(<span class="hljs-string">'id'</span>).from<User>(<span class="hljs-string">'users'</span>); <span class="hljs-comment">// Results to Pick<User, "id">[]</span></code></pre></div><div id="Builder-with" data-reactid="917"><b data-reactid="918">with</b><!-- react-text: 919 --> — <!-- /react-text --><code data-reactid="920">.with(alias, function|raw)</code><p data-reactid="921">Add a "with" clause to the query. "With" clauses are supported by PostgreSQL, Oracle, SQLite3 and MSSQL.</p><pre class="display" data-reactid="922"><code class="js hljs" data-reactid="923">knex.with(<span class="hljs-string">'with_alias'</span>, knex.raw(<span class="hljs-string">'select * from "books" where "author" = ?'</span>, <span class="hljs-string">'Test'</span>)).select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'with_alias'</span>)</code><br data-reactid="924"/><!-- react-text: 925 -->Outputs:<!-- /react-text --><br data-reactid="926"/><code class="sql hljs" data-reactid="927"><span class="hljs-keyword">with</span> <span class="hljs-string">`with_alias`</span> <span class="hljs-keyword">as</span> (<span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">"books"</span> <span class="hljs-keyword">where</span> <span class="hljs-string">"author"</span> = <span class="hljs-string">'Test'</span>) <span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`with_alias`</span></code></pre><pre class="display" data-reactid="928"><code class="js hljs" data-reactid="929">knex.with(<span class="hljs-string">'with_alias'</span>, (qb) => {
qb.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'books'</span>).where(<span class="hljs-string">'author'</span>, <span class="hljs-string">'Test'</span>)
}).select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'with_alias'</span>)</code><br data-reactid="930"/><!-- react-text: 931 -->Outputs:<!-- /react-text --><br data-reactid="932"/><code class="sql hljs" data-reactid="933"><span class="hljs-keyword">with</span> <span class="hljs-string">`with_alias`</span> <span class="hljs-keyword">as</span> (<span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`books`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`author`</span> = <span class="hljs-string">'Test'</span>) <span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`with_alias`</span></code></pre></div><div id="Builder-withRecursive" data-reactid="934"><b data-reactid="935">withRecursive</b><!-- react-text: 936 --> — <!-- /react-text --><code data-reactid="937">.withRecursive(alias, function|raw)</code><p data-reactid="938">Indentical to the <code>with</code> method except "recursive" is appended to "with" to make self-referential CTEs possible.</p><pre class="display" data-reactid="939"><code class="js hljs" data-reactid="940">knex.withRecursive(<span class="hljs-string">'ancestors'</span>, (qb) => {
qb.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'people'</span>).where(<span class="hljs-string">'people.id'</span>, <span class="hljs-number">1</span>).union(<span class="hljs-function">(<span class="hljs-params">qb</span>) =></span> {
qb.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'people'</span>).join(<span class="hljs-string">'ancestors'</span>, <span class="hljs-string">'ancestors.parentId'</span>, <span class="hljs-string">'people.id'</span>)
})
}).select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'ancestors'</span>)</code><br data-reactid="941"/><!-- react-text: 942 -->Outputs:<!-- /react-text --><br data-reactid="943"/><code class="sql hljs" data-reactid="944"><span class="hljs-keyword">with</span> <span class="hljs-keyword">recursive</span> <span class="hljs-string">`ancestors`</span> <span class="hljs-keyword">as</span> (<span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`people`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`people`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-number">1</span> <span class="hljs-keyword">union</span> <span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`people`</span> <span class="hljs-keyword">inner</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`ancestors`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`ancestors`</span>.<span class="hljs-string">`parentId`</span> = <span class="hljs-string">`people`</span>.<span class="hljs-string">`id`</span>) <span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`ancestors`</span></code></pre></div><div id="Builder-withSchema" data-reactid="945"><b data-reactid="946">withSchema</b><!-- react-text: 947 --> — <!-- /react-text --><code data-reactid="948">.withSchema([schemaName])</code><p data-reactid="949">Specifies the schema to be used as prefix of table name.</p><pre class="display" data-reactid="950"><code class="js hljs" data-reactid="951">knex.withSchema(<span class="hljs-string">'public'</span>).select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>)</code><br data-reactid="952"/><!-- react-text: 953 -->Outputs:<!-- /react-text --><br data-reactid="954"/><code class="sql hljs" data-reactid="955"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`public`</span>.<span class="hljs-string">`users`</span></code></pre></div><h3 id="Builder-wheres" data-reactid="956">Where Clauses</h3><div data-reactid="957"><p data-reactid="958">Several methods exist to assist in dynamic where clauses. In many places functions may be used in place of values, constructing subqueries. In most places existing knex queries may be used to compose sub-queries, etc. Take a look at a few of the examples for each method for instruction on use:</p><p data-reactid="959"><strong>Important:</strong> Supplying knex with an <code>undefined</code> value to any of the <code>where</code> functions will cause knex to throw an error during sql compilation. This is both for yours and our sake. Knex cannot know what to do with undefined values in a where clause, and generally it would be a programmatic error to supply one to begin with. The error will throw a message containing the type of query and the compiled query-string. Example:</p></div><pre class="display" data-reactid="960"><code class="js hljs" data-reactid="961">knex(<span class="hljs-string">'accounts'</span>)
.where(<span class="hljs-string">'login'</span>, <span class="hljs-literal">undefined</span>)
.select()
.toSQL()</code><br data-reactid="962"/><!-- react-text: 963 -->Error:<!-- /react-text --><br data-reactid="964"/><code class="sql hljs" data-reactid="965">Undefined binding(s) detected when compiling SELECT. Undefined column(s): [login] query: select * from `accounts` where `login` = ?</code></pre><div id="Builder-where" data-reactid="966"><b data-reactid="967">where</b><!-- react-text: 968 --> — <!-- /react-text --><code data-reactid="969">.where(~mixed~)</code></div><p data-reactid="970">Object Syntax:</p><pre class="display" data-reactid="971"><code class="js hljs" data-reactid="972">knex(<span class="hljs-string">'users'</span>).where({
<span class="hljs-attr">first_name</span>: <span class="hljs-string">'Test'</span>,
<span class="hljs-attr">last_name</span>: <span class="hljs-string">'User'</span>
}).select(<span class="hljs-string">'id'</span>)</code><br data-reactid="973"/><!-- react-text: 974 -->Outputs:<!-- /react-text --><br data-reactid="975"/><code class="sql hljs" data-reactid="976"><span class="hljs-keyword">select</span> <span class="hljs-string">`id`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`first_name`</span> = <span class="hljs-string">'Test'</span> <span class="hljs-keyword">and</span> <span class="hljs-string">`last_name`</span> = <span class="hljs-string">'User'</span></code></pre><p data-reactid="977">Key, Value:</p><pre class="display" data-reactid="978"><code class="js hljs" data-reactid="979">knex(<span class="hljs-string">'users'</span>).where(<span class="hljs-string">'id'</span>, <span class="hljs-number">1</span>)</code><br data-reactid="980"/><!-- react-text: 981 -->Outputs:<!-- /react-text --><br data-reactid="982"/><code class="sql hljs" data-reactid="983"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`id`</span> = <span class="hljs-number">1</span></code></pre><p data-reactid="984">Functions:</p><pre class="display" data-reactid="985"><code class="js hljs" data-reactid="986">knex(<span class="hljs-string">'users'</span>)
.where(<span class="hljs-function">(<span class="hljs-params">builder</span>) =></span>
builder.whereIn(<span class="hljs-string">'id'</span>, [<span class="hljs-number">1</span>, <span class="hljs-number">11</span>, <span class="hljs-number">15</span>]).whereNotIn(<span class="hljs-string">'id'</span>, [<span class="hljs-number">17</span>, <span class="hljs-number">19</span>])
)
.andWhere(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.where(<span class="hljs-string">'id'</span>, <span class="hljs-string">'>'</span>, <span class="hljs-number">10</span>)
})</code><br data-reactid="987"/><!-- react-text: 988 -->Outputs:<!-- /react-text --><br data-reactid="989"/><code class="sql hljs" data-reactid="990"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> (<span class="hljs-string">`id`</span> <span class="hljs-keyword">in</span> (<span class="hljs-number">1</span>, <span class="hljs-number">11</span>, <span class="hljs-number">15</span>) <span class="hljs-keyword">and</span> <span class="hljs-string">`id`</span> <span class="hljs-keyword">not</span> <span class="hljs-keyword">in</span> (<span class="hljs-number">17</span>, <span class="hljs-number">19</span>)) <span class="hljs-keyword">and</span> (<span class="hljs-string">`id`</span> > <span class="hljs-number">10</span>)</code></pre><p data-reactid="991">Grouped Chain:</p><pre class="display" data-reactid="992"><code class="js hljs" data-reactid="993">knex(<span class="hljs-string">'users'</span>).where(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.where(<span class="hljs-string">'id'</span>, <span class="hljs-number">1</span>).orWhere(<span class="hljs-string">'id'</span>, <span class="hljs-string">'>'</span>, <span class="hljs-number">10</span>)
}).orWhere({<span class="hljs-attr">name</span>: <span class="hljs-string">'Tester'</span>})</code><br data-reactid="994"/><!-- react-text: 995 -->Outputs:<!-- /react-text --><br data-reactid="996"/><code class="sql hljs" data-reactid="997"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> (<span class="hljs-string">`id`</span> = <span class="hljs-number">1</span> <span class="hljs-keyword">or</span> <span class="hljs-string">`id`</span> > <span class="hljs-number">10</span>) <span class="hljs-keyword">or</span> (<span class="hljs-string">`name`</span> = <span class="hljs-string">'Tester'</span>)</code></pre><p data-reactid="998">Operator:</p><pre class="display" data-reactid="999"><code class="js hljs" data-reactid="1000">knex(<span class="hljs-string">'users'</span>).where(<span class="hljs-string">'columnName'</span>, <span class="hljs-string">'like'</span>, <span class="hljs-string">'%rowlikeme%'</span>)</code><br data-reactid="1001"/><!-- react-text: 1002 -->Outputs:<!-- /react-text --><br data-reactid="1003"/><code class="sql hljs" data-reactid="1004"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`columnName`</span> <span class="hljs-keyword">like</span> <span class="hljs-string">'%rowlikeme%'</span></code></pre><p data-reactid="1005">The above query demonstrates the common use case of returning all users for which a specific pattern appears within a designated column.</p><pre class="display" data-reactid="1006"><code class="js hljs" data-reactid="1007">knex(<span class="hljs-string">'users'</span>).where(<span class="hljs-string">'votes'</span>, <span class="hljs-string">'>'</span>, <span class="hljs-number">100</span>)</code><br data-reactid="1008"/><!-- react-text: 1009 -->Outputs:<!-- /react-text --><br data-reactid="1010"/><code class="sql hljs" data-reactid="1011"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`votes`</span> > <span class="hljs-number">100</span></code></pre><pre class="display" data-reactid="1012"><code class="js hljs" data-reactid="1013"><span class="hljs-keyword">var</span> subquery = knex(<span class="hljs-string">'users'</span>).where(<span class="hljs-string">'votes'</span>, <span class="hljs-string">'>'</span>, <span class="hljs-number">100</span>).andWhere(<span class="hljs-string">'status'</span>, <span class="hljs-string">'active'</span>).orWhere(<span class="hljs-string">'name'</span>, <span class="hljs-string">'John'</span>).select(<span class="hljs-string">'id'</span>);
knex(<span class="hljs-string">'accounts'</span>).where(<span class="hljs-string">'id'</span>, <span class="hljs-string">'in'</span>, subquery)</code><br data-reactid="1014"/><!-- react-text: 1015 -->Outputs:<!-- /react-text --><br data-reactid="1016"/><code class="sql hljs" data-reactid="1017"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`id`</span> <span class="hljs-keyword">in</span> (<span class="hljs-keyword">select</span> <span class="hljs-string">`id`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`votes`</span> > <span class="hljs-number">100</span> <span class="hljs-keyword">and</span> <span class="hljs-string">`status`</span> = <span class="hljs-string">'active'</span> <span class="hljs-keyword">or</span> <span class="hljs-string">`name`</span> = <span class="hljs-string">'John'</span>)</code></pre><p data-reactid="1018">.orWhere with an object automatically wraps the statement and creates an <code>or (and - and - and)</code> clause</p><pre class="display" data-reactid="1019"><code class="js hljs" data-reactid="1020">knex(<span class="hljs-string">'users'</span>).where(<span class="hljs-string">'id'</span>, <span class="hljs-number">1</span>).orWhere({<span class="hljs-attr">votes</span>: <span class="hljs-number">100</span>, <span class="hljs-attr">user</span>: <span class="hljs-string">'knex'</span>})</code><br data-reactid="1021"/><!-- react-text: 1022 -->Outputs:<!-- /react-text --><br data-reactid="1023"/><code class="sql hljs" data-reactid="1024"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`id`</span> = <span class="hljs-number">1</span> <span class="hljs-keyword">or</span> (<span class="hljs-string">`votes`</span> = <span class="hljs-number">100</span> <span class="hljs-keyword">and</span> <span class="hljs-string">`user`</span> = <span class="hljs-string">'knex'</span>)</code></pre><div id="Builder-whereNot" data-reactid="1025"><b data-reactid="1026">whereNot</b><!-- react-text: 1027 --> — <!-- /react-text --><code data-reactid="1028">.whereNot(~mixed~)</code></div><p data-reactid="1029">Object Syntax:</p><pre class="display" data-reactid="1030"><code class="js hljs" data-reactid="1031">knex(<span class="hljs-string">'users'</span>).whereNot({
<span class="hljs-attr">first_name</span>: <span class="hljs-string">'Test'</span>,
<span class="hljs-attr">last_name</span>: <span class="hljs-string">'User'</span>
}).select(<span class="hljs-string">'id'</span>)</code><br data-reactid="1032"/><!-- react-text: 1033 -->Outputs:<!-- /react-text --><br data-reactid="1034"/><code class="sql hljs" data-reactid="1035"><span class="hljs-keyword">select</span> <span class="hljs-string">`id`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-keyword">not</span> <span class="hljs-string">`first_name`</span> = <span class="hljs-string">'Test'</span> <span class="hljs-keyword">and</span> <span class="hljs-keyword">not</span> <span class="hljs-string">`last_name`</span> = <span class="hljs-string">'User'</span></code></pre><p data-reactid="1036">Key, Value:</p><pre class="display" data-reactid="1037"><code class="js hljs" data-reactid="1038">knex(<span class="hljs-string">'users'</span>).whereNot(<span class="hljs-string">'id'</span>, <span class="hljs-number">1</span>)</code><br data-reactid="1039"/><!-- react-text: 1040 -->Outputs:<!-- /react-text --><br data-reactid="1041"/><code class="sql hljs" data-reactid="1042"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-keyword">not</span> <span class="hljs-string">`id`</span> = <span class="hljs-number">1</span></code></pre><p data-reactid="1043">Grouped Chain:</p><pre class="display" data-reactid="1044"><code class="js hljs" data-reactid="1045">knex(<span class="hljs-string">'users'</span>).whereNot(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.where(<span class="hljs-string">'id'</span>, <span class="hljs-number">1</span>).orWhereNot(<span class="hljs-string">'id'</span>, <span class="hljs-string">'>'</span>, <span class="hljs-number">10</span>)
}).orWhereNot({<span class="hljs-attr">name</span>: <span class="hljs-string">'Tester'</span>})</code><br data-reactid="1046"/><!-- react-text: 1047 -->Outputs:<!-- /react-text --><br data-reactid="1048"/><code class="sql hljs" data-reactid="1049"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-keyword">not</span> (<span class="hljs-string">`id`</span> = <span class="hljs-number">1</span> <span class="hljs-keyword">or</span> <span class="hljs-keyword">not</span> <span class="hljs-string">`id`</span> > <span class="hljs-number">10</span>) <span class="hljs-keyword">or</span> <span class="hljs-keyword">not</span> <span class="hljs-string">`name`</span> = <span class="hljs-string">'Tester'</span></code></pre><p data-reactid="1050">Operator:</p><pre class="display" data-reactid="1051"><code class="js hljs" data-reactid="1052">knex(<span class="hljs-string">'users'</span>).whereNot(<span class="hljs-string">'votes'</span>, <span class="hljs-string">'>'</span>, <span class="hljs-number">100</span>)</code><br data-reactid="1053"/><!-- react-text: 1054 -->Outputs:<!-- /react-text --><br data-reactid="1055"/><code class="sql hljs" data-reactid="1056"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-keyword">not</span> <span class="hljs-string">`votes`</span> > <span class="hljs-number">100</span></code></pre><p data-reactid="1057">CAVEAT: WhereNot is not suitable for "in" and "between" type subqueries. You should use "not in" and "not between" instead.</p><pre class="display" data-reactid="1058"><code class="js hljs" data-reactid="1059"><span class="hljs-keyword">var</span> subquery = knex(<span class="hljs-string">'users'</span>)
.whereNot(<span class="hljs-string">'votes'</span>, <span class="hljs-string">'>'</span>, <span class="hljs-number">100</span>)
.andWhere(<span class="hljs-string">'status'</span>, <span class="hljs-string">'active'</span>)
.orWhere(<span class="hljs-string">'name'</span>, <span class="hljs-string">'John'</span>)
.select(<span class="hljs-string">'id'</span>);
knex(<span class="hljs-string">'accounts'</span>).where(<span class="hljs-string">'id'</span>, <span class="hljs-string">'not in'</span>, subquery)</code><br data-reactid="1060"/><!-- react-text: 1061 -->Outputs:<!-- /react-text --><br data-reactid="1062"/><code class="sql hljs" data-reactid="1063"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`id`</span> <span class="hljs-keyword">not</span> <span class="hljs-keyword">in</span> (<span class="hljs-keyword">select</span> <span class="hljs-string">`id`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-keyword">not</span> <span class="hljs-string">`votes`</span> > <span class="hljs-number">100</span> <span class="hljs-keyword">and</span> <span class="hljs-string">`status`</span> = <span class="hljs-string">'active'</span> <span class="hljs-keyword">or</span> <span class="hljs-string">`name`</span> = <span class="hljs-string">'John'</span>)</code></pre><div id="Builder-whereIn" data-reactid="1064"><b data-reactid="1065">whereIn</b><!-- react-text: 1066 --> — <!-- /react-text --><code data-reactid="1067">.whereIn(column|columns, array|callback|builder) / .orWhereIn</code><p data-reactid="1068">Shorthand for .where('id', 'in', obj), the .whereIn and .orWhereIn methods add a "where in" clause to the query. Note that passing empty array as the value results in a query that never returns any rows (<code>WHERE 1 = 0</code>)</p><pre class="display" data-reactid="1069"><code class="js hljs" data-reactid="1070">knex.select(<span class="hljs-string">'name'</span>).from(<span class="hljs-string">'users'</span>)
.whereIn(<span class="hljs-string">'id'</span>, [<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>])
.orWhereIn(<span class="hljs-string">'id'</span>, [<span class="hljs-number">4</span>, <span class="hljs-number">5</span>, <span class="hljs-number">6</span>])</code><br data-reactid="1071"/><!-- react-text: 1072 -->Outputs:<!-- /react-text --><br data-reactid="1073"/><code class="sql hljs" data-reactid="1074"><span class="hljs-keyword">select</span> <span class="hljs-string">`name`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`id`</span> <span class="hljs-keyword">in</span> (<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>) <span class="hljs-keyword">or</span> <span class="hljs-string">`id`</span> <span class="hljs-keyword">in</span> (<span class="hljs-number">4</span>, <span class="hljs-number">5</span>, <span class="hljs-number">6</span>)</code></pre><pre class="display" data-reactid="1075"><code class="js hljs" data-reactid="1076">knex.select(<span class="hljs-string">'name'</span>).from(<span class="hljs-string">'users'</span>)
.whereIn(<span class="hljs-string">'account_id'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.select(<span class="hljs-string">'id'</span>).from(<span class="hljs-string">'accounts'</span>);
})</code><br data-reactid="1077"/><!-- react-text: 1078 -->Outputs:<!-- /react-text --><br data-reactid="1079"/><code class="sql hljs" data-reactid="1080"><span class="hljs-keyword">select</span> <span class="hljs-string">`name`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`account_id`</span> <span class="hljs-keyword">in</span> (<span class="hljs-keyword">select</span> <span class="hljs-string">`id`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`accounts`</span>)</code></pre><pre class="display" data-reactid="1081"><code class="js hljs" data-reactid="1082"><span class="hljs-keyword">var</span> subquery = knex.select(<span class="hljs-string">'id'</span>).from(<span class="hljs-string">'accounts'</span>);
knex.select(<span class="hljs-string">'name'</span>).from(<span class="hljs-string">'users'</span>)
.whereIn(<span class="hljs-string">'account_id'</span>, subquery)</code><br data-reactid="1083"/><!-- react-text: 1084 -->Outputs:<!-- /react-text --><br data-reactid="1085"/><code class="sql hljs" data-reactid="1086"><span class="hljs-keyword">select</span> <span class="hljs-string">`name`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`account_id`</span> <span class="hljs-keyword">in</span> (<span class="hljs-keyword">select</span> <span class="hljs-string">`id`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`accounts`</span>)</code></pre><pre class="display" data-reactid="1087"><code class="js hljs" data-reactid="1088">knex.select(<span class="hljs-string">'name'</span>).from(<span class="hljs-string">'users'</span>)
.whereIn([<span class="hljs-string">'account_id'</span>, <span class="hljs-string">'email'</span>], [[<span class="hljs-number">3</span>, <span class="hljs-string">'test3@example.com'</span>], [<span class="hljs-number">4</span>, <span class="hljs-string">'test4@example.com'</span>]])</code><br data-reactid="1089"/><!-- react-text: 1090 -->Outputs:<!-- /react-text --><br data-reactid="1091"/><code class="sql hljs" data-reactid="1092"><span class="hljs-keyword">select</span> <span class="hljs-string">`name`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> (<span class="hljs-string">`account_id`</span>, <span class="hljs-string">`email`</span>) <span class="hljs-keyword">in</span> ((<span class="hljs-number">3</span>, <span class="hljs-string">'test3@example.com'</span>), (<span class="hljs-number">4</span>, <span class="hljs-string">'test4@example.com'</span>))</code></pre><pre class="display" data-reactid="1093"><code class="js hljs" data-reactid="1094">knex.select(<span class="hljs-string">'name'</span>).from(<span class="hljs-string">'users'</span>)
.whereIn([<span class="hljs-string">'account_id'</span>, <span class="hljs-string">'email'</span>], knex.select(<span class="hljs-string">'id'</span>, <span class="hljs-string">'email'</span>).from(<span class="hljs-string">'accounts'</span>))</code><br data-reactid="1095"/><!-- react-text: 1096 -->Outputs:<!-- /react-text --><br data-reactid="1097"/><code class="sql hljs" data-reactid="1098"><span class="hljs-keyword">select</span> <span class="hljs-string">`name`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> (<span class="hljs-string">`account_id`</span>, <span class="hljs-string">`email`</span>) <span class="hljs-keyword">in</span> (<span class="hljs-keyword">select</span> <span class="hljs-string">`id`</span>, <span class="hljs-string">`email`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`accounts`</span>)</code></pre></div><div id="Builder-whereNotIn" data-reactid="1099"><b data-reactid="1100">whereNotIn</b><!-- react-text: 1101 --> — <!-- /react-text --><code data-reactid="1102">.whereNotIn(column, array|callback|builder) / .orWhereNotIn</code><pre class="display" data-reactid="1103"><code class="js hljs" data-reactid="1104">knex(<span class="hljs-string">'users'</span>).whereNotIn(<span class="hljs-string">'id'</span>, [<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>])</code><br data-reactid="1105"/><!-- react-text: 1106 -->Outputs:<!-- /react-text --><br data-reactid="1107"/><code class="sql hljs" data-reactid="1108"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`id`</span> <span class="hljs-keyword">not</span> <span class="hljs-keyword">in</span> (<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>)</code></pre><pre class="display" data-reactid="1109"><code class="js hljs" data-reactid="1110">knex(<span class="hljs-string">'users'</span>).where(<span class="hljs-string">'name'</span>, <span class="hljs-string">'like'</span>, <span class="hljs-string">'%Test%'</span>).orWhereNotIn(<span class="hljs-string">'id'</span>, [<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>])</code><br data-reactid="1111"/><!-- react-text: 1112 -->Outputs:<!-- /react-text --><br data-reactid="1113"/><code class="sql hljs" data-reactid="1114"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`name`</span> <span class="hljs-keyword">like</span> <span class="hljs-string">'%Test%'</span> <span class="hljs-keyword">or</span> <span class="hljs-string">`id`</span> <span class="hljs-keyword">not</span> <span class="hljs-keyword">in</span> (<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>)</code></pre></div><div id="Builder-whereNull" data-reactid="1115"><b data-reactid="1116">whereNull</b><!-- react-text: 1117 --> — <!-- /react-text --><code data-reactid="1118">.whereNull(column) / .orWhereNull</code><pre class="display" data-reactid="1119"><code class="js hljs" data-reactid="1120">knex(<span class="hljs-string">'users'</span>).whereNull(<span class="hljs-string">'updated_at'</span>)</code><br data-reactid="1121"/><!-- react-text: 1122 -->Outputs:<!-- /react-text --><br data-reactid="1123"/><code class="sql hljs" data-reactid="1124"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`updated_at`</span> <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span></code></pre></div><div id="Builder-whereNotNull" data-reactid="1125"><b data-reactid="1126">whereNotNull</b><!-- react-text: 1127 --> — <!-- /react-text --><code data-reactid="1128">.whereNotNull(column) / .orWhereNotNull</code><pre class="display" data-reactid="1129"><code class="js hljs" data-reactid="1130">knex(<span class="hljs-string">'users'</span>).whereNotNull(<span class="hljs-string">'created_at'</span>)</code><br data-reactid="1131"/><!-- react-text: 1132 -->Outputs:<!-- /react-text --><br data-reactid="1133"/><code class="sql hljs" data-reactid="1134"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`created_at`</span> <span class="hljs-keyword">is</span> <span class="hljs-keyword">not</span> <span class="hljs-literal">null</span></code></pre></div><div id="Builder-whereExists" data-reactid="1135"><b data-reactid="1136">whereExists</b><!-- react-text: 1137 --> — <!-- /react-text --><code data-reactid="1138">.whereExists(builder | callback) / .orWhereExists</code><pre class="display" data-reactid="1139"><code class="js hljs" data-reactid="1140">knex(<span class="hljs-string">'users'</span>).whereExists(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'accounts'</span>).whereRaw(<span class="hljs-string">'users.account_id = accounts.id'</span>);
})</code><br data-reactid="1141"/><!-- react-text: 1142 -->Outputs:<!-- /react-text --><br data-reactid="1143"/><code class="sql hljs" data-reactid="1144"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-keyword">exists</span> (<span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">where</span> users.account_id = accounts.id)</code></pre><pre class="display" data-reactid="1145"><code class="js hljs" data-reactid="1146">knex(<span class="hljs-string">'users'</span>).whereExists(knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'accounts'</span>).whereRaw(<span class="hljs-string">'users.account_id = accounts.id'</span>))</code><br data-reactid="1147"/><!-- react-text: 1148 -->Outputs:<!-- /react-text --><br data-reactid="1149"/><code class="sql hljs" data-reactid="1150"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-keyword">exists</span> (<span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">where</span> users.account_id = accounts.id)</code></pre></div><div id="Builder-whereNotExists" data-reactid="1151"><b data-reactid="1152">whereNotExists</b><!-- react-text: 1153 --> — <!-- /react-text --><code data-reactid="1154">.whereNotExists(builder | callback) / .orWhereNotExists</code><pre class="display" data-reactid="1155"><code class="js hljs" data-reactid="1156">knex(<span class="hljs-string">'users'</span>).whereNotExists(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'accounts'</span>).whereRaw(<span class="hljs-string">'users.account_id = accounts.id'</span>);
})</code><br data-reactid="1157"/><!-- react-text: 1158 -->Outputs:<!-- /react-text --><br data-reactid="1159"/><code class="sql hljs" data-reactid="1160"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-keyword">not</span> <span class="hljs-keyword">exists</span> (<span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">where</span> users.account_id = accounts.id)</code></pre><pre class="display" data-reactid="1161"><code class="js hljs" data-reactid="1162">knex(<span class="hljs-string">'users'</span>).whereNotExists(knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'accounts'</span>).whereRaw(<span class="hljs-string">'users.account_id = accounts.id'</span>))</code><br data-reactid="1163"/><!-- react-text: 1164 -->Outputs:<!-- /react-text --><br data-reactid="1165"/><code class="sql hljs" data-reactid="1166"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-keyword">not</span> <span class="hljs-keyword">exists</span> (<span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">where</span> users.account_id = accounts.id)</code></pre></div><div id="Builder-whereBetween" data-reactid="1167"><b data-reactid="1168">whereBetween</b><!-- react-text: 1169 --> — <!-- /react-text --><code data-reactid="1170">.whereBetween(column, range) / .orWhereBetween</code><pre class="display" data-reactid="1171"><code class="js hljs" data-reactid="1172">knex(<span class="hljs-string">'users'</span>).whereBetween(<span class="hljs-string">'votes'</span>, [<span class="hljs-number">1</span>, <span class="hljs-number">100</span>])</code><br data-reactid="1173"/><!-- react-text: 1174 -->Outputs:<!-- /react-text --><br data-reactid="1175"/><code class="sql hljs" data-reactid="1176"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`votes`</span> <span class="hljs-keyword">between</span> <span class="hljs-number">1</span> <span class="hljs-keyword">and</span> <span class="hljs-number">100</span></code></pre></div><div id="Builder-whereNotBetween" data-reactid="1177"><b data-reactid="1178">whereNotBetween</b><!-- react-text: 1179 --> — <!-- /react-text --><code data-reactid="1180">.whereNotBetween(column, range) / .orWhereNotBetween</code><pre class="display" data-reactid="1181"><code class="js hljs" data-reactid="1182">knex(<span class="hljs-string">'users'</span>).whereNotBetween(<span class="hljs-string">'votes'</span>, [<span class="hljs-number">1</span>, <span class="hljs-number">100</span>])</code><br data-reactid="1183"/><!-- react-text: 1184 -->Outputs:<!-- /react-text --><br data-reactid="1185"/><code class="sql hljs" data-reactid="1186"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`votes`</span> <span class="hljs-keyword">not</span> <span class="hljs-keyword">between</span> <span class="hljs-number">1</span> <span class="hljs-keyword">and</span> <span class="hljs-number">100</span></code></pre></div><div id="Builder-whereRaw" data-reactid="1187"><b data-reactid="1188">whereRaw</b><!-- react-text: 1189 --> — <!-- /react-text --><code data-reactid="1190">.whereRaw(query, [bindings])</code><p data-reactid="1191">Convenience helper for .where(knex.raw(query)).</p><pre class="display" data-reactid="1192"><code class="js hljs" data-reactid="1193">knex(<span class="hljs-string">'users'</span>).whereRaw(<span class="hljs-string">'id = ?'</span>, [<span class="hljs-number">1</span>])</code><br data-reactid="1194"/><!-- react-text: 1195 -->Outputs:<!-- /react-text --><br data-reactid="1196"/><code class="sql hljs" data-reactid="1197"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-keyword">id</span> = <span class="hljs-number">1</span></code></pre></div><h3 data-reactid="1198">Join Methods</h3><p data-reactid="1199">Several methods are provided which assist in building joins.</p><div id="Builder-join" data-reactid="1200"><b data-reactid="1201">join</b><!-- react-text: 1202 --> — <!-- /react-text --><code data-reactid="1203">.join(table, first, [operator], second)</code><p data-reactid="1204">The join builder can be used to specify joins between tables, with the first argument being the joining table, the next three arguments being the first join column, the join operator and the second join column, respectively.</p><pre class="display" data-reactid="1205"><code class="js hljs" data-reactid="1206">knex(<span class="hljs-string">'users'</span>)
.join(<span class="hljs-string">'contacts'</span>, <span class="hljs-string">'users.id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'contacts.user_id'</span>)
.select(<span class="hljs-string">'users.id'</span>, <span class="hljs-string">'contacts.phone'</span>)</code><br data-reactid="1207"/><!-- react-text: 1208 -->Outputs:<!-- /react-text --><br data-reactid="1209"/><code class="sql hljs" data-reactid="1210"><span class="hljs-keyword">select</span> <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span>, <span class="hljs-string">`contacts`</span>.<span class="hljs-string">`phone`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">inner</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`contacts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`contacts`</span>.<span class="hljs-string">`user_id`</span></code></pre><pre class="display" data-reactid="1211"><code class="js hljs" data-reactid="1212">knex(<span class="hljs-string">'users'</span>)
.join(<span class="hljs-string">'contacts'</span>, <span class="hljs-string">'users.id'</span>, <span class="hljs-string">'contacts.user_id'</span>)
.select(<span class="hljs-string">'users.id'</span>, <span class="hljs-string">'contacts.phone'</span>)</code><br data-reactid="1213"/><!-- react-text: 1214 -->Outputs:<!-- /react-text --><br data-reactid="1215"/><code class="sql hljs" data-reactid="1216"><span class="hljs-keyword">select</span> <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span>, <span class="hljs-string">`contacts`</span>.<span class="hljs-string">`phone`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">inner</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`contacts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`contacts`</span>.<span class="hljs-string">`user_id`</span></code></pre></div><p data-reactid="1217">For grouped joins, specify a function as the second argument for the join query, and use <code>on</code> with <code>orOn</code> or <code>andOn</code> to create joins that are grouped with parentheses.</p><pre class="display" data-reactid="1218"><code class="js hljs" data-reactid="1219">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).join(<span class="hljs-string">'accounts'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.on(<span class="hljs-string">'accounts.id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'users.account_id'</span>).orOn(<span class="hljs-string">'accounts.owner_id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'users.id'</span>)
})</code><br data-reactid="1220"/><!-- react-text: 1221 -->Outputs:<!-- /react-text --><br data-reactid="1222"/><code class="sql hljs" data-reactid="1223"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">inner</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`users`</span>.<span class="hljs-string">`account_id`</span> <span class="hljs-keyword">or</span> <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`owner_id`</span> = <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span></code></pre><p data-reactid="1224">For nested join statements, specify a function as first argument of <code>on</code>, <code>orOn</code> or <code>andOn</code></p><pre class="display" data-reactid="1225"><code class="js hljs" data-reactid="1226">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).join(<span class="hljs-string">'accounts'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.on(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.on(<span class="hljs-string">'accounts.id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'users.account_id'</span>)
<span class="hljs-keyword">this</span>.orOn(<span class="hljs-string">'accounts.owner_id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'users.id'</span>)
})
})</code><br data-reactid="1227"/><!-- react-text: 1228 -->Outputs:<!-- /react-text --><br data-reactid="1229"/><code class="sql hljs" data-reactid="1230"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">inner</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">on</span> (<span class="hljs-string">`accounts`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`users`</span>.<span class="hljs-string">`account_id`</span> <span class="hljs-keyword">or</span> <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`owner_id`</span> = <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span>)</code></pre><p data-reactid="1231">It is also possible to use an object to represent the join syntax.</p><pre class="display" data-reactid="1232"><code class="js hljs" data-reactid="1233">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).join(<span class="hljs-string">'accounts'</span>, {<span class="hljs-string">'accounts.id'</span>: <span class="hljs-string">'users.account_id'</span>})</code><br data-reactid="1234"/><!-- react-text: 1235 -->Outputs:<!-- /react-text --><br data-reactid="1236"/><code class="sql hljs" data-reactid="1237"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">inner</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`users`</span>.<span class="hljs-string">`account_id`</span></code></pre><p data-reactid="1238">If you need to use a literal value (string, number, or boolean) in a join instead of a column, use <code>knex.raw</code>.</p><pre class="display" data-reactid="1239"><code class="js hljs" data-reactid="1240">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).join(<span class="hljs-string">'accounts'</span>, <span class="hljs-string">'accounts.type'</span>, knex.raw(<span class="hljs-string">'?'</span>, [<span class="hljs-string">'admin'</span>]))</code><br data-reactid="1241"/><!-- react-text: 1242 -->Outputs:<!-- /react-text --><br data-reactid="1243"/><code class="sql hljs" data-reactid="1244"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">inner</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`type`</span> = <span class="hljs-string">'admin'</span></code></pre><div id="Builder-innerJoin" data-reactid="1245"><b data-reactid="1246">innerJoin</b><!-- react-text: 1247 --> — <!-- /react-text --><code data-reactid="1248">.innerJoin(table, ~mixed~)</code><pre class="display" data-reactid="1249"><code class="js hljs" data-reactid="1250">knex.from(<span class="hljs-string">'users'</span>).innerJoin(<span class="hljs-string">'accounts'</span>, <span class="hljs-string">'users.id'</span>, <span class="hljs-string">'accounts.user_id'</span>)</code><br data-reactid="1251"/><!-- react-text: 1252 -->Outputs:<!-- /react-text --><br data-reactid="1253"/><code class="sql hljs" data-reactid="1254"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">inner</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`user_id`</span></code></pre><pre class="display" data-reactid="1255"><code class="js hljs" data-reactid="1256">knex.table(<span class="hljs-string">'users'</span>).innerJoin(<span class="hljs-string">'accounts'</span>, <span class="hljs-string">'users.id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'accounts.user_id'</span>)</code><br data-reactid="1257"/><!-- react-text: 1258 -->Outputs:<!-- /react-text --><br data-reactid="1259"/><code class="sql hljs" data-reactid="1260"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">inner</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`user_id`</span></code></pre><pre class="display" data-reactid="1261"><code class="js hljs" data-reactid="1262">knex(<span class="hljs-string">'users'</span>).innerJoin(<span class="hljs-string">'accounts'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.on(<span class="hljs-string">'accounts.id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'users.account_id'</span>).orOn(<span class="hljs-string">'accounts.owner_id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'users.id'</span>)
})</code><br data-reactid="1263"/><!-- react-text: 1264 -->Outputs:<!-- /react-text --><br data-reactid="1265"/><code class="sql hljs" data-reactid="1266"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">inner</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`users`</span>.<span class="hljs-string">`account_id`</span> <span class="hljs-keyword">or</span> <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`owner_id`</span> = <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span></code></pre></div><div id="Builder-leftJoin" data-reactid="1267"><b data-reactid="1268">leftJoin</b><!-- react-text: 1269 --> — <!-- /react-text --><code data-reactid="1270">.leftJoin(table, ~mixed~)</code><pre class="display" data-reactid="1271"><code class="js hljs" data-reactid="1272">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).leftJoin(<span class="hljs-string">'accounts'</span>, <span class="hljs-string">'users.id'</span>, <span class="hljs-string">'accounts.user_id'</span>)</code><br data-reactid="1273"/><!-- react-text: 1274 -->Outputs:<!-- /react-text --><br data-reactid="1275"/><code class="sql hljs" data-reactid="1276"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">left</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`user_id`</span></code></pre><pre class="display" data-reactid="1277"><code class="js hljs" data-reactid="1278">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).leftJoin(<span class="hljs-string">'accounts'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.on(<span class="hljs-string">'accounts.id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'users.account_id'</span>).orOn(<span class="hljs-string">'accounts.owner_id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'users.id'</span>)
})</code><br data-reactid="1279"/><!-- react-text: 1280 -->Outputs:<!-- /react-text --><br data-reactid="1281"/><code class="sql hljs" data-reactid="1282"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">left</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`users`</span>.<span class="hljs-string">`account_id`</span> <span class="hljs-keyword">or</span> <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`owner_id`</span> = <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span></code></pre></div><div id="Builder-leftOuterJoin" data-reactid="1283"><b data-reactid="1284">leftOuterJoin</b><!-- react-text: 1285 --> — <!-- /react-text --><code data-reactid="1286">.leftOuterJoin(table, ~mixed~)</code><pre class="display" data-reactid="1287"><code class="js hljs" data-reactid="1288">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).leftOuterJoin(<span class="hljs-string">'accounts'</span>, <span class="hljs-string">'users.id'</span>, <span class="hljs-string">'accounts.user_id'</span>)</code><br data-reactid="1289"/><!-- react-text: 1290 -->Outputs:<!-- /react-text --><br data-reactid="1291"/><code class="sql hljs" data-reactid="1292"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">left</span> <span class="hljs-keyword">outer</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`user_id`</span></code></pre><pre class="display" data-reactid="1293"><code class="js hljs" data-reactid="1294">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).leftOuterJoin(<span class="hljs-string">'accounts'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.on(<span class="hljs-string">'accounts.id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'users.account_id'</span>).orOn(<span class="hljs-string">'accounts.owner_id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'users.id'</span>)
})</code><br data-reactid="1295"/><!-- react-text: 1296 -->Outputs:<!-- /react-text --><br data-reactid="1297"/><code class="sql hljs" data-reactid="1298"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">left</span> <span class="hljs-keyword">outer</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`users`</span>.<span class="hljs-string">`account_id`</span> <span class="hljs-keyword">or</span> <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`owner_id`</span> = <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span></code></pre></div><div id="Builder-rightJoin" data-reactid="1299"><b data-reactid="1300">rightJoin</b><!-- react-text: 1301 --> — <!-- /react-text --><code data-reactid="1302">.rightJoin(table, ~mixed~)</code><pre class="display" data-reactid="1303"><code class="js hljs" data-reactid="1304">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).rightJoin(<span class="hljs-string">'accounts'</span>, <span class="hljs-string">'users.id'</span>, <span class="hljs-string">'accounts.user_id'</span>)</code><br data-reactid="1305"/><!-- react-text: 1306 -->Outputs:<!-- /react-text --><br data-reactid="1307"/><code class="sql hljs" data-reactid="1308"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">right</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`user_id`</span></code></pre><pre class="display" data-reactid="1309"><code class="js hljs" data-reactid="1310">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).rightJoin(<span class="hljs-string">'accounts'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.on(<span class="hljs-string">'accounts.id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'users.account_id'</span>).orOn(<span class="hljs-string">'accounts.owner_id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'users.id'</span>)
})</code><br data-reactid="1311"/><!-- react-text: 1312 -->Outputs:<!-- /react-text --><br data-reactid="1313"/><code class="sql hljs" data-reactid="1314"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">right</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`users`</span>.<span class="hljs-string">`account_id`</span> <span class="hljs-keyword">or</span> <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`owner_id`</span> = <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span></code></pre></div><div id="Builder-rightOuterJoin" data-reactid="1315"><b data-reactid="1316">rightOuterJoin</b><!-- react-text: 1317 --> — <!-- /react-text --><code data-reactid="1318">.rightOuterJoin(table, ~mixed~)</code><pre class="display" data-reactid="1319"><code class="js hljs" data-reactid="1320">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).rightOuterJoin(<span class="hljs-string">'accounts'</span>, <span class="hljs-string">'users.id'</span>, <span class="hljs-string">'accounts.user_id'</span>)</code><br data-reactid="1321"/><!-- react-text: 1322 -->Outputs:<!-- /react-text --><br data-reactid="1323"/><code class="sql hljs" data-reactid="1324"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">right</span> <span class="hljs-keyword">outer</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`user_id`</span></code></pre><pre class="display" data-reactid="1325"><code class="js hljs" data-reactid="1326">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).rightOuterJoin(<span class="hljs-string">'accounts'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.on(<span class="hljs-string">'accounts.id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'users.account_id'</span>).orOn(<span class="hljs-string">'accounts.owner_id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'users.id'</span>)
})</code><br data-reactid="1327"/><!-- react-text: 1328 -->Outputs:<!-- /react-text --><br data-reactid="1329"/><code class="sql hljs" data-reactid="1330"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">right</span> <span class="hljs-keyword">outer</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`users`</span>.<span class="hljs-string">`account_id`</span> <span class="hljs-keyword">or</span> <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`owner_id`</span> = <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span></code></pre></div><div id="Builder-fullOuterJoin" data-reactid="1331"><b data-reactid="1332">fullOuterJoin</b><!-- react-text: 1333 --> — <!-- /react-text --><code data-reactid="1334">.fullOuterJoin(table, ~mixed~)</code><pre class="display" data-reactid="1335"><code class="js hljs" data-reactid="1336">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).fullOuterJoin(<span class="hljs-string">'accounts'</span>, <span class="hljs-string">'users.id'</span>, <span class="hljs-string">'accounts.user_id'</span>)</code><br data-reactid="1337"/><!-- react-text: 1338 -->Outputs:<!-- /react-text --><br data-reactid="1339"/><code class="sql hljs" data-reactid="1340"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">full</span> <span class="hljs-keyword">outer</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`user_id`</span></code></pre><pre class="display" data-reactid="1341"><code class="js hljs" data-reactid="1342">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).fullOuterJoin(<span class="hljs-string">'accounts'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.on(<span class="hljs-string">'accounts.id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'users.account_id'</span>).orOn(<span class="hljs-string">'accounts.owner_id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'users.id'</span>)
})</code><br data-reactid="1343"/><!-- react-text: 1344 -->Outputs:<!-- /react-text --><br data-reactid="1345"/><code class="sql hljs" data-reactid="1346"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">full</span> <span class="hljs-keyword">outer</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`users`</span>.<span class="hljs-string">`account_id`</span> <span class="hljs-keyword">or</span> <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`owner_id`</span> = <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span></code></pre></div><div id="Builder-crossJoin" data-reactid="1347"><b data-reactid="1348">crossJoin</b><!-- react-text: 1349 --> — <!-- /react-text --><code data-reactid="1350">.crossJoin(table, ~mixed~)</code><p data-reactid="1351">Cross join conditions are only supported in MySQL and SQLite3. For join conditions rather use innerJoin.</p><pre class="display" data-reactid="1352"><code class="js hljs" data-reactid="1353">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).crossJoin(<span class="hljs-string">'accounts'</span>)</code><br data-reactid="1354"/><!-- react-text: 1355 -->Outputs:<!-- /react-text --><br data-reactid="1356"/><code class="sql hljs" data-reactid="1357"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">cross</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`accounts`</span></code></pre><pre class="display" data-reactid="1358"><code class="js hljs" data-reactid="1359">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).crossJoin(<span class="hljs-string">'accounts'</span>, <span class="hljs-string">'users.id'</span>, <span class="hljs-string">'accounts.user_id'</span>)</code><br data-reactid="1360"/><!-- react-text: 1361 -->Outputs:<!-- /react-text --><br data-reactid="1362"/><code class="sql hljs" data-reactid="1363"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">cross</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`user_id`</span></code></pre><pre class="display" data-reactid="1364"><code class="js hljs" data-reactid="1365">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).crossJoin(<span class="hljs-string">'accounts'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.on(<span class="hljs-string">'accounts.id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'users.account_id'</span>).orOn(<span class="hljs-string">'accounts.owner_id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'users.id'</span>)
})</code><br data-reactid="1366"/><!-- react-text: 1367 -->Outputs:<!-- /react-text --><br data-reactid="1368"/><code class="sql hljs" data-reactid="1369"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">cross</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`users`</span>.<span class="hljs-string">`account_id`</span> <span class="hljs-keyword">or</span> <span class="hljs-string">`accounts`</span>.<span class="hljs-string">`owner_id`</span> = <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span></code></pre></div><div id="Builder-joinRaw" data-reactid="1370"><b data-reactid="1371">joinRaw</b><!-- react-text: 1372 --> — <!-- /react-text --><code data-reactid="1373">.joinRaw(sql, [bindings])</code><pre class="display" data-reactid="1374"><code class="js hljs" data-reactid="1375">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'accounts'</span>).joinRaw(<span class="hljs-string">'natural full join table1'</span>).where(<span class="hljs-string">'id'</span>, <span class="hljs-number">1</span>)</code><br data-reactid="1376"/><!-- react-text: 1377 -->Outputs:<!-- /react-text --><br data-reactid="1378"/><code class="sql hljs" data-reactid="1379"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">natural</span> <span class="hljs-keyword">full</span> <span class="hljs-keyword">join</span> table1 <span class="hljs-keyword">where</span> <span class="hljs-string">`id`</span> = <span class="hljs-number">1</span></code></pre><pre class="display" data-reactid="1380"><code class="js hljs" data-reactid="1381">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'accounts'</span>).join(knex.raw(<span class="hljs-string">'natural full join table1'</span>)).where(<span class="hljs-string">'id'</span>, <span class="hljs-number">1</span>)</code><br data-reactid="1382"/><!-- react-text: 1383 -->Outputs:<!-- /react-text --><br data-reactid="1384"/><code class="sql hljs" data-reactid="1385"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">inner</span> <span class="hljs-keyword">join</span> <span class="hljs-keyword">natural</span> <span class="hljs-keyword">full</span> <span class="hljs-keyword">join</span> table1 <span class="hljs-keyword">where</span> <span class="hljs-string">`id`</span> = <span class="hljs-number">1</span></code></pre></div><h3 id="Builder-on" data-reactid="1386">OnClauses</h3><div id="Builder-onIn" data-reactid="1387"><b data-reactid="1388">onIn</b><!-- react-text: 1389 --> — <!-- /react-text --><code data-reactid="1390">.onIn(column, values)</code><p data-reactid="1391">Adds a onIn clause to the query.</p><pre class="display" data-reactid="1392"><code class="js hljs" data-reactid="1393">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).join(<span class="hljs-string">'contacts'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.on(<span class="hljs-string">'users.id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'contacts.id'</span>).onIn(<span class="hljs-string">'contacts.id'</span>, [<span class="hljs-number">7</span>, <span class="hljs-number">15</span>, <span class="hljs-number">23</span>, <span class="hljs-number">41</span>])
})</code><br data-reactid="1394"/><!-- react-text: 1395 -->Outputs:<!-- /react-text --><br data-reactid="1396"/><code class="sql hljs" data-reactid="1397"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">inner</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`contacts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`contacts`</span>.<span class="hljs-string">`id`</span> <span class="hljs-keyword">and</span> <span class="hljs-string">`contacts`</span>.<span class="hljs-string">`id`</span> <span class="hljs-keyword">in</span> (<span class="hljs-number">7</span>, <span class="hljs-number">15</span>, <span class="hljs-number">23</span>, <span class="hljs-number">41</span>)</code></pre></div><div id="Builder-onNotIn" data-reactid="1398"><b data-reactid="1399">onNotIn</b><!-- react-text: 1400 --> — <!-- /react-text --><code data-reactid="1401">.onNotIn(column, values)</code><p data-reactid="1402">Adds a onNotIn clause to the query.</p><pre class="display" data-reactid="1403"><code class="js hljs" data-reactid="1404">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).join(<span class="hljs-string">'contacts'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.on(<span class="hljs-string">'users.id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'contacts.id'</span>).onNotIn(<span class="hljs-string">'contacts.id'</span>, [<span class="hljs-number">7</span>, <span class="hljs-number">15</span>, <span class="hljs-number">23</span>, <span class="hljs-number">41</span>])
})</code><br data-reactid="1405"/><!-- react-text: 1406 -->Outputs:<!-- /react-text --><br data-reactid="1407"/><code class="sql hljs" data-reactid="1408"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">inner</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`contacts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`contacts`</span>.<span class="hljs-string">`id`</span> <span class="hljs-keyword">and</span> <span class="hljs-string">`contacts`</span>.<span class="hljs-string">`id`</span> <span class="hljs-keyword">not</span> <span class="hljs-keyword">in</span> (<span class="hljs-number">7</span>, <span class="hljs-number">15</span>, <span class="hljs-number">23</span>, <span class="hljs-number">41</span>)</code></pre></div><div id="Builder-onNull" data-reactid="1409"><b data-reactid="1410">onNull</b><!-- react-text: 1411 --> — <!-- /react-text --><code data-reactid="1412">.onNull(column)</code><p data-reactid="1413">Adds a onNull clause to the query.</p><pre class="display" data-reactid="1414"><code class="js hljs" data-reactid="1415">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).join(<span class="hljs-string">'contacts'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.on(<span class="hljs-string">'users.id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'contacts.id'</span>).onNull(<span class="hljs-string">'contacts.email'</span>)
})</code><br data-reactid="1416"/><!-- react-text: 1417 -->Outputs:<!-- /react-text --><br data-reactid="1418"/><code class="sql hljs" data-reactid="1419"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">inner</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`contacts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`contacts`</span>.<span class="hljs-string">`id`</span> <span class="hljs-keyword">and</span> <span class="hljs-string">`contacts`</span>.<span class="hljs-string">`email`</span> <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span></code></pre></div><div id="Builder-onNotNull" data-reactid="1420"><b data-reactid="1421">onNotNull</b><!-- react-text: 1422 --> — <!-- /react-text --><code data-reactid="1423">.onNotNull(column)</code><p data-reactid="1424">Adds a onNotNull clause to the query.</p><pre class="display" data-reactid="1425"><code class="js hljs" data-reactid="1426">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).join(<span class="hljs-string">'contacts'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.on(<span class="hljs-string">'users.id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'contacts.id'</span>).onNotNull(<span class="hljs-string">'contacts.email'</span>)
})</code><br data-reactid="1427"/><!-- react-text: 1428 -->Outputs:<!-- /react-text --><br data-reactid="1429"/><code class="sql hljs" data-reactid="1430"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">inner</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`contacts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`contacts`</span>.<span class="hljs-string">`id`</span> <span class="hljs-keyword">and</span> <span class="hljs-string">`contacts`</span>.<span class="hljs-string">`email`</span> <span class="hljs-keyword">is</span> <span class="hljs-keyword">not</span> <span class="hljs-literal">null</span></code></pre></div><div id="Builder-onExists" data-reactid="1431"><b data-reactid="1432">onExists</b><!-- react-text: 1433 --> — <!-- /react-text --><code data-reactid="1434">.onExists(builder | callback)</code><p data-reactid="1435">Adds a onExists clause to the query.</p><pre class="display" data-reactid="1436"><code class="js hljs" data-reactid="1437">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).join(<span class="hljs-string">'contacts'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.on(<span class="hljs-string">'users.id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'contacts.id'</span>).onExists(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'accounts'</span>).whereRaw(<span class="hljs-string">'users.account_id = accounts.id'</span>);
})
})</code><br data-reactid="1438"/><!-- react-text: 1439 -->Outputs:<!-- /react-text --><br data-reactid="1440"/><code class="sql hljs" data-reactid="1441"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">inner</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`contacts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`contacts`</span>.<span class="hljs-string">`id`</span> <span class="hljs-keyword">and</span> <span class="hljs-keyword">exists</span> (<span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">where</span> users.account_id = accounts.id)</code></pre></div><div id="Builder-onNotExists" data-reactid="1442"><b data-reactid="1443">onNotExists</b><!-- react-text: 1444 --> — <!-- /react-text --><code data-reactid="1445">.onNotExists(builder | callback)</code><p data-reactid="1446">Adds a onNotExists clause to the query.</p><pre class="display" data-reactid="1447"><code class="js hljs" data-reactid="1448">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).join(<span class="hljs-string">'contacts'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.on(<span class="hljs-string">'users.id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'contacts.id'</span>).onNotExists(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'accounts'</span>).whereRaw(<span class="hljs-string">'users.account_id = accounts.id'</span>);
})
})</code><br data-reactid="1449"/><!-- react-text: 1450 -->Outputs:<!-- /react-text --><br data-reactid="1451"/><code class="sql hljs" data-reactid="1452"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">inner</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`contacts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`contacts`</span>.<span class="hljs-string">`id`</span> <span class="hljs-keyword">and</span> <span class="hljs-keyword">not</span> <span class="hljs-keyword">exists</span> (<span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">where</span> users.account_id = accounts.id)</code></pre></div><div id="Builder-onBetween" data-reactid="1453"><b data-reactid="1454">onBetween</b><!-- react-text: 1455 --> — <!-- /react-text --><code data-reactid="1456">.onBetween(column, range)</code><p data-reactid="1457">Adds a onBetween clause to the query.</p><pre class="display" data-reactid="1458"><code class="js hljs" data-reactid="1459">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).join(<span class="hljs-string">'contacts'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.on(<span class="hljs-string">'users.id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'contacts.id'</span>).onBetween(<span class="hljs-string">'contacts.id'</span>, [<span class="hljs-number">5</span>, <span class="hljs-number">30</span>])
})</code><br data-reactid="1460"/><!-- react-text: 1461 -->Outputs:<!-- /react-text --><br data-reactid="1462"/><code class="sql hljs" data-reactid="1463"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">inner</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`contacts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`contacts`</span>.<span class="hljs-string">`id`</span> <span class="hljs-keyword">and</span> <span class="hljs-string">`contacts`</span>.<span class="hljs-string">`id`</span> <span class="hljs-keyword">between</span> <span class="hljs-number">5</span> <span class="hljs-keyword">and</span> <span class="hljs-number">30</span></code></pre></div><div id="Builder-onNotBetween" data-reactid="1464"><b data-reactid="1465">onNotBetween</b><!-- react-text: 1466 --> — <!-- /react-text --><code data-reactid="1467">.onNotBetween(column, range)</code><p data-reactid="1468">Adds a onNotBetween clause to the query.</p><pre class="display" data-reactid="1469"><code class="js hljs" data-reactid="1470">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).join(<span class="hljs-string">'contacts'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.on(<span class="hljs-string">'users.id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-string">'contacts.id'</span>).onNotBetween(<span class="hljs-string">'contacts.id'</span>, [<span class="hljs-number">5</span>, <span class="hljs-number">30</span>])
})</code><br data-reactid="1471"/><!-- react-text: 1472 -->Outputs:<!-- /react-text --><br data-reactid="1473"/><code class="sql hljs" data-reactid="1474"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">inner</span> <span class="hljs-keyword">join</span> <span class="hljs-string">`contacts`</span> <span class="hljs-keyword">on</span> <span class="hljs-string">`users`</span>.<span class="hljs-string">`id`</span> = <span class="hljs-string">`contacts`</span>.<span class="hljs-string">`id`</span> <span class="hljs-keyword">and</span> <span class="hljs-string">`contacts`</span>.<span class="hljs-string">`id`</span> <span class="hljs-keyword">not</span> <span class="hljs-keyword">between</span> <span class="hljs-number">5</span> <span class="hljs-keyword">and</span> <span class="hljs-number">30</span></code></pre></div><h3 id="Builder-clear" data-reactid="1475">ClearClauses</h3><div id="Builder-clearSelect" data-reactid="1476"><b data-reactid="1477">clearSelect</b><!-- react-text: 1478 --> — <!-- /react-text --><code data-reactid="1479">.clearSelect()</code><p data-reactid="1480">Clears all select clauses from the query, excluding subqueries.</p><pre class="display" data-reactid="1481"><code class="js hljs" data-reactid="1482">knex.select(<span class="hljs-string">'email'</span>, <span class="hljs-string">'name'</span>).from(<span class="hljs-string">'users'</span>).clearSelect()</code><br data-reactid="1483"/><!-- react-text: 1484 -->Outputs:<!-- /react-text --><br data-reactid="1485"/><code class="sql hljs" data-reactid="1486"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre></div><div id="Builder-clearWhere" data-reactid="1487"><b data-reactid="1488">clearWhere</b><!-- react-text: 1489 --> — <!-- /react-text --><code data-reactid="1490">.clearWhere()</code><p data-reactid="1491">Clears all where clauses from the query, excluding subqueries.</p><pre class="display" data-reactid="1492"><code class="js hljs" data-reactid="1493">knex.select(<span class="hljs-string">'email'</span>, <span class="hljs-string">'name'</span>).from(<span class="hljs-string">'users'</span>).where(<span class="hljs-string">'id'</span>, <span class="hljs-number">1</span>).clearWhere()</code><br data-reactid="1494"/><!-- react-text: 1495 -->Outputs:<!-- /react-text --><br data-reactid="1496"/><code class="sql hljs" data-reactid="1497"><span class="hljs-keyword">select</span> <span class="hljs-string">`email`</span>, <span class="hljs-string">`name`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre></div><div id="Builder-clearOrder" data-reactid="1498"><b data-reactid="1499">clearOrder</b><!-- react-text: 1500 --> — <!-- /react-text --><code data-reactid="1501">.clearOrder()</code><p data-reactid="1502">Clears all order clauses from the query, excluding subqueries.</p><pre class="display" data-reactid="1503"><code class="js hljs" data-reactid="1504">knex.select().from(<span class="hljs-string">'users'</span>).orderBy(<span class="hljs-string">'name'</span>, <span class="hljs-string">'desc'</span>).clearOrder()</code><br data-reactid="1505"/><!-- react-text: 1506 -->Outputs:<!-- /react-text --><br data-reactid="1507"/><code class="sql hljs" data-reactid="1508"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre></div><div id="Builder-clearHaving" data-reactid="1509"><b data-reactid="1510">clearHaving</b><!-- react-text: 1511 --> — <!-- /react-text --><code data-reactid="1512">.clearHaving()</code><p data-reactid="1513">Clears all having clauses from the query, excluding subqueries.</p><pre class="display" data-reactid="1514"><code class="js hljs" data-reactid="1515">knex.select().from(<span class="hljs-string">'users'</span>).having(<span class="hljs-string">'id'</span>, <span class="hljs-string">'>'</span>, <span class="hljs-number">5</span>).clearHaving()</code><br data-reactid="1516"/><!-- react-text: 1517 -->Outputs:<!-- /react-text --><br data-reactid="1518"/><code class="sql hljs" data-reactid="1519"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre></div><div id="Builder-clearCounters" data-reactid="1520"><b data-reactid="1521">clearCounters</b><!-- react-text: 1522 --> — <!-- /react-text --><code data-reactid="1523">.clearCounters()</code><p data-reactid="1524">Clears all increments/decrements clauses from the query.</p><pre class="display" data-reactid="1525"><code class="js hljs" data-reactid="1526">knex(<span class="hljs-string">'accounts'</span>)
.where(<span class="hljs-string">'id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-number">1</span>)
.update({ <span class="hljs-attr">email</span>: <span class="hljs-string">'foo@bar.com'</span> })
.decrement({
<span class="hljs-attr">balance</span>: <span class="hljs-number">50</span>,
})
.clearCounters()</code><br data-reactid="1527"/><!-- react-text: 1528 -->Outputs:<!-- /react-text --><br data-reactid="1529"/><code class="sql hljs" data-reactid="1530"><span class="hljs-keyword">update</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">set</span> <span class="hljs-string">`email`</span> = <span class="hljs-string">'foo@bar.com'</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`id`</span> = <span class="hljs-number">1</span></code></pre></div><div id="Builder-distinct" data-reactid="1531"><b data-reactid="1532">distinct</b><!-- react-text: 1533 --> — <!-- /react-text --><code data-reactid="1534">.distinct([*columns])</code><p data-reactid="1535">Sets a distinct clause on the query. If the parameter is falsy or empty array, method falls back to '*'.</p><pre class="display" data-reactid="1536"><code class="js hljs" data-reactid="1537"><span class="hljs-comment">// select distinct 'first_name' from customers</span>
knex(<span class="hljs-string">'customers'</span>)
.distinct(<span class="hljs-string">'first_name'</span>, <span class="hljs-string">'last_name'</span>)</code><br data-reactid="1538"/><!-- react-text: 1539 -->Outputs:<!-- /react-text --><br data-reactid="1540"/><code class="sql hljs" data-reactid="1541"><span class="hljs-keyword">select</span> <span class="hljs-keyword">distinct</span> <span class="hljs-string">`first_name`</span>, <span class="hljs-string">`last_name`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`customers`</span></code></pre><pre class="display" data-reactid="1542"><code class="js hljs" data-reactid="1543"><span class="hljs-comment">// select which eleminates duplicate rows</span>
knex(<span class="hljs-string">'customers'</span>)
.distinct()</code><br data-reactid="1544"/><!-- react-text: 1545 -->Outputs:<!-- /react-text --><br data-reactid="1546"/><code class="sql hljs" data-reactid="1547"><span class="hljs-keyword">select</span> <span class="hljs-keyword">distinct</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`customers`</span></code></pre></div><div id="Builder-groupBy" data-reactid="1548"><b data-reactid="1549">groupBy</b><!-- react-text: 1550 --> — <!-- /react-text --><code data-reactid="1551">.groupBy(*names)</code><p data-reactid="1552">Adds a group by clause to the query.</p><pre class="display" data-reactid="1553"><code class="js hljs" data-reactid="1554">knex(<span class="hljs-string">'users'</span>).groupBy(<span class="hljs-string">'count'</span>)</code><br data-reactid="1555"/><!-- react-text: 1556 -->Outputs:<!-- /react-text --><br data-reactid="1557"/><code class="sql hljs" data-reactid="1558"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">group</span> <span class="hljs-keyword">by</span> <span class="hljs-string">`count`</span></code></pre></div><div id="Builder-groupByRaw" data-reactid="1559"><b data-reactid="1560">groupByRaw</b><!-- react-text: 1561 --> — <!-- /react-text --><code data-reactid="1562">.groupByRaw(sql)</code><p data-reactid="1563">Adds a raw group by clause to the query.</p><pre class="display" data-reactid="1564"><code class="js hljs" data-reactid="1565">knex.select(<span class="hljs-string">'year'</span>, knex.raw(<span class="hljs-string">'SUM(profit)'</span>)).from(<span class="hljs-string">'sales'</span>).groupByRaw(<span class="hljs-string">'year WITH ROLLUP'</span>)</code><br data-reactid="1566"/><!-- react-text: 1567 -->Outputs:<!-- /react-text --><br data-reactid="1568"/><code class="sql hljs" data-reactid="1569"><span class="hljs-keyword">select</span> <span class="hljs-string">`year`</span>, <span class="hljs-keyword">SUM</span>(profit) <span class="hljs-keyword">from</span> <span class="hljs-string">`sales`</span> <span class="hljs-keyword">group</span> <span class="hljs-keyword">by</span> <span class="hljs-keyword">year</span> <span class="hljs-keyword">WITH</span> <span class="hljs-keyword">ROLLUP</span></code></pre></div><div id="Builder-orderBy" data-reactid="1570"><b data-reactid="1571">orderBy</b><!-- react-text: 1572 --> — <!-- /react-text --><code data-reactid="1573">.orderBy(column|columns, [direction])</code><p data-reactid="1574">Adds an order by clause to the query. column can be string, or list mixed with string and object.</p><p data-reactid="1575">Single Column:</p><pre class="display" data-reactid="1576"><code class="js hljs" data-reactid="1577">knex(<span class="hljs-string">'users'</span>).orderBy(<span class="hljs-string">'email'</span>)</code><br data-reactid="1578"/><!-- react-text: 1579 -->Outputs:<!-- /react-text --><br data-reactid="1580"/><code class="sql hljs" data-reactid="1581"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">order</span> <span class="hljs-keyword">by</span> <span class="hljs-string">`email`</span> <span class="hljs-keyword">asc</span></code></pre><pre class="display" data-reactid="1582"><code class="js hljs" data-reactid="1583">knex(<span class="hljs-string">'users'</span>).orderBy(<span class="hljs-string">'name'</span>, <span class="hljs-string">'desc'</span>)</code><br data-reactid="1584"/><!-- react-text: 1585 -->Outputs:<!-- /react-text --><br data-reactid="1586"/><code class="sql hljs" data-reactid="1587"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">order</span> <span class="hljs-keyword">by</span> <span class="hljs-string">`name`</span> <span class="hljs-keyword">desc</span></code></pre><p data-reactid="1588">Multiple Columns:</p><pre class="display" data-reactid="1589"><code class="js hljs" data-reactid="1590">knex(<span class="hljs-string">'users'</span>).orderBy([<span class="hljs-string">'email'</span>, { <span class="hljs-attr">column</span>: <span class="hljs-string">'age'</span>, <span class="hljs-attr">order</span>: <span class="hljs-string">'desc'</span> }])</code><br data-reactid="1591"/><!-- react-text: 1592 -->Outputs:<!-- /react-text --><br data-reactid="1593"/><code class="sql hljs" data-reactid="1594"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">order</span> <span class="hljs-keyword">by</span> <span class="hljs-string">`email`</span> <span class="hljs-keyword">asc</span>, <span class="hljs-string">`age`</span> <span class="hljs-keyword">desc</span></code></pre><pre class="display" data-reactid="1595"><code class="js hljs" data-reactid="1596">knex(<span class="hljs-string">'users'</span>).orderBy([{ <span class="hljs-attr">column</span>: <span class="hljs-string">'email'</span> }, { <span class="hljs-attr">column</span>: <span class="hljs-string">'age'</span>, <span class="hljs-attr">order</span>: <span class="hljs-string">'desc'</span> }])</code><br data-reactid="1597"/><!-- react-text: 1598 -->Outputs:<!-- /react-text --><br data-reactid="1599"/><code class="sql hljs" data-reactid="1600"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">order</span> <span class="hljs-keyword">by</span> <span class="hljs-string">`email`</span> <span class="hljs-keyword">asc</span>, <span class="hljs-string">`age`</span> <span class="hljs-keyword">desc</span></code></pre></div><div id="Builder-orderByRaw" data-reactid="1601"><b data-reactid="1602">orderByRaw</b><!-- react-text: 1603 --> — <!-- /react-text --><code data-reactid="1604">.orderByRaw(sql)</code><p data-reactid="1605">Adds an order by raw clause to the query.</p><pre class="display" data-reactid="1606"><code class="js hljs" data-reactid="1607">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'table'</span>).orderByRaw(<span class="hljs-string">'col DESC NULLS LAST'</span>)</code><br data-reactid="1608"/><!-- react-text: 1609 -->Outputs:<!-- /react-text --><br data-reactid="1610"/><code class="sql hljs" data-reactid="1611"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`table`</span> <span class="hljs-keyword">order</span> <span class="hljs-keyword">by</span> <span class="hljs-keyword">col</span> <span class="hljs-keyword">DESC</span> <span class="hljs-keyword">NULLS</span> <span class="hljs-keyword">LAST</span></code></pre></div><h3 id="Builder-havings" data-reactid="1612">Having Clauses</h3><div id="Builder-having" data-reactid="1613"><b data-reactid="1614">having</b><!-- react-text: 1615 --> — <!-- /react-text --><code data-reactid="1616">.having(column, operator, value)</code><p data-reactid="1617">Adds a having clause to the query.</p><pre class="display" data-reactid="1618"><code class="js hljs" data-reactid="1619">knex(<span class="hljs-string">'users'</span>)
.groupBy(<span class="hljs-string">'count'</span>)
.orderBy(<span class="hljs-string">'name'</span>, <span class="hljs-string">'desc'</span>)
.having(<span class="hljs-string">'count'</span>, <span class="hljs-string">'>'</span>, <span class="hljs-number">100</span>)</code><br data-reactid="1620"/><!-- react-text: 1621 -->Outputs:<!-- /react-text --><br data-reactid="1622"/><code class="sql hljs" data-reactid="1623"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">group</span> <span class="hljs-keyword">by</span> <span class="hljs-string">`count`</span> <span class="hljs-keyword">having</span> <span class="hljs-string">`count`</span> > <span class="hljs-number">100</span> <span class="hljs-keyword">order</span> <span class="hljs-keyword">by</span> <span class="hljs-string">`name`</span> <span class="hljs-keyword">desc</span></code></pre></div><div id="Builder-havingIn" data-reactid="1624"><b data-reactid="1625">havingIn</b><!-- react-text: 1626 --> — <!-- /react-text --><code data-reactid="1627">.havingIn(column, values)</code><p data-reactid="1628">Adds a havingIn clause to the query.</p><pre class="display" data-reactid="1629"><code class="js hljs" data-reactid="1630">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).havingIn(<span class="hljs-string">'id'</span>, [<span class="hljs-number">5</span>, <span class="hljs-number">3</span>, <span class="hljs-number">10</span>, <span class="hljs-number">17</span>])</code><br data-reactid="1631"/><!-- react-text: 1632 -->Outputs:<!-- /react-text --><br data-reactid="1633"/><code class="sql hljs" data-reactid="1634"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">having</span> <span class="hljs-string">`id`</span> <span class="hljs-keyword">in</span> (<span class="hljs-number">5</span>, <span class="hljs-number">3</span>, <span class="hljs-number">10</span>, <span class="hljs-number">17</span>)</code></pre></div><div id="Builder-havingNotIn" data-reactid="1635"><b data-reactid="1636">havingNotIn</b><!-- react-text: 1637 --> — <!-- /react-text --><code data-reactid="1638">.havingNotIn(column, values)</code><p data-reactid="1639">Adds a havingNotIn clause to the query.</p><pre class="display" data-reactid="1640"><code class="js hljs" data-reactid="1641">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).havingNotIn(<span class="hljs-string">'id'</span>, [<span class="hljs-number">5</span>, <span class="hljs-number">3</span>, <span class="hljs-number">10</span>, <span class="hljs-number">17</span>])</code><br data-reactid="1642"/><!-- react-text: 1643 -->Outputs:<!-- /react-text --><br data-reactid="1644"/><code class="sql hljs" data-reactid="1645"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">having</span> <span class="hljs-string">`id`</span> <span class="hljs-keyword">not</span> <span class="hljs-keyword">in</span> (<span class="hljs-number">5</span>, <span class="hljs-number">3</span>, <span class="hljs-number">10</span>, <span class="hljs-number">17</span>)</code></pre></div><div id="Builder-havingNull" data-reactid="1646"><b data-reactid="1647">havingNull</b><!-- react-text: 1648 --> — <!-- /react-text --><code data-reactid="1649">.havingNull(column)</code><p data-reactid="1650">Adds a havingNull clause to the query.</p><pre class="display" data-reactid="1651"><code class="js hljs" data-reactid="1652">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).havingNull(<span class="hljs-string">'email'</span>)</code><br data-reactid="1653"/><!-- react-text: 1654 -->Outputs:<!-- /react-text --><br data-reactid="1655"/><code class="sql hljs" data-reactid="1656"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">having</span> <span class="hljs-string">`email`</span> <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span></code></pre></div><div id="Builder-havingNotNull" data-reactid="1657"><b data-reactid="1658">havingNotNull</b><!-- react-text: 1659 --> — <!-- /react-text --><code data-reactid="1660">.havingNotNull(column)</code><p data-reactid="1661">Adds a havingNotNull clause to the query.</p><pre class="display" data-reactid="1662"><code class="js hljs" data-reactid="1663">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).havingNotNull(<span class="hljs-string">'email'</span>)</code><br data-reactid="1664"/><!-- react-text: 1665 -->Outputs:<!-- /react-text --><br data-reactid="1666"/><code class="sql hljs" data-reactid="1667"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">having</span> <span class="hljs-string">`email`</span> <span class="hljs-keyword">is</span> <span class="hljs-keyword">not</span> <span class="hljs-literal">null</span></code></pre></div><div id="Builder-havingExists" data-reactid="1668"><b data-reactid="1669">havingExists</b><!-- react-text: 1670 --> — <!-- /react-text --><code data-reactid="1671">.havingExists(builder | callback)</code><p data-reactid="1672">Adds a havingExists clause to the query.</p><pre class="display" data-reactid="1673"><code class="js hljs" data-reactid="1674">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).havingExists(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'accounts'</span>).whereRaw(<span class="hljs-string">'users.account_id = accounts.id'</span>);
})</code><br data-reactid="1675"/><!-- react-text: 1676 -->Outputs:<!-- /react-text --><br data-reactid="1677"/><code class="sql hljs" data-reactid="1678"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">having</span> <span class="hljs-keyword">exists</span> (<span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">where</span> users.account_id = accounts.id)</code></pre></div><div id="Builder-havingNotExists" data-reactid="1679"><b data-reactid="1680">havingNotExists</b><!-- react-text: 1681 --> — <!-- /react-text --><code data-reactid="1682">.havingNotExists(builder | callback)</code><p data-reactid="1683">Adds a havingNotExists clause to the query.</p><pre class="display" data-reactid="1684"><code class="js hljs" data-reactid="1685">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).havingNotExists(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'accounts'</span>).whereRaw(<span class="hljs-string">'users.account_id = accounts.id'</span>);
})</code><br data-reactid="1686"/><!-- react-text: 1687 -->Outputs:<!-- /react-text --><br data-reactid="1688"/><code class="sql hljs" data-reactid="1689"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">having</span> <span class="hljs-keyword">not</span> <span class="hljs-keyword">exists</span> (<span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">where</span> users.account_id = accounts.id)</code></pre></div><div id="Builder-havingBetween" data-reactid="1690"><b data-reactid="1691">havingBetween</b><!-- react-text: 1692 --> — <!-- /react-text --><code data-reactid="1693">.havingBetween(column, range)</code><p data-reactid="1694">Adds a havingBetween clause to the query.</p><pre class="display" data-reactid="1695"><code class="js hljs" data-reactid="1696">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).havingBetween(<span class="hljs-string">'id'</span>, [<span class="hljs-number">5</span>, <span class="hljs-number">10</span>])</code><br data-reactid="1697"/><!-- react-text: 1698 -->Outputs:<!-- /react-text --><br data-reactid="1699"/><code class="sql hljs" data-reactid="1700"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">having</span> <span class="hljs-string">`id`</span> <span class="hljs-keyword">between</span> <span class="hljs-number">5</span> <span class="hljs-keyword">and</span> <span class="hljs-number">10</span></code></pre></div><div id="Builder-havingNotBetween" data-reactid="1701"><b data-reactid="1702">havingNotBetween</b><!-- react-text: 1703 --> — <!-- /react-text --><code data-reactid="1704">.havingNotBetween(column, range)</code><p data-reactid="1705">Adds a havingNotBetween clause to the query.</p><pre class="display" data-reactid="1706"><code class="js hljs" data-reactid="1707">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).havingNotBetween(<span class="hljs-string">'id'</span>, [<span class="hljs-number">5</span>, <span class="hljs-number">10</span>])</code><br data-reactid="1708"/><!-- react-text: 1709 -->Outputs:<!-- /react-text --><br data-reactid="1710"/><code class="sql hljs" data-reactid="1711"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">having</span> <span class="hljs-string">`id`</span> <span class="hljs-keyword">not</span> <span class="hljs-keyword">between</span> <span class="hljs-number">5</span> <span class="hljs-keyword">and</span> <span class="hljs-number">10</span></code></pre></div><div id="Builder-havingRaw" data-reactid="1712"><b data-reactid="1713">havingRaw</b><!-- react-text: 1714 --> — <!-- /react-text --><code data-reactid="1715">.havingRaw(column, operator, value)</code><p data-reactid="1716">Adds a havingRaw clause to the query.</p><pre class="display" data-reactid="1717"><code class="js hljs" data-reactid="1718">knex(<span class="hljs-string">'users'</span>)
.groupBy(<span class="hljs-string">'count'</span>)
.orderBy(<span class="hljs-string">'name'</span>, <span class="hljs-string">'desc'</span>)
.havingRaw(<span class="hljs-string">'count > ?'</span>, [<span class="hljs-number">100</span>])</code><br data-reactid="1719"/><!-- react-text: 1720 -->Outputs:<!-- /react-text --><br data-reactid="1721"/><code class="sql hljs" data-reactid="1722"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">group</span> <span class="hljs-keyword">by</span> <span class="hljs-string">`count`</span> <span class="hljs-keyword">having</span> <span class="hljs-keyword">count</span> > <span class="hljs-number">100</span> <span class="hljs-keyword">order</span> <span class="hljs-keyword">by</span> <span class="hljs-string">`name`</span> <span class="hljs-keyword">desc</span></code></pre></div><div id="Builder-offset" data-reactid="1723"><b data-reactid="1724">offset</b><!-- react-text: 1725 --> — <!-- /react-text --><code data-reactid="1726">.offset(value)</code><p data-reactid="1727">Adds an offset clause to the query.</p><pre class="display" data-reactid="1728"><code class="js hljs" data-reactid="1729">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).offset(<span class="hljs-number">10</span>)</code><br data-reactid="1730"/><!-- react-text: 1731 -->Outputs:<!-- /react-text --><br data-reactid="1732"/><code class="sql hljs" data-reactid="1733"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">limit</span> <span class="hljs-number">18446744073709551615</span> <span class="hljs-keyword">offset</span> <span class="hljs-number">10</span></code></pre></div><div id="Builder-limit" data-reactid="1734"><b data-reactid="1735">limit</b><!-- react-text: 1736 --> — <!-- /react-text --><code data-reactid="1737">.limit(value)</code><p data-reactid="1738">Adds a limit clause to the query.</p><pre class="display" data-reactid="1739"><code class="js hljs" data-reactid="1740">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).limit(<span class="hljs-number">10</span>).offset(<span class="hljs-number">30</span>)</code><br data-reactid="1741"/><!-- react-text: 1742 -->Outputs:<!-- /react-text --><br data-reactid="1743"/><code class="sql hljs" data-reactid="1744"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">limit</span> <span class="hljs-number">10</span> <span class="hljs-keyword">offset</span> <span class="hljs-number">30</span></code></pre></div><div id="Builder-union" data-reactid="1745"><b data-reactid="1746">union</b><!-- react-text: 1747 --> — <!-- /react-text --><code data-reactid="1748">.union([*queries], [wrap])</code><p data-reactid="1749">Creates a union query, taking an array or a list of callbacks, builders, or raw statements to build the union statement, with optional boolean wrap. If the <code>wrap</code> parameter is <code>true</code>, the queries will be individually wrapped in parentheses.</p><pre class="display" data-reactid="1750"><code class="js hljs" data-reactid="1751">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).whereNull(<span class="hljs-string">'last_name'</span>).union(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).whereNull(<span class="hljs-string">'first_name'</span>)
})</code><br data-reactid="1752"/><!-- react-text: 1753 -->Outputs:<!-- /react-text --><br data-reactid="1754"/><code class="sql hljs" data-reactid="1755"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`last_name`</span> <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span> <span class="hljs-keyword">union</span> <span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`first_name`</span> <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span></code></pre><pre class="display" data-reactid="1756"><code class="js hljs" data-reactid="1757">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).whereNull(<span class="hljs-string">'last_name'</span>).union([
knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).whereNull(<span class="hljs-string">'first_name'</span>)
])</code><br data-reactid="1758"/><!-- react-text: 1759 -->Outputs:<!-- /react-text --><br data-reactid="1760"/><code class="sql hljs" data-reactid="1761"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`last_name`</span> <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span> <span class="hljs-keyword">union</span> <span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`first_name`</span> <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span></code></pre><pre class="display" data-reactid="1762"><code class="js hljs" data-reactid="1763">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).whereNull(<span class="hljs-string">'last_name'</span>).union(
knex.raw(<span class="hljs-string">'select * from users where first_name is null'</span>),
knex.raw(<span class="hljs-string">'select * from users where email is null'</span>)
)</code><br data-reactid="1764"/><!-- react-text: 1765 -->Outputs:<!-- /react-text --><br data-reactid="1766"/><code class="sql hljs" data-reactid="1767"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`last_name`</span> <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span> <span class="hljs-keyword">union</span> <span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-keyword">users</span> <span class="hljs-keyword">where</span> first_name <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span> <span class="hljs-keyword">union</span> <span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-keyword">users</span> <span class="hljs-keyword">where</span> email <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span></code></pre></div><div id="Builder-unionAll" data-reactid="1768"><b data-reactid="1769">unionAll</b><!-- react-text: 1770 --> — <!-- /react-text --><code data-reactid="1771">.unionAll([*queries], [wrap])</code><p data-reactid="1772">Creates a union all query, with the same method signature as the union method. If the <code>wrap</code> parameter is <code>true</code>, the queries will be individually wrapped in parentheses.</p><pre class="display" data-reactid="1773"><code class="js hljs" data-reactid="1774">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).whereNull(<span class="hljs-string">'last_name'</span>).unionAll(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).whereNull(<span class="hljs-string">'first_name'</span>);
})</code><br data-reactid="1775"/><!-- react-text: 1776 -->Outputs:<!-- /react-text --><br data-reactid="1777"/><code class="sql hljs" data-reactid="1778"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`last_name`</span> <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span> <span class="hljs-keyword">union</span> all <span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`first_name`</span> <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span></code></pre><pre class="display" data-reactid="1779"><code class="js hljs" data-reactid="1780">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).whereNull(<span class="hljs-string">'last_name'</span>).unionAll([
knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).whereNull(<span class="hljs-string">'first_name'</span>)
])</code><br data-reactid="1781"/><!-- react-text: 1782 -->Outputs:<!-- /react-text --><br data-reactid="1783"/><code class="sql hljs" data-reactid="1784"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`last_name`</span> <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span> <span class="hljs-keyword">union</span> all <span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`first_name`</span> <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span></code></pre><pre class="display" data-reactid="1785"><code class="js hljs" data-reactid="1786">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).whereNull(<span class="hljs-string">'last_name'</span>).unionAll(
knex.raw(<span class="hljs-string">'select * from users where first_name is null'</span>),
knex.raw(<span class="hljs-string">'select * from users where email is null'</span>)
)</code><br data-reactid="1787"/><!-- react-text: 1788 -->Outputs:<!-- /react-text --><br data-reactid="1789"/><code class="sql hljs" data-reactid="1790"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`last_name`</span> <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span> <span class="hljs-keyword">union</span> all <span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-keyword">users</span> <span class="hljs-keyword">where</span> first_name <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span> <span class="hljs-keyword">union</span> all <span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-keyword">users</span> <span class="hljs-keyword">where</span> email <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span></code></pre></div><div id="Builder-intersect" data-reactid="1791"><b data-reactid="1792">intersect</b><!-- react-text: 1793 --> — <!-- /react-text --><code data-reactid="1794">.intersect([*queries], [wrap])</code><p data-reactid="1795">Creates an intersect query, taking an array or a list of callbacks, builders, or raw statements to build the intersect statement, with optional boolean wrap. If the <code>wrap</code> parameter is <code>true</code>, the queries will be individually wrapped in parentheses. The intersect method is unsupported on MySQL.</p><pre class="display" data-reactid="1796"><code class="js hljs" data-reactid="1797">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).whereNull(<span class="hljs-string">'last_name'</span>).intersect(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).whereNull(<span class="hljs-string">'first_name'</span>)
})</code><br data-reactid="1798"/><!-- react-text: 1799 -->Outputs:<!-- /react-text --><br data-reactid="1800"/><code class="sql hljs" data-reactid="1801"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`last_name`</span> <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span> <span class="hljs-keyword">intersect</span> <span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`first_name`</span> <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span></code></pre><pre class="display" data-reactid="1802"><code class="js hljs" data-reactid="1803">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).whereNull(<span class="hljs-string">'last_name'</span>).intersect([
knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).whereNull(<span class="hljs-string">'first_name'</span>)
])</code><br data-reactid="1804"/><!-- react-text: 1805 -->Outputs:<!-- /react-text --><br data-reactid="1806"/><code class="sql hljs" data-reactid="1807"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`last_name`</span> <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span> <span class="hljs-keyword">intersect</span> <span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`first_name`</span> <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span></code></pre><pre class="display" data-reactid="1808"><code class="js hljs" data-reactid="1809">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).whereNull(<span class="hljs-string">'last_name'</span>).intersect(
knex.raw(<span class="hljs-string">'select * from users where first_name is null'</span>),
knex.raw(<span class="hljs-string">'select * from users where email is null'</span>)
)</code><br data-reactid="1810"/><!-- react-text: 1811 -->Outputs:<!-- /react-text --><br data-reactid="1812"/><code class="sql hljs" data-reactid="1813"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`last_name`</span> <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span> <span class="hljs-keyword">intersect</span> <span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-keyword">users</span> <span class="hljs-keyword">where</span> first_name <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span> <span class="hljs-keyword">intersect</span> <span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-keyword">users</span> <span class="hljs-keyword">where</span> email <span class="hljs-keyword">is</span> <span class="hljs-literal">null</span></code></pre></div><div id="Builder-insert" data-reactid="1814"><b data-reactid="1815">insert</b><!-- react-text: 1816 --> — <!-- /react-text --><code data-reactid="1817">.insert(data, [returning])</code><p data-reactid="1818">Creates an insert query, taking either a hash of properties to be inserted into the row, or an array of inserts, to be executed as a single insert command. If returning array is passed e.g. ['id', 'title'], it resolves the promise / fulfills the callback with an array of all the added rows with specified columns. It's a shortcut for <a href="#Builder-returning">returning method</a></p><pre class="display" data-reactid="1819"><code class="js hljs" data-reactid="1820"><span class="hljs-comment">// Returns [1] in "mysql", "sqlite", "oracle"; [] in "postgresql" unless the 'returning' parameter is set.</span>
knex(<span class="hljs-string">'books'</span>).insert({<span class="hljs-attr">title</span>: <span class="hljs-string">'Slaughterhouse Five'</span>})</code><br data-reactid="1821"/><!-- react-text: 1822 -->Outputs:<!-- /react-text --><br data-reactid="1823"/><code class="sql hljs" data-reactid="1824"><span class="hljs-keyword">insert</span> <span class="hljs-keyword">into</span> <span class="hljs-string">`books`</span> (<span class="hljs-string">`title`</span>) <span class="hljs-keyword">values</span> (<span class="hljs-string">'Slaughterhouse Five'</span>)</code></pre><pre class="display" data-reactid="1825"><code class="js hljs" data-reactid="1826"><span class="hljs-comment">// Normalizes for empty keys on multi-row insert:</span>
knex(<span class="hljs-string">'coords'</span>).insert([{<span class="hljs-attr">x</span>: <span class="hljs-number">20</span>}, {<span class="hljs-attr">y</span>: <span class="hljs-number">30</span>}, {<span class="hljs-attr">x</span>: <span class="hljs-number">10</span>, <span class="hljs-attr">y</span>: <span class="hljs-number">20</span>}])</code><br data-reactid="1827"/><!-- react-text: 1828 -->Outputs:<!-- /react-text --><br data-reactid="1829"/><code class="sql hljs" data-reactid="1830"><span class="hljs-keyword">insert</span> <span class="hljs-keyword">into</span> <span class="hljs-string">`coords`</span> (<span class="hljs-string">`x`</span>, <span class="hljs-string">`y`</span>) <span class="hljs-keyword">values</span> (<span class="hljs-number">20</span>, <span class="hljs-keyword">DEFAULT</span>), (<span class="hljs-keyword">DEFAULT</span>, <span class="hljs-number">30</span>), (<span class="hljs-number">10</span>, <span class="hljs-number">20</span>)</code></pre><pre class="display" data-reactid="1831"><code class="js hljs" data-reactid="1832"><span class="hljs-comment">// Returns [2] in "mysql", "sqlite"; [2, 3] in "postgresql"</span>
knex.insert([{<span class="hljs-attr">title</span>: <span class="hljs-string">'Great Gatsby'</span>}, {<span class="hljs-attr">title</span>: <span class="hljs-string">'Fahrenheit 451'</span>}], [<span class="hljs-string">'id'</span>]).into(<span class="hljs-string">'books'</span>)</code><br data-reactid="1833"/><!-- react-text: 1834 -->Outputs:<!-- /react-text --><br data-reactid="1835"/><code class="sql hljs" data-reactid="1836"><span class="hljs-keyword">insert</span> <span class="hljs-keyword">into</span> <span class="hljs-string">`books`</span> (<span class="hljs-string">`title`</span>) <span class="hljs-keyword">values</span> (<span class="hljs-string">'Great Gatsby'</span>), (<span class="hljs-string">'Fahrenheit 451'</span>)</code></pre></div><p data-reactid="1837">If one prefers that undefined keys are replaced with <code>NULL</code> instead of <code>DEFAULT</code> one may give <code>useNullAsDefault</code> configuration parameter in knex config.</p><pre data-reactid="1838"><code class="hljs js" data-reactid="1839"><span class="hljs-keyword">var</span> knex = <span class="hljs-built_in">require</span>(<span class="hljs-string">'knex'</span>)({
<span class="hljs-attr">client</span>: <span class="hljs-string">'mysql'</span>,
<span class="hljs-attr">connection</span>: {
<span class="hljs-attr">host</span> : <span class="hljs-string">'127.0.0.1'</span>,
<span class="hljs-attr">user</span> : <span class="hljs-string">'your_database_user'</span>,
<span class="hljs-attr">password</span> : <span class="hljs-string">'your_database_password'</span>,
<span class="hljs-attr">database</span> : <span class="hljs-string">'myapp_test'</span>
},
<span class="hljs-attr">useNullAsDefault</span>: <span class="hljs-literal">true</span>
});
knex(<span class="hljs-string">'coords'</span>).insert([{<span class="hljs-attr">x</span>: <span class="hljs-number">20</span>}, {<span class="hljs-attr">y</span>: <span class="hljs-number">30</span>}, {<span class="hljs-attr">x</span>: <span class="hljs-number">10</span>, <span class="hljs-attr">y</span>: <span class="hljs-number">20</span>}])
<span class="hljs-comment">// insert into `coords` (`x`, `y`) values (20, NULL), (NULL, 30), (10, 20)"</span></code></pre><div id="Builder-returning" data-reactid="1840"><b data-reactid="1841">returning</b><!-- react-text: 1842 --> — <!-- /react-text --><code data-reactid="1843">.returning(column) / .returning([column1, column2, ...])</code><p data-reactid="1844">Utilized by PostgreSQL, MSSQL, and Oracle databases, the returning method specifies which column should be returned by the insert and update methods. Passed column parameter may be a string or an array of strings. When passed in a string, makes the SQL result be reported as an array of values from the specified column. When passed in an array of strings, makes the SQL result be reported as an array of objects, each containing a single property for each of the specified columns. The returning method is not supported on Amazon Redshift.</p><pre class="display" data-reactid="1845"><code class="js hljs" data-reactid="1846"><span class="hljs-comment">// Returns [1]</span>
knex(<span class="hljs-string">'books'</span>)
.returning(<span class="hljs-string">'id'</span>)
.insert({<span class="hljs-attr">title</span>: <span class="hljs-string">'Slaughterhouse Five'</span>})</code><br data-reactid="1847"/><!-- react-text: 1848 -->Outputs:<!-- /react-text --><br data-reactid="1849"/><code class="sql hljs" data-reactid="1850"><span class="hljs-keyword">insert</span> <span class="hljs-keyword">into</span> <span class="hljs-string">`books`</span> (<span class="hljs-string">`title`</span>) <span class="hljs-keyword">values</span> (<span class="hljs-string">'Slaughterhouse Five'</span>)</code></pre><pre class="display" data-reactid="1851"><code class="js hljs" data-reactid="1852"><span class="hljs-comment">// Returns [2] in "mysql", "sqlite"; [2, 3] in "postgresql"</span>
knex(<span class="hljs-string">'books'</span>)
.returning(<span class="hljs-string">'id'</span>)
.insert([{<span class="hljs-attr">title</span>: <span class="hljs-string">'Great Gatsby'</span>}, {<span class="hljs-attr">title</span>: <span class="hljs-string">'Fahrenheit 451'</span>}])</code><br data-reactid="1853"/><!-- react-text: 1854 -->Outputs:<!-- /react-text --><br data-reactid="1855"/><code class="sql hljs" data-reactid="1856"><span class="hljs-keyword">insert</span> <span class="hljs-keyword">into</span> <span class="hljs-string">`books`</span> (<span class="hljs-string">`title`</span>) <span class="hljs-keyword">values</span> (<span class="hljs-string">'Great Gatsby'</span>), (<span class="hljs-string">'Fahrenheit 451'</span>)</code></pre><pre class="display" data-reactid="1857"><code class="js hljs" data-reactid="1858"><span class="hljs-comment">// Returns [ { id: 1, title: 'Slaughterhouse Five' } ]</span>
knex(<span class="hljs-string">'books'</span>)
.returning([<span class="hljs-string">'id'</span>,<span class="hljs-string">'title'</span>])
.insert({<span class="hljs-attr">title</span>: <span class="hljs-string">'Slaughterhouse Five'</span>})</code><br data-reactid="1859"/><!-- react-text: 1860 -->Outputs:<!-- /react-text --><br data-reactid="1861"/><code class="sql hljs" data-reactid="1862"><span class="hljs-keyword">insert</span> <span class="hljs-keyword">into</span> <span class="hljs-string">`books`</span> (<span class="hljs-string">`title`</span>) <span class="hljs-keyword">values</span> (<span class="hljs-string">'Slaughterhouse Five'</span>)</code></pre></div><div id="Builder-update" data-reactid="1863"><b data-reactid="1864">update</b><!-- react-text: 1865 --> — <!-- /react-text --><code data-reactid="1866">.update(data, [returning]) / .update(key, value, [returning])</code><p data-reactid="1867">Creates an update query, taking a hash of properties or a key/value pair to be updated based on the other query constraints. If returning array is passed e.g. ['id', 'title'], it resolves the promise / fulfills the callback with an array of all the updated rows with specified columns. It's a shortcut for <a href="#Builder-returning">returning method</a></p><pre class="display" data-reactid="1868"><code class="js hljs" data-reactid="1869">knex(<span class="hljs-string">'books'</span>)
.where(<span class="hljs-string">'published_date'</span>, <span class="hljs-string">'<'</span>, <span class="hljs-number">2000</span>)
.update({
<span class="hljs-attr">status</span>: <span class="hljs-string">'archived'</span>,
<span class="hljs-attr">thisKeyIsSkipped</span>: <span class="hljs-literal">undefined</span>
})</code><br data-reactid="1870"/><!-- react-text: 1871 -->Outputs:<!-- /react-text --><br data-reactid="1872"/><code class="sql hljs" data-reactid="1873"><span class="hljs-keyword">update</span> <span class="hljs-string">`books`</span> <span class="hljs-keyword">set</span> <span class="hljs-string">`status`</span> = <span class="hljs-string">'archived'</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`published_date`</span> < <span class="hljs-number">2000</span></code></pre><pre class="display" data-reactid="1874"><code class="js hljs" data-reactid="1875"><span class="hljs-comment">// Returns [1] in "mysql", "sqlite", "oracle"; [] in "postgresql" unless the 'returning' parameter is set.</span>
knex(<span class="hljs-string">'books'</span>).update(<span class="hljs-string">'title'</span>, <span class="hljs-string">'Slaughterhouse Five'</span>)</code><br data-reactid="1876"/><!-- react-text: 1877 -->Outputs:<!-- /react-text --><br data-reactid="1878"/><code class="sql hljs" data-reactid="1879"><span class="hljs-keyword">update</span> <span class="hljs-string">`books`</span> <span class="hljs-keyword">set</span> <span class="hljs-string">`title`</span> = <span class="hljs-string">'Slaughterhouse Five'</span></code></pre><pre class="display" data-reactid="1880"><code class="js hljs" data-reactid="1881"><span class="hljs-comment">// Returns [ { id: 42, title: "The Hitchhiker's Guide to the Galaxy" } ]</span>
knex(<span class="hljs-string">'books'</span>)
.where({ <span class="hljs-attr">id</span>: <span class="hljs-number">42</span> })
.update({ <span class="hljs-attr">title</span>: <span class="hljs-string">"The Hitchhiker's Guide to the Galaxy"</span> }, [<span class="hljs-string">'id'</span>, <span class="hljs-string">'title'</span>])</code><br data-reactid="1882"/><!-- react-text: 1883 -->Outputs:<!-- /react-text --><br data-reactid="1884"/><code class="sql hljs" data-reactid="1885"><span class="hljs-keyword">update</span> <span class="hljs-string">`books`</span> <span class="hljs-keyword">set</span> <span class="hljs-string">`title`</span> = <span class="hljs-string">'The Hitchhiker\'s Guide to the Galaxy'</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`id`</span> = <span class="hljs-number">42</span></code></pre></div><div id="Builder-del / delete" data-reactid="1886"><b data-reactid="1887">del / delete</b><!-- react-text: 1888 --> — <!-- /react-text --><code data-reactid="1889">.del()</code><p data-reactid="1890">Aliased to del as delete is a reserved word in JavaScript, this method deletes one or more rows, based on other conditions specified in the query. Resolves the promise / fulfills the callback with the number of affected rows for the query.</p><pre class="display" data-reactid="1891"><code class="js hljs" data-reactid="1892">knex(<span class="hljs-string">'accounts'</span>)
.where(<span class="hljs-string">'activated'</span>, <span class="hljs-literal">false</span>)
.del()</code><br data-reactid="1893"/><!-- react-text: 1894 -->Outputs:<!-- /react-text --><br data-reactid="1895"/><code class="sql hljs" data-reactid="1896"><span class="hljs-keyword">delete</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`activated`</span> = <span class="hljs-literal">false</span></code></pre></div><div id="Builder-transacting" data-reactid="1897"><b data-reactid="1898">transacting</b><!-- react-text: 1899 --> — <!-- /react-text --><code data-reactid="1900">.transacting(transactionObj)</code><p data-reactid="1901">Used by knex.transaction, 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 data-reactid="1902"><code class="hljs js" data-reactid="1903"><span class="hljs-keyword">var</span> <span class="hljs-built_in">Promise</span> = <span class="hljs-built_in">require</span>(<span class="hljs-string">'bluebird'</span>);
knex.transaction(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">trx</span>) </span>{
knex(<span class="hljs-string">'books'</span>).transacting(trx).insert({<span class="hljs-attr">name</span>: <span class="hljs-string">'Old Books'</span>})
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">resp</span>) </span>{
<span class="hljs-keyword">var</span> id = resp[<span class="hljs-number">0</span>];
<span class="hljs-keyword">return</span> someExternalMethod(id, trx);
})
.then(trx.commit)
.catch(trx.rollback);
})
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">resp</span>) </span>{
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'Transaction complete.'</span>);
})
.catch(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">err</span>) </span>{
<span class="hljs-built_in">console</span>.error(err);
});</code></pre></div><div id="Builder-forUpdate" data-reactid="1904"><b data-reactid="1905">forUpdate</b><!-- react-text: 1906 --> — <!-- /react-text --><code data-reactid="1907">.transacting(t).forUpdate()</code><p data-reactid="1908">Dynamically added after a transaction is specified, the forUpdate adds a FOR UPDATE in PostgreSQL and MySQL during a select statement. Not supported on Amazon Redshift due to lack of table locks.</p><pre class="display" data-reactid="1909"><code class="js hljs" data-reactid="1910">knex(<span class="hljs-string">'tableName'</span>)
.transacting(trx)
.forUpdate()
.select(<span class="hljs-string">'*'</span>)</code><br data-reactid="1911"/><!-- react-text: 1912 -->Outputs:<!-- /react-text --><br data-reactid="1913"/><code class="sql hljs" data-reactid="1914"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`tableName`</span> <span class="hljs-keyword">for</span> <span class="hljs-keyword">update</span></code></pre></div><div id="Builder-forShare" data-reactid="1915"><b data-reactid="1916">forShare</b><!-- react-text: 1917 --> — <!-- /react-text --><code data-reactid="1918">.transacting(t).forShare()</code><p data-reactid="1919">Dynamically added after a transaction is specified, the forShare adds a FOR SHARE in PostgreSQL and a LOCK IN SHARE MODE for MySQL during a select statement. Not supported on Amazon Redshift due to lack of table locks.</p><pre class="display" data-reactid="1920"><code class="js hljs" data-reactid="1921">knex(<span class="hljs-string">'tableName'</span>)
.transacting(trx)
.forShare()
.select(<span class="hljs-string">'*'</span>)</code><br data-reactid="1922"/><!-- react-text: 1923 -->Outputs:<!-- /react-text --><br data-reactid="1924"/><code class="sql hljs" data-reactid="1925"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`tableName`</span> <span class="hljs-keyword">lock</span> <span class="hljs-keyword">in</span> <span class="hljs-keyword">share</span> <span class="hljs-keyword">mode</span></code></pre></div><div id="Builder-skipLocked" data-reactid="1926"><b data-reactid="1927">skipLocked</b><!-- react-text: 1928 --> — <!-- /react-text --><code data-reactid="1929">.skipLocked()</code><p data-reactid="1930">MySQL 8.0+ and PostgreSQL 9.5+ only. This method can be used after a lock mode has been specified with either forUpdate or forShare, and will cause the query to skip any locked rows, returning an empty set if none are available.</p><pre class="display" data-reactid="1931"><code class="js hljs" data-reactid="1932">knex(<span class="hljs-string">'tableName'</span>)
.select(<span class="hljs-string">'*'</span>)
.forUpdate()
.skipLocked()</code><br data-reactid="1933"/><!-- react-text: 1934 -->Outputs:<!-- /react-text --><br data-reactid="1935"/><code class="sql hljs" data-reactid="1936"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`tableName`</span> <span class="hljs-keyword">for</span> <span class="hljs-keyword">update</span> <span class="hljs-keyword">skip</span> <span class="hljs-keyword">locked</span></code></pre></div><div id="Builder-noWait" data-reactid="1937"><b data-reactid="1938">noWait</b><!-- react-text: 1939 --> — <!-- /react-text --><code data-reactid="1940">.noWait()</code><p data-reactid="1941">MySQL 8.0+ and PostgreSQL 9.5+ only. This method can be used after a lock mode has been specified with either forUpdate or forShare, and will cause the query to fail immediately if any selected rows are currently locked.</p><pre class="display" data-reactid="1942"><code class="js hljs" data-reactid="1943">knex(<span class="hljs-string">'tableName'</span>)
.select(<span class="hljs-string">'*'</span>)
.forUpdate()
.noWait()</code><br data-reactid="1944"/><!-- react-text: 1945 -->Outputs:<!-- /react-text --><br data-reactid="1946"/><code class="sql hljs" data-reactid="1947"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`tableName`</span> <span class="hljs-keyword">for</span> <span class="hljs-keyword">update</span> <span class="hljs-keyword">nowait</span></code></pre></div><div id="Builder-count" data-reactid="1948"><b data-reactid="1949">count</b><!-- react-text: 1950 --> — <!-- /react-text --><code data-reactid="1951">.count(column|columns|raw, [options])</code><p data-reactid="1952">Performs a count on the specified column or array of columns (note that some drivers do not support multiple columns). Also accepts raw expressions. The value returned from count (and other aggregation queries) is an array of objects like: <code>[{'COUNT(*)': 1}]</code>. The actual keys are dialect specific, so usually we would want to specify an alias (Refer examples below). Note that in Postgres, count returns a bigint type which will be a String and not a Number (<a href="https://github.com/brianc/node-pg-types#use">more info</a>).</p><pre class="display" data-reactid="1953"><code class="js hljs" data-reactid="1954">knex(<span class="hljs-string">'users'</span>).count(<span class="hljs-string">'active'</span>)</code><br data-reactid="1955"/><!-- react-text: 1956 -->Outputs:<!-- /react-text --><br data-reactid="1957"/><code class="sql hljs" data-reactid="1958"><span class="hljs-keyword">select</span> <span class="hljs-keyword">count</span>(<span class="hljs-string">`active`</span>) <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="1959"><code class="js hljs" data-reactid="1960">knex(<span class="hljs-string">'users'</span>).count(<span class="hljs-string">'active'</span>, {<span class="hljs-attr">as</span>: <span class="hljs-string">'a'</span>})</code><br data-reactid="1961"/><!-- react-text: 1962 -->Outputs:<!-- /react-text --><br data-reactid="1963"/><code class="sql hljs" data-reactid="1964"><span class="hljs-keyword">select</span> <span class="hljs-keyword">count</span>(<span class="hljs-string">`active`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`a`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="1965"><code class="js hljs" data-reactid="1966">knex(<span class="hljs-string">'users'</span>).count(<span class="hljs-string">'active as a'</span>)</code><br data-reactid="1967"/><!-- react-text: 1968 -->Outputs:<!-- /react-text --><br data-reactid="1969"/><code class="sql hljs" data-reactid="1970"><span class="hljs-keyword">select</span> <span class="hljs-keyword">count</span>(<span class="hljs-string">`active`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`a`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="1971"><code class="js hljs" data-reactid="1972">knex(<span class="hljs-string">'users'</span>).count({ <span class="hljs-attr">a</span>: <span class="hljs-string">'active'</span> })</code><br data-reactid="1973"/><!-- react-text: 1974 -->Outputs:<!-- /react-text --><br data-reactid="1975"/><code class="sql hljs" data-reactid="1976"><span class="hljs-keyword">select</span> <span class="hljs-keyword">count</span>(<span class="hljs-string">`active`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`a`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="1977"><code class="js hljs" data-reactid="1978">knex(<span class="hljs-string">'users'</span>).count({ <span class="hljs-attr">a</span>: <span class="hljs-string">'active'</span>, <span class="hljs-attr">v</span>: <span class="hljs-string">'valid'</span> })</code><br data-reactid="1979"/><!-- react-text: 1980 -->Outputs:<!-- /react-text --><br data-reactid="1981"/><code class="sql hljs" data-reactid="1982"><span class="hljs-keyword">select</span> <span class="hljs-keyword">count</span>(<span class="hljs-string">`active`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`a`</span>, <span class="hljs-keyword">count</span>(<span class="hljs-string">`valid`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`v`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="1983"><code class="js hljs" data-reactid="1984">knex(<span class="hljs-string">'users'</span>).count(<span class="hljs-string">'id'</span>, <span class="hljs-string">'active'</span>)</code><br data-reactid="1985"/><!-- react-text: 1986 -->Outputs:<!-- /react-text --><br data-reactid="1987"/><code class="sql hljs" data-reactid="1988"><span class="hljs-keyword">select</span> <span class="hljs-keyword">count</span>(<span class="hljs-string">`id`</span>) <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="1989"><code class="js hljs" data-reactid="1990">knex(<span class="hljs-string">'users'</span>).count({ <span class="hljs-attr">count</span>: [<span class="hljs-string">'id'</span>, <span class="hljs-string">'active'</span>] })</code><br data-reactid="1991"/><!-- react-text: 1992 -->Outputs:<!-- /react-text --><br data-reactid="1993"/><code class="sql hljs" data-reactid="1994"><span class="hljs-keyword">select</span> <span class="hljs-keyword">count</span>(<span class="hljs-string">`id`</span>, <span class="hljs-string">`active`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`count`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="1995"><code class="js hljs" data-reactid="1996">knex(<span class="hljs-string">'users'</span>).count(knex.raw(<span class="hljs-string">'??'</span>, [<span class="hljs-string">'active'</span>]))</code><br data-reactid="1997"/><!-- react-text: 1998 -->Outputs:<!-- /react-text --><br data-reactid="1999"/><code class="sql hljs" data-reactid="2000"><span class="hljs-keyword">select</span> <span class="hljs-keyword">count</span>(<span class="hljs-string">`active`</span>) <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><h3 data-reactid="2001">Usage with TypeScript</h3><p data-reactid="2002">The value of count will, by default, have type of <code>string | number</code>. This may be counter-intuitive but some connectors (eg. postgres) will automatically cast BigInt result to string when javascript's Number type is not large enough for the value.</p><pre data-reactid="2003"><code class="hljs ts" data-reactid="2004">knex(<span class="hljs-string">'users'</span>).count(<span class="hljs-string">'age'</span>) <span class="hljs-comment">// Resolves to: Record<string, number | string></span>
knex(<span class="hljs-string">'users'</span>).count({count: <span class="hljs-string">'*'</span>}) <span class="hljs-comment">// Resolves to { count?: string | number | undefined; }</span></code></pre><p data-reactid="2005">Working with <code>string | number</code> can be inconvenient if you are not working with large tables. Two alternatives are available:</p><pre data-reactid="2006"><code class="hljs ts" data-reactid="2007"><span class="hljs-comment">// Be explicit about what you want as a result:</span>
knex(<span class="hljs-string">'users'</span>).count<Record<<span class="hljs-built_in">string</span>, <span class="hljs-built_in">number</span>>>(<span class="hljs-string">'age'</span>);
<span class="hljs-comment">// Setup a one time declaration to make knex use number as result type for all</span>
<span class="hljs-comment">// count and countDistinct invocations (for any table)</span>
<span class="hljs-keyword">declare</span> <span class="hljs-keyword">module</span> "knex/types/result" {
<span class="hljs-keyword">interface</span> Registry {
Count: <span class="hljs-built_in">number</span>;
}
}</code></pre></div><p data-reactid="2008">Use <strong>countDistinct</strong> to add a distinct expression inside the aggregate function.</p><pre class="display" data-reactid="2009"><code class="js hljs" data-reactid="2010">knex(<span class="hljs-string">'users'</span>).countDistinct(<span class="hljs-string">'active'</span>)</code><br data-reactid="2011"/><!-- react-text: 2012 -->Outputs:<!-- /react-text --><br data-reactid="2013"/><code class="sql hljs" data-reactid="2014"><span class="hljs-keyword">select</span> <span class="hljs-keyword">count</span>(<span class="hljs-keyword">distinct</span> <span class="hljs-string">`active`</span>) <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><div id="Builder-min" data-reactid="2015"><b data-reactid="2016">min</b><!-- react-text: 2017 --> — <!-- /react-text --><code data-reactid="2018">.min(column|columns|raw, [options])</code><p data-reactid="2019">Gets the minimum value for the specified column or array of columns (note that some drivers do not support multiple columns). Also accepts raw expressions.</p><pre class="display" data-reactid="2020"><code class="js hljs" data-reactid="2021">knex(<span class="hljs-string">'users'</span>).min(<span class="hljs-string">'age'</span>)</code><br data-reactid="2022"/><!-- react-text: 2023 -->Outputs:<!-- /react-text --><br data-reactid="2024"/><code class="sql hljs" data-reactid="2025"><span class="hljs-keyword">select</span> <span class="hljs-keyword">min</span>(<span class="hljs-string">`age`</span>) <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2026"><code class="js hljs" data-reactid="2027">knex(<span class="hljs-string">'users'</span>).min(<span class="hljs-string">'age'</span>, {<span class="hljs-attr">as</span>: <span class="hljs-string">'a'</span>})</code><br data-reactid="2028"/><!-- react-text: 2029 -->Outputs:<!-- /react-text --><br data-reactid="2030"/><code class="sql hljs" data-reactid="2031"><span class="hljs-keyword">select</span> <span class="hljs-keyword">min</span>(<span class="hljs-string">`age`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`a`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2032"><code class="js hljs" data-reactid="2033">knex(<span class="hljs-string">'users'</span>).min(<span class="hljs-string">'age as a'</span>)</code><br data-reactid="2034"/><!-- react-text: 2035 -->Outputs:<!-- /react-text --><br data-reactid="2036"/><code class="sql hljs" data-reactid="2037"><span class="hljs-keyword">select</span> <span class="hljs-keyword">min</span>(<span class="hljs-string">`age`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`a`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2038"><code class="js hljs" data-reactid="2039">knex(<span class="hljs-string">'users'</span>).min({ <span class="hljs-attr">a</span>: <span class="hljs-string">'age'</span> })</code><br data-reactid="2040"/><!-- react-text: 2041 -->Outputs:<!-- /react-text --><br data-reactid="2042"/><code class="sql hljs" data-reactid="2043"><span class="hljs-keyword">select</span> <span class="hljs-keyword">min</span>(<span class="hljs-string">`age`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`a`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2044"><code class="js hljs" data-reactid="2045">knex(<span class="hljs-string">'users'</span>).min({ <span class="hljs-attr">a</span>: <span class="hljs-string">'age'</span>, <span class="hljs-attr">b</span>: <span class="hljs-string">'experience'</span> })</code><br data-reactid="2046"/><!-- react-text: 2047 -->Outputs:<!-- /react-text --><br data-reactid="2048"/><code class="sql hljs" data-reactid="2049"><span class="hljs-keyword">select</span> <span class="hljs-keyword">min</span>(<span class="hljs-string">`age`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`a`</span>, <span class="hljs-keyword">min</span>(<span class="hljs-string">`experience`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`b`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2050"><code class="js hljs" data-reactid="2051">knex(<span class="hljs-string">'users'</span>).min(<span class="hljs-string">'age'</span>, <span class="hljs-string">'logins'</span>)</code><br data-reactid="2052"/><!-- react-text: 2053 -->Outputs:<!-- /react-text --><br data-reactid="2054"/><code class="sql hljs" data-reactid="2055"><span class="hljs-keyword">select</span> <span class="hljs-keyword">min</span>(<span class="hljs-string">`age`</span>) <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2056"><code class="js hljs" data-reactid="2057">knex(<span class="hljs-string">'users'</span>).min({ <span class="hljs-attr">min</span>: [<span class="hljs-string">'age'</span>, <span class="hljs-string">'logins'</span>] })</code><br data-reactid="2058"/><!-- react-text: 2059 -->Outputs:<!-- /react-text --><br data-reactid="2060"/><code class="sql hljs" data-reactid="2061"><span class="hljs-keyword">select</span> <span class="hljs-keyword">min</span>(<span class="hljs-string">`age`</span>, <span class="hljs-string">`logins`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`min`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2062"><code class="js hljs" data-reactid="2063">knex(<span class="hljs-string">'users'</span>).min(knex.raw(<span class="hljs-string">'??'</span>, [<span class="hljs-string">'age'</span>]))</code><br data-reactid="2064"/><!-- react-text: 2065 -->Outputs:<!-- /react-text --><br data-reactid="2066"/><code class="sql hljs" data-reactid="2067"><span class="hljs-keyword">select</span> <span class="hljs-keyword">min</span>(<span class="hljs-string">`age`</span>) <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre></div><div id="Builder-max" data-reactid="2068"><b data-reactid="2069">max</b><!-- react-text: 2070 --> — <!-- /react-text --><code data-reactid="2071">.max(column|columns|raw, [options])</code><p data-reactid="2072">Gets the maximum value for the specified column or array of columns (note that some drivers do not support multiple columns). Also accepts raw expressions.</p><pre class="display" data-reactid="2073"><code class="js hljs" data-reactid="2074">knex(<span class="hljs-string">'users'</span>).max(<span class="hljs-string">'age'</span>)</code><br data-reactid="2075"/><!-- react-text: 2076 -->Outputs:<!-- /react-text --><br data-reactid="2077"/><code class="sql hljs" data-reactid="2078"><span class="hljs-keyword">select</span> <span class="hljs-keyword">max</span>(<span class="hljs-string">`age`</span>) <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2079"><code class="js hljs" data-reactid="2080">knex(<span class="hljs-string">'users'</span>).max(<span class="hljs-string">'age'</span>, {<span class="hljs-attr">as</span>: <span class="hljs-string">'a'</span>})</code><br data-reactid="2081"/><!-- react-text: 2082 -->Outputs:<!-- /react-text --><br data-reactid="2083"/><code class="sql hljs" data-reactid="2084"><span class="hljs-keyword">select</span> <span class="hljs-keyword">max</span>(<span class="hljs-string">`age`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`a`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2085"><code class="js hljs" data-reactid="2086">knex(<span class="hljs-string">'users'</span>).max(<span class="hljs-string">'age as a'</span>)</code><br data-reactid="2087"/><!-- react-text: 2088 -->Outputs:<!-- /react-text --><br data-reactid="2089"/><code class="sql hljs" data-reactid="2090"><span class="hljs-keyword">select</span> <span class="hljs-keyword">max</span>(<span class="hljs-string">`age`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`a`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2091"><code class="js hljs" data-reactid="2092">knex(<span class="hljs-string">'users'</span>).max({ <span class="hljs-attr">a</span>: <span class="hljs-string">'age'</span> })</code><br data-reactid="2093"/><!-- react-text: 2094 -->Outputs:<!-- /react-text --><br data-reactid="2095"/><code class="sql hljs" data-reactid="2096"><span class="hljs-keyword">select</span> <span class="hljs-keyword">max</span>(<span class="hljs-string">`age`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`a`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2097"><code class="js hljs" data-reactid="2098">knex(<span class="hljs-string">'users'</span>).max(<span class="hljs-string">'age'</span>, <span class="hljs-string">'logins'</span>)</code><br data-reactid="2099"/><!-- react-text: 2100 -->Outputs:<!-- /react-text --><br data-reactid="2101"/><code class="sql hljs" data-reactid="2102"><span class="hljs-keyword">select</span> <span class="hljs-keyword">max</span>(<span class="hljs-string">`age`</span>) <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2103"><code class="js hljs" data-reactid="2104">knex(<span class="hljs-string">'users'</span>).max({ <span class="hljs-attr">max</span>: [<span class="hljs-string">'age'</span>, <span class="hljs-string">'logins'</span>] })</code><br data-reactid="2105"/><!-- react-text: 2106 -->Outputs:<!-- /react-text --><br data-reactid="2107"/><code class="sql hljs" data-reactid="2108"><span class="hljs-keyword">select</span> <span class="hljs-keyword">max</span>(<span class="hljs-string">`age`</span>, <span class="hljs-string">`logins`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`max`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2109"><code class="js hljs" data-reactid="2110">knex(<span class="hljs-string">'users'</span>).max({ <span class="hljs-attr">max</span>: <span class="hljs-string">'age'</span>, <span class="hljs-attr">exp</span>: <span class="hljs-string">'experience'</span> })</code><br data-reactid="2111"/><!-- react-text: 2112 -->Outputs:<!-- /react-text --><br data-reactid="2113"/><code class="sql hljs" data-reactid="2114"><span class="hljs-keyword">select</span> <span class="hljs-keyword">max</span>(<span class="hljs-string">`age`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`max`</span>, <span class="hljs-keyword">max</span>(<span class="hljs-string">`experience`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`exp`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2115"><code class="js hljs" data-reactid="2116">knex(<span class="hljs-string">'users'</span>).max(knex.raw(<span class="hljs-string">'??'</span>, [<span class="hljs-string">'age'</span>]))</code><br data-reactid="2117"/><!-- react-text: 2118 -->Outputs:<!-- /react-text --><br data-reactid="2119"/><code class="sql hljs" data-reactid="2120"><span class="hljs-keyword">select</span> <span class="hljs-keyword">max</span>(<span class="hljs-string">`age`</span>) <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre></div><div id="Builder-sum" data-reactid="2121"><b data-reactid="2122">sum</b><!-- react-text: 2123 --> — <!-- /react-text --><code data-reactid="2124">.sum(column|columns|raw)</code><p data-reactid="2125">Retrieve the sum of the values of a given column or array of columns (note that some drivers do not support multiple columns). Also accepts raw expressions.</p><pre class="display" data-reactid="2126"><code class="js hljs" data-reactid="2127">knex(<span class="hljs-string">'users'</span>).sum(<span class="hljs-string">'products'</span>)</code><br data-reactid="2128"/><!-- react-text: 2129 -->Outputs:<!-- /react-text --><br data-reactid="2130"/><code class="sql hljs" data-reactid="2131"><span class="hljs-keyword">select</span> <span class="hljs-keyword">sum</span>(<span class="hljs-string">`products`</span>) <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2132"><code class="js hljs" data-reactid="2133">knex(<span class="hljs-string">'users'</span>).sum(<span class="hljs-string">'products as p'</span>)</code><br data-reactid="2134"/><!-- react-text: 2135 -->Outputs:<!-- /react-text --><br data-reactid="2136"/><code class="sql hljs" data-reactid="2137"><span class="hljs-keyword">select</span> <span class="hljs-keyword">sum</span>(<span class="hljs-string">`products`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`p`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2138"><code class="js hljs" data-reactid="2139">knex(<span class="hljs-string">'users'</span>).sum({ <span class="hljs-attr">p</span>: <span class="hljs-string">'products'</span> })</code><br data-reactid="2140"/><!-- react-text: 2141 -->Outputs:<!-- /react-text --><br data-reactid="2142"/><code class="sql hljs" data-reactid="2143"><span class="hljs-keyword">select</span> <span class="hljs-keyword">sum</span>(<span class="hljs-string">`products`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`p`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2144"><code class="js hljs" data-reactid="2145">knex(<span class="hljs-string">'users'</span>).sum(<span class="hljs-string">'products'</span>, <span class="hljs-string">'orders'</span>)</code><br data-reactid="2146"/><!-- react-text: 2147 -->Outputs:<!-- /react-text --><br data-reactid="2148"/><code class="sql hljs" data-reactid="2149"><span class="hljs-keyword">select</span> <span class="hljs-keyword">sum</span>(<span class="hljs-string">`products`</span>) <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2150"><code class="js hljs" data-reactid="2151">knex(<span class="hljs-string">'users'</span>).sum({ <span class="hljs-attr">sum</span>: [<span class="hljs-string">'products'</span>, <span class="hljs-string">'orders'</span>] })</code><br data-reactid="2152"/><!-- react-text: 2153 -->Outputs:<!-- /react-text --><br data-reactid="2154"/><code class="sql hljs" data-reactid="2155"><span class="hljs-keyword">select</span> <span class="hljs-keyword">sum</span>(<span class="hljs-string">`products`</span>, <span class="hljs-string">`orders`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`sum`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2156"><code class="js hljs" data-reactid="2157">knex(<span class="hljs-string">'users'</span>).sum(knex.raw(<span class="hljs-string">'??'</span>, [<span class="hljs-string">'products'</span>]))</code><br data-reactid="2158"/><!-- react-text: 2159 -->Outputs:<!-- /react-text --><br data-reactid="2160"/><code class="sql hljs" data-reactid="2161"><span class="hljs-keyword">select</span> <span class="hljs-keyword">sum</span>(<span class="hljs-string">`products`</span>) <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre></div><p data-reactid="2162">Use <strong>sumDistinct</strong> to add a distinct expression inside the aggregate function.</p><pre class="display" data-reactid="2163"><code class="js hljs" data-reactid="2164">knex(<span class="hljs-string">'users'</span>).sumDistinct(<span class="hljs-string">'products'</span>)</code><br data-reactid="2165"/><!-- react-text: 2166 -->Outputs:<!-- /react-text --><br data-reactid="2167"/><code class="sql hljs" data-reactid="2168"><span class="hljs-keyword">select</span> <span class="hljs-keyword">sum</span>(<span class="hljs-keyword">distinct</span> <span class="hljs-string">`products`</span>) <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><div id="Builder-avg" data-reactid="2169"><b data-reactid="2170">avg</b><!-- react-text: 2171 --> — <!-- /react-text --><code data-reactid="2172">.avg(column|columns|raw)</code><p data-reactid="2173">Retrieve the average of the values of a given column or array of columns (note that some drivers do not support multiple columns). Also accepts raw expressions.</p><pre class="display" data-reactid="2174"><code class="js hljs" data-reactid="2175">knex(<span class="hljs-string">'users'</span>).avg(<span class="hljs-string">'age'</span>)</code><br data-reactid="2176"/><!-- react-text: 2177 -->Outputs:<!-- /react-text --><br data-reactid="2178"/><code class="sql hljs" data-reactid="2179"><span class="hljs-keyword">select</span> <span class="hljs-keyword">avg</span>(<span class="hljs-string">`age`</span>) <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2180"><code class="js hljs" data-reactid="2181">knex(<span class="hljs-string">'users'</span>).avg(<span class="hljs-string">'age as a'</span>)</code><br data-reactid="2182"/><!-- react-text: 2183 -->Outputs:<!-- /react-text --><br data-reactid="2184"/><code class="sql hljs" data-reactid="2185"><span class="hljs-keyword">select</span> <span class="hljs-keyword">avg</span>(<span class="hljs-string">`age`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`a`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2186"><code class="js hljs" data-reactid="2187">knex(<span class="hljs-string">'users'</span>).avg({ <span class="hljs-attr">a</span>: <span class="hljs-string">'age'</span> })</code><br data-reactid="2188"/><!-- react-text: 2189 -->Outputs:<!-- /react-text --><br data-reactid="2190"/><code class="sql hljs" data-reactid="2191"><span class="hljs-keyword">select</span> <span class="hljs-keyword">avg</span>(<span class="hljs-string">`age`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`a`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2192"><code class="js hljs" data-reactid="2193">knex(<span class="hljs-string">'users'</span>).avg(<span class="hljs-string">'age'</span>, <span class="hljs-string">'logins'</span>)</code><br data-reactid="2194"/><!-- react-text: 2195 -->Outputs:<!-- /react-text --><br data-reactid="2196"/><code class="sql hljs" data-reactid="2197"><span class="hljs-keyword">select</span> <span class="hljs-keyword">avg</span>(<span class="hljs-string">`age`</span>) <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2198"><code class="js hljs" data-reactid="2199">knex(<span class="hljs-string">'users'</span>).avg({ <span class="hljs-attr">avg</span>: [<span class="hljs-string">'age'</span>, <span class="hljs-string">'logins'</span>] })</code><br data-reactid="2200"/><!-- react-text: 2201 -->Outputs:<!-- /react-text --><br data-reactid="2202"/><code class="sql hljs" data-reactid="2203"><span class="hljs-keyword">select</span> <span class="hljs-keyword">avg</span>(<span class="hljs-string">`age`</span>, <span class="hljs-string">`logins`</span>) <span class="hljs-keyword">as</span> <span class="hljs-string">`avg`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><pre class="display" data-reactid="2204"><code class="js hljs" data-reactid="2205">knex(<span class="hljs-string">'users'</span>).avg(knex.raw(<span class="hljs-string">'??'</span>, [<span class="hljs-string">'age'</span>]))</code><br data-reactid="2206"/><!-- react-text: 2207 -->Outputs:<!-- /react-text --><br data-reactid="2208"/><code class="sql hljs" data-reactid="2209"><span class="hljs-keyword">select</span> <span class="hljs-keyword">avg</span>(<span class="hljs-string">`age`</span>) <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre></div><p data-reactid="2210">Use <strong>avgDistinct</strong> to add a distinct expression inside the aggregate function.</p><pre class="display" data-reactid="2211"><code class="js hljs" data-reactid="2212">knex(<span class="hljs-string">'users'</span>).avgDistinct(<span class="hljs-string">'age'</span>)</code><br data-reactid="2213"/><!-- react-text: 2214 -->Outputs:<!-- /react-text --><br data-reactid="2215"/><code class="sql hljs" data-reactid="2216"><span class="hljs-keyword">select</span> <span class="hljs-keyword">avg</span>(<span class="hljs-keyword">distinct</span> <span class="hljs-string">`age`</span>) <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre><div id="Builder-increment" data-reactid="2217"><b data-reactid="2218">increment</b><!-- react-text: 2219 --> — <!-- /react-text --><code data-reactid="2220">.increment(column, amount)</code><p data-reactid="2221">Increments a column value by the specified amount. Object syntax is supported for <code>column</code>.</p><pre class="display" data-reactid="2222"><code class="js hljs" data-reactid="2223">knex(<span class="hljs-string">'accounts'</span>)
.where(<span class="hljs-string">'userid'</span>, <span class="hljs-string">'='</span>, <span class="hljs-number">1</span>)
.increment(<span class="hljs-string">'balance'</span>, <span class="hljs-number">10</span>)</code><br data-reactid="2224"/><!-- react-text: 2225 -->Outputs:<!-- /react-text --><br data-reactid="2226"/><code class="sql hljs" data-reactid="2227"><span class="hljs-keyword">update</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">set</span> <span class="hljs-string">`balance`</span> = <span class="hljs-string">`balance`</span> + <span class="hljs-number">10</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`userid`</span> = <span class="hljs-number">1</span></code></pre><pre class="display" data-reactid="2228"><code class="js hljs" data-reactid="2229">knex(<span class="hljs-string">'accounts'</span>)
.where(<span class="hljs-string">'id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-number">1</span>)
.increment({
<span class="hljs-attr">balance</span>: <span class="hljs-number">10</span>,
<span class="hljs-attr">times</span>: <span class="hljs-number">1</span>,
})</code><br data-reactid="2230"/><!-- react-text: 2231 -->Outputs:<!-- /react-text --><br data-reactid="2232"/><code class="sql hljs" data-reactid="2233"><span class="hljs-keyword">update</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">set</span> <span class="hljs-string">`balance`</span> = <span class="hljs-string">`balance`</span> + <span class="hljs-number">10</span>, <span class="hljs-string">`times`</span> = <span class="hljs-string">`times`</span> + <span class="hljs-number">1</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`id`</span> = <span class="hljs-number">1</span></code></pre></div><div id="Builder-decrement" data-reactid="2234"><b data-reactid="2235">decrement</b><!-- react-text: 2236 --> — <!-- /react-text --><code data-reactid="2237">.decrement(column, amount)</code><p data-reactid="2238">Decrements a column value by the specified amount. Object syntax is supported for <code>column</code>.</p><pre class="display" data-reactid="2239"><code class="js hljs" data-reactid="2240">knex(<span class="hljs-string">'accounts'</span>).where(<span class="hljs-string">'userid'</span>, <span class="hljs-string">'='</span>, <span class="hljs-number">1</span>).decrement(<span class="hljs-string">'balance'</span>, <span class="hljs-number">5</span>)</code><br data-reactid="2241"/><!-- react-text: 2242 -->Outputs:<!-- /react-text --><br data-reactid="2243"/><code class="sql hljs" data-reactid="2244"><span class="hljs-keyword">update</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">set</span> <span class="hljs-string">`balance`</span> = <span class="hljs-string">`balance`</span> - <span class="hljs-number">5</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`userid`</span> = <span class="hljs-number">1</span></code></pre><pre class="display" data-reactid="2245"><code class="js hljs" data-reactid="2246">knex(<span class="hljs-string">'accounts'</span>)
.where(<span class="hljs-string">'id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-number">1</span>)
.decrement({
<span class="hljs-attr">balance</span>: <span class="hljs-number">50</span>,
})</code><br data-reactid="2247"/><!-- react-text: 2248 -->Outputs:<!-- /react-text --><br data-reactid="2249"/><code class="sql hljs" data-reactid="2250"><span class="hljs-keyword">update</span> <span class="hljs-string">`accounts`</span> <span class="hljs-keyword">set</span> <span class="hljs-string">`balance`</span> = <span class="hljs-string">`balance`</span> - <span class="hljs-number">50</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`id`</span> = <span class="hljs-number">1</span></code></pre></div><div id="Builder-truncate" data-reactid="2251"><b data-reactid="2252">truncate</b><!-- react-text: 2253 --> — <!-- /react-text --><code data-reactid="2254">.truncate()</code><p data-reactid="2255">Truncates the current table.</p><pre class="display" data-reactid="2256"><code class="js hljs" data-reactid="2257">knex(<span class="hljs-string">'accounts'</span>).truncate()</code><br data-reactid="2258"/><!-- react-text: 2259 -->Outputs:<!-- /react-text --><br data-reactid="2260"/><code class="sql hljs" data-reactid="2261"><span class="hljs-keyword">truncate</span> <span class="hljs-string">`accounts`</span></code></pre></div><div id="Builder-pluck" data-reactid="2262"><b data-reactid="2263">pluck</b><!-- react-text: 2264 --> — <!-- /react-text --><code data-reactid="2265">.pluck(id)</code><p data-reactid="2266">This will pluck the specified column from each row in your results, yielding a promise which resolves to the array of values selected.</p><pre data-reactid="2267"><code class="hljs js" data-reactid="2268">knex.table(<span class="hljs-string">'users'</span>).pluck(<span class="hljs-string">'id'</span>).then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">ids</span>) </span>{ <span class="hljs-built_in">console</span>.log(ids); });</code></pre></div><div id="Builder-first" data-reactid="2269"><b data-reactid="2270">first</b><!-- react-text: 2271 --> — <!-- /react-text --><code data-reactid="2272">.first([columns])</code><p data-reactid="2273">Similar to select, but only retrieves & resolves with the first record from the query.</p><pre data-reactid="2274"><code class="hljs js" data-reactid="2275">knex.table(<span class="hljs-string">'users'</span>).first(<span class="hljs-string">'id'</span>, <span class="hljs-string">'name'</span>).then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">row</span>) </span>{ <span class="hljs-built_in">console</span>.log(row); });</code></pre></div><div id="Builder-clone" data-reactid="2276"><b data-reactid="2277">clone</b><!-- react-text: 2278 --> — <!-- /react-text --><code data-reactid="2279">.clone()</code><p data-reactid="2280">Clones the current query chain, useful for re-using partial query snippets in other queries without mutating the original.</p></div><div id="Builder-modify" data-reactid="2281"><b data-reactid="2282">modify</b><!-- react-text: 2283 --> — <!-- /react-text --><code data-reactid="2284">.modify(fn, *arguments)</code><p data-reactid="2285">Allows encapsulating and re-using query snippets and common behaviors as functions. The callback function should receive the query builder as its first argument, followed by the rest of the (optional) parameters passed to modify.</p><pre data-reactid="2286"><code class="hljs js" data-reactid="2287"><span class="hljs-keyword">var</span> withUserName = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">queryBuilder, foreignKey</span>) </span>{
queryBuilder.leftJoin(<span class="hljs-string">'users'</span>, foreignKey, <span class="hljs-string">'users.id'</span>).select(<span class="hljs-string">'users.user_name'</span>);
};
knex.table(<span class="hljs-string">'articles'</span>).select(<span class="hljs-string">'title'</span>, <span class="hljs-string">'body'</span>).modify(withUserName, <span class="hljs-string">'articles_user.id'</span>).then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">article</span>) </span>{
<span class="hljs-built_in">console</span>.log(article.user_name);
});</code></pre></div><div id="Builder-columnInfo" data-reactid="2288"><b data-reactid="2289">columnInfo</b><!-- react-text: 2290 --> — <!-- /react-text --><code data-reactid="2291">.columnInfo([columnName])</code><p data-reactid="2292">Returns an object with the column info about the current table, or an individual column if one is passed, returning an object with the following keys:* <strong>defaultValue</strong>: the default value for the column* <strong>type</strong>: the column type* <strong>maxLength</strong>: the max length set for the column* <strong>nullable</strong>: whether the column may be null</p><pre data-reactid="2293"><code class="hljs js" data-reactid="2294">knex(<span class="hljs-string">'users'</span>).columnInfo().then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">info</span>) </span>{ <span class="hljs-comment">// ... });</span></code></pre></div><div id="Builder-debug" data-reactid="2295"><b data-reactid="2296">debug</b><!-- react-text: 2297 --> — <!-- /react-text --><code data-reactid="2298">.debug([enabled])</code><p data-reactid="2299">Overrides the global debug setting for the current query chain. If enabled is omitted, query debugging will be turned on.</p></div><div id="Builder-connection" data-reactid="2300"><b data-reactid="2301">connection</b><!-- react-text: 2302 --> — <!-- /react-text --><code data-reactid="2303">.connection(dbConnection)</code><p data-reactid="2304">The method sets the db connection to use for the query without using the connection pool. You should pass to it the same object that acquireConnection() for the corresponding driver returns</p><pre data-reactid="2305"><code class="hljs js" data-reactid="2306"><span class="hljs-keyword">const</span> Pool = <span class="hljs-built_in">require</span>(<span class="hljs-string">'pg-pool'</span>)
<span class="hljs-keyword">const</span> pool = <span class="hljs-keyword">new</span> Pool({ ... })
<span class="hljs-keyword">const</span> connection = <span class="hljs-keyword">await</span> pool.connect();
<span class="hljs-keyword">try</span> {
<span class="hljs-keyword">return</span> <span class="hljs-keyword">await</span> knex.connection(connection); <span class="hljs-comment">// knex here is a query builder with query already built</span>
} <span class="hljs-keyword">catch</span> (error) {
<span class="hljs-comment">// Process error</span>
} <span class="hljs-keyword">finally</span> {
connection.release();
}</code></pre></div><div id="Builder-options" data-reactid="2307"><b data-reactid="2308">options</b><!-- react-text: 2309 --> — <!-- /react-text --><code data-reactid="2310">.options()</code><p data-reactid="2311">Allows for mixing in additional options as defined by database client specific libraries:</p><pre data-reactid="2312"><code class="hljs js" data-reactid="2313">knex(<span class="hljs-string">'accounts as a1'</span>)
.leftJoin(<span class="hljs-string">'accounts as a2'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">this</span>.on(<span class="hljs-string">'a1.email'</span>, <span class="hljs-string">'<>'</span>, <span class="hljs-string">'a2.email'</span>);
})
.select([<span class="hljs-string">'a1.email'</span>, <span class="hljs-string">'a2.email'</span>])
.where(knex.raw(<span class="hljs-string">'a1.id = 1'</span>))
.options({ <span class="hljs-attr">nestTables</span>: <span class="hljs-literal">true</span>, <span class="hljs-attr">rowMode</span>: <span class="hljs-string">'array'</span> })
.limit(<span class="hljs-number">2</span>)
.then(...</code></pre></div><div id="Builder-queryContext" data-reactid="2314"><b data-reactid="2315">queryContext</b><!-- react-text: 2316 --> — <!-- /react-text --><code data-reactid="2317">.queryContext(context)</code><p data-reactid="2318">Allows for configuring a context to be passed to the <a href="#Installation-wrap-identifier">wrapIdentifier</a> and <a href="#Installation-post-process-response">postProcessResponse</a> hooks:</p><pre data-reactid="2319"><code class="hljs js" data-reactid="2320">knex(<span class="hljs-string">'accounts as a1'</span>)
.queryContext({ <span class="hljs-attr">foo</span>: <span class="hljs-string">'bar'</span> })
.select([<span class="hljs-string">'a1.email'</span>, <span class="hljs-string">'a2.email'</span>])</code></pre><p data-reactid="2321">The context can be any kind of value and will be passed to the hooks without modification. However, note that <strong>objects will be shallow-cloned</strong> when a query builder instance is <a href="#Builder-clone">cloned</a>, which means that they will contain all the properties of the original object but will not be the same object reference. This allows modifying the context for the cloned query builder instance.</p><p data-reactid="2322">Calling <code>queryContext</code> with no arguments will return any context configured for the query builder instance.</p></div><h3 id="Builder-extending" data-reactid="2323">Extending Query Builder</h3><div data-reactid="2324"><p data-reactid="2325"><strong>Important:</strong> this feature is experimental and its API may change in the future.</p><p data-reactid="2326">It allows to add custom function the the Query Builder.</p><p data-reactid="2327">Example:</p></div><pre data-reactid="2328"><code class="hljs js" data-reactid="2329"><span class="hljs-keyword">const</span> Knex = <span class="hljs-built_in">require</span>(<span class="hljs-string">'knex'</span>);
Knex.QueryBuilder.extend(<span class="hljs-string">'customSelect'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">value</span>) </span>{
<span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>.select(<span class="hljs-keyword">this</span>.client.raw(<span class="hljs-string">`<span class="hljs-subst">${value}</span> as value`</span>));
});
<span class="hljs-keyword">const</span> meaningOfLife = <span class="hljs-keyword">await</span> knex(<span class="hljs-string">'accounts'</span>)
.customSelect(<span class="hljs-number">42</span>);</code></pre><div data-reactid="2330"><p data-reactid="2331">If using TypeScript, you can extend the QueryBuilder interface with your custom method.</p><p data-reactid="2332"><ol>
<li>Create a <code>knex.d.ts</code> file inside a <code>@types</code> folder (or any other folder).</li>
</ol>
</p></div><pre data-reactid="2333"><code class="hljs ts" data-reactid="2334"><span class="hljs-comment">// knex.d.ts</span>
<span class="hljs-keyword">import</span> * <span class="hljs-keyword">as</span> Knex <span class="hljs-keyword">from</span> <span class="hljs-string">'knex'</span>;
<span class="hljs-keyword">declare</span> <span class="hljs-keyword">module</span> 'knex' {
<span class="hljs-keyword">interface</span> QueryBuilder {
customSelect<TRecord, TResult>(value: <span class="hljs-built_in">number</span>): QueryBuilder<TRecord, TResult>;
}</code></pre><div data-reactid="2335"><p data-reactid="2336"><ol start="2">
<li>Add the new <code>@types</code> folder to <code>typeRoots</code> in your <code>tsconfig.json</code>.</li>
</ol>
</p></div><pre data-reactid="2337"><code class="hljs ts" data-reactid="2338"><span class="hljs-comment">// tsconfig.json</span>
{
<span class="hljs-string">"compilerOptions"</span>: {
<span class="hljs-string">"typeRoots"</span>: [
<span class="hljs-string">"node_modules/@types"</span>,
<span class="hljs-string">"@types"</span>
],
}
}</code></pre></div><div id="Transactions" data-reactid="2339"><h2 id="Transactions" data-reactid="2340">Transactions</h2><div data-reactid="2341"><p data-reactid="2342">Transactions are an important feature of relational databases, as they allow correct recovery from failures and keep a database consistent even in cases of system failure. All queries within a transaction are executed on the same database connection, and run the entire set of queries as a single unit of work. Any failure will mean the database will rollback any queries executed on that connection to the pre-transaction state.</p><p data-reactid="2343">Transactions are handled by passing a handler function into <code>knex.transaction</code>. The handler function accepts a single argument, an object which may be used in two ways:<ol>
<li>As the "promise aware" knex connection</li>
<li>As an object passed into a query with <a href="#Builder-transacting"></a>and eventually call commit or rollback.</li>
</ol>
Consider these two examples:</p></div><pre data-reactid="2344"><code class="hljs js" data-reactid="2345"><span class="hljs-comment">// Using trx as a query builder:</span>
knex.transaction(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">trx</span>) </span>{
<span class="hljs-keyword">const</span> books = [
{<span class="hljs-attr">title</span>: <span class="hljs-string">'Canterbury Tales'</span>},
{<span class="hljs-attr">title</span>: <span class="hljs-string">'Moby Dick'</span>},
{<span class="hljs-attr">title</span>: <span class="hljs-string">'Hamlet'</span>}
];
<span class="hljs-keyword">return</span> trx
.insert({<span class="hljs-attr">name</span>: <span class="hljs-string">'Old Books'</span>}, <span class="hljs-string">'id'</span>)
.into(<span class="hljs-string">'catalogues'</span>)
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">ids</span>) </span>{
books.forEach(<span class="hljs-function">(<span class="hljs-params">book</span>) =></span> book.catalogue_id = ids[<span class="hljs-number">0</span>]);
<span class="hljs-keyword">return</span> trx(<span class="hljs-string">'books'</span>).insert(books);
});
})
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">inserts</span>) </span>{
<span class="hljs-built_in">console</span>.log(inserts.length + <span class="hljs-string">' new books saved.'</span>);
})
.catch(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">error</span>) </span>{
<span class="hljs-comment">// If we get here, that means that neither the 'Old Books' catalogues insert,</span>
<span class="hljs-comment">// nor any of the books inserts will have taken place.</span>
<span class="hljs-built_in">console</span>.error(error);
});</code></pre><p data-reactid="2346">And then this example:</p><pre data-reactid="2347"><code class="hljs js" data-reactid="2348"><span class="hljs-comment">// Using trx as a transaction object:</span>
knex.transaction(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">trx</span>) </span>{
<span class="hljs-keyword">const</span> books = [
{<span class="hljs-attr">title</span>: <span class="hljs-string">'Canterbury Tales'</span>},
{<span class="hljs-attr">title</span>: <span class="hljs-string">'Moby Dick'</span>},
{<span class="hljs-attr">title</span>: <span class="hljs-string">'Hamlet'</span>}
];
knex.insert({<span class="hljs-attr">name</span>: <span class="hljs-string">'Old Books'</span>}, <span class="hljs-string">'id'</span>)
.into(<span class="hljs-string">'catalogues'</span>)
.transacting(trx)
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">ids</span>) </span>{
books.forEach(<span class="hljs-function">(<span class="hljs-params">book</span>) =></span> book.catalogue_id = ids[<span class="hljs-number">0</span>]);
<span class="hljs-keyword">return</span> knex(<span class="hljs-string">'books'</span>).insert(books).transacting(trx);
})
.then(trx.commit)
.catch(trx.rollback);
})
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">inserts</span>) </span>{
<span class="hljs-built_in">console</span>.log(inserts.length + <span class="hljs-string">' new books saved.'</span>);
})
.catch(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">error</span>) </span>{
<span class="hljs-comment">// If we get here, that means that neither the 'Old Books' catalogues insert,</span>
<span class="hljs-comment">// nor any of the books inserts will have taken place.</span>
<span class="hljs-built_in">console</span>.error(error);
});</code></pre><div data-reactid="2349"><p data-reactid="2350">Throwing an error directly from the transaction handler function automatically rolls back the transaction, same as returning a rejected promise.</p><p data-reactid="2351">Notice that if a promise is not returned within the handler, it is up to you to ensure <code>trx.commit</code>, or <code>trx.rollback</code> are called, otherwise the transaction connection will hang.</p><p data-reactid="2352">Calling <code>trx.rollback</code> will return a rejected Promise. If you don't pass any argument to <code>trx.rollback</code>, a generic <code>Error</code> object will be created and passed in to ensure the Promise always rejects with something.</p><p data-reactid="2353">Note that Amazon Redshift does not support savepoints in transactions.</p></div><p data-reactid="2354">In some cases you may prefer to create transaction but only execute statements in it later. In such case call method <code>transaction</code> without a handler function:</p><pre data-reactid="2355"><code class="hljs js" data-reactid="2356"><span class="hljs-comment">// Using trx as a transaction object:</span>
<span class="hljs-keyword">const</span> trx = <span class="hljs-keyword">await</span> knex.transaction();
<span class="hljs-keyword">const</span> books = [
{<span class="hljs-attr">title</span>: <span class="hljs-string">'Canterbury Tales'</span>},
{<span class="hljs-attr">title</span>: <span class="hljs-string">'Moby Dick'</span>},
{<span class="hljs-attr">title</span>: <span class="hljs-string">'Hamlet'</span>}
];
trx(<span class="hljs-string">'catalogues'</span>)
.insert({<span class="hljs-attr">name</span>: <span class="hljs-string">'Old Books'</span>}, <span class="hljs-string">'id'</span>)
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">ids</span>) </span>{
books.forEach(<span class="hljs-function">(<span class="hljs-params">book</span>) =></span> book.catalogue_id = ids[<span class="hljs-number">0</span>]);
<span class="hljs-keyword">return</span> trx(<span class="hljs-string">'books'</span>).insert(books);
})
.then(trx.commit)
.catch(trx.rollback);</code></pre><p data-reactid="2357">If you want to create a reusable transaction instance, but do not want to actually start it until it is used, you can create a transaction provider instance. It will start transaction after being called for the first time, and return same transaction on subsequent calls:</p><pre data-reactid="2358"><code class="hljs js" data-reactid="2359"><span class="hljs-comment">// Does not start a transaction yet</span>
<span class="hljs-keyword">const</span> trxProvider = knex.transactionProvider();
<span class="hljs-keyword">const</span> books = [
{<span class="hljs-attr">title</span>: <span class="hljs-string">'Canterbury Tales'</span>},
{<span class="hljs-attr">title</span>: <span class="hljs-string">'Moby Dick'</span>},
{<span class="hljs-attr">title</span>: <span class="hljs-string">'Hamlet'</span>}
];
<span class="hljs-comment">// Starts a transaction</span>
<span class="hljs-keyword">const</span> trx = <span class="hljs-keyword">await</span> trxProvider();
<span class="hljs-keyword">const</span> ids = <span class="hljs-keyword">await</span> trx(<span class="hljs-string">'catalogues'</span>)
.insert({<span class="hljs-attr">name</span>: <span class="hljs-string">'Old Books'</span>}, <span class="hljs-string">'id'</span>)
books.forEach(<span class="hljs-function">(<span class="hljs-params">book</span>) =></span> book.catalogue_id = ids[<span class="hljs-number">0</span>]);
<span class="hljs-keyword">await</span> trx(<span class="hljs-string">'books'</span>).insert(books);
<span class="hljs-comment">// Reuses same transaction</span>
<span class="hljs-keyword">const</span> sameTrx = <span class="hljs-keyword">await</span> trxProvider();
<span class="hljs-keyword">const</span> ids2 = <span class="hljs-keyword">await</span> sameTrx(<span class="hljs-string">'catalogues'</span>)
.insert({<span class="hljs-attr">name</span>: <span class="hljs-string">'New Books'</span>}, <span class="hljs-string">'id'</span>)
books.forEach(<span class="hljs-function">(<span class="hljs-params">book</span>) =></span> book.catalogue_id = ids2[<span class="hljs-number">0</span>]);
<span class="hljs-keyword">await</span> sameTrx(<span class="hljs-string">'books'</span>).insert(books);</code></pre><p data-reactid="2360">You can access promise that gets resolved after transaction is rolled back explicitly by user or committed, or rejected if it gets rolled back by DB itself, when using either way of creating transaction, from field <code>executionPromise</code>:</p><pre data-reactid="2361"><code class="hljs js" data-reactid="2362"><span class="hljs-keyword">const</span> trxProvider = knex.transactionProvider();
<span class="hljs-keyword">const</span> trx = <span class="hljs-keyword">await</span> trxProvider();
<span class="hljs-keyword">const</span> trxPromise = trx.executionPromise;
<span class="hljs-keyword">const</span> trx2 = <span class="hljs-keyword">await</span> knex.transaction();
<span class="hljs-keyword">const</span> trx2Promise = trx2.executionPromise;
<span class="hljs-keyword">const</span> trxInitPromise = <span class="hljs-keyword">new</span> <span class="hljs-built_in">Promise</span>(<span class="hljs-keyword">async</span> (resolve, reject) => {
knex.transaction(<span class="hljs-function">(<span class="hljs-params">transaction</span>) =></span> {
resolve(transaction);
});
});
<span class="hljs-keyword">const</span> trx3 = <span class="hljs-keyword">await</span> trxInitPromise;
<span class="hljs-keyword">const</span> trx3Promise = trx3.executionPromise;</code></pre><p data-reactid="2363">You can check if a transaction has been committed or rolled back with the method <code>isCompleted</code>:</p><pre data-reactid="2364"><code class="hljs js" data-reactid="2365"><span class="hljs-keyword">const</span> trx = <span class="hljs-keyword">await</span> knex.transaction();
trx.isCompleted(); <span class="hljs-comment">// false</span>
<span class="hljs-keyword">await</span> trx.commit();
trx.isCompleted(); <span class="hljs-comment">// true</span>
<span class="hljs-keyword">const</span> trx2 = knex.transactionProvider();
<span class="hljs-keyword">await</span> trx2.rollback();
trx2.isCompleted(); <span class="hljs-comment">// true</span></code></pre></div><div id="Schema" data-reactid="2366"><h2 id="Schema" data-reactid="2367">Schema Builder</h2><p data-reactid="2368">The <code>knex.schema</code> is a <strong>getter function</strong>, which returns a stateful object containing the query. Therefore be sure to obtain a new instance of the <code>knex.schema</code> for every query. These methods return <a href="http://knexjs.org/#Interfaces-Promises">promises</a>.</p><div id="Schema-withSchema" data-reactid="2369"><b data-reactid="2370">withSchema</b><!-- react-text: 2371 --> — <!-- /react-text --><code data-reactid="2372">knex.schema.withSchema([schemaName])</code><p data-reactid="2373">Specifies the schema to be used when using the schema-building commands.</p><pre class="display" data-reactid="2374"><code class="js hljs" data-reactid="2375">knex.schema.withSchema(<span class="hljs-string">'public'</span>).createTable(<span class="hljs-string">'users'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">table</span>) </span>{
table.increments();
})</code><br data-reactid="2376"/><!-- react-text: 2377 -->Outputs:<!-- /react-text --><br data-reactid="2378"/><code class="sql hljs" data-reactid="2379"><span class="hljs-keyword">create</span> <span class="hljs-keyword">table</span> <span class="hljs-string">`public`</span>.<span class="hljs-string">`users`</span> (<span class="hljs-string">`id`</span> <span class="hljs-built_in">int</span> <span class="hljs-keyword">unsigned</span> <span class="hljs-keyword">not</span> <span class="hljs-literal">null</span> auto_increment primary <span class="hljs-keyword">key</span>)</code></pre></div><div id="Schema-createTable" data-reactid="2380"><b data-reactid="2381">createTable</b><!-- react-text: 2382 --> — <!-- /react-text --><code data-reactid="2383">knex.schema.createTable(tableName, callback)</code><p data-reactid="2384">Creates a new table on the database, with a callback function to modify the table's structure, using the schema-building commands.</p><pre class="display" data-reactid="2385"><code class="js hljs" data-reactid="2386">knex.schema.createTable(<span class="hljs-string">'users'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">table</span>) </span>{
table.increments();
table.string(<span class="hljs-string">'name'</span>);
table.timestamps();
})</code><br data-reactid="2387"/><!-- react-text: 2388 -->Outputs:<!-- /react-text --><br data-reactid="2389"/><code class="sql hljs" data-reactid="2390"><span class="hljs-keyword">create</span> <span class="hljs-keyword">table</span> <span class="hljs-string">`users`</span> (<span class="hljs-string">`id`</span> <span class="hljs-built_in">int</span> <span class="hljs-keyword">unsigned</span> <span class="hljs-keyword">not</span> <span class="hljs-literal">null</span> auto_increment primary <span class="hljs-keyword">key</span>, <span class="hljs-string">`name`</span> <span class="hljs-built_in">varchar</span>(<span class="hljs-number">255</span>), <span class="hljs-string">`created_at`</span> datetime, <span class="hljs-string">`updated_at`</span> datetime)</code></pre></div><div id="Schema-renameTable" data-reactid="2391"><b data-reactid="2392">renameTable</b><!-- react-text: 2393 --> — <!-- /react-text --><code data-reactid="2394">knex.schema.renameTable(from, to)</code><p data-reactid="2395">Renames a table from a current tableName to another.</p><pre class="display" data-reactid="2396"><code class="js hljs" data-reactid="2397">knex.schema.renameTable(<span class="hljs-string">'users'</span>, <span class="hljs-string">'old_users'</span>)</code><br data-reactid="2398"/><!-- react-text: 2399 -->Outputs:<!-- /react-text --><br data-reactid="2400"/><code class="sql hljs" data-reactid="2401"><span class="hljs-keyword">rename</span> <span class="hljs-keyword">table</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">to</span> <span class="hljs-string">`old_users`</span></code></pre></div><div id="Schema-dropTable" data-reactid="2402"><b data-reactid="2403">dropTable</b><!-- react-text: 2404 --> — <!-- /react-text --><code data-reactid="2405">knex.schema.dropTable(tableName)</code><p data-reactid="2406">Drops a table, specified by tableName.</p><pre class="display" data-reactid="2407"><code class="js hljs" data-reactid="2408">knex.schema.dropTable(<span class="hljs-string">'users'</span>)</code><br data-reactid="2409"/><!-- react-text: 2410 -->Outputs:<!-- /react-text --><br data-reactid="2411"/><code class="sql hljs" data-reactid="2412"><span class="hljs-keyword">drop</span> <span class="hljs-keyword">table</span> <span class="hljs-string">`users`</span></code></pre></div><div id="Schema-hasTable" data-reactid="2413"><b data-reactid="2414">hasTable</b><!-- react-text: 2415 --> — <!-- /react-text --><code data-reactid="2416">knex.schema.hasTable(tableName)</code><p data-reactid="2417">Checks for a table's existence by tableName, resolving with a boolean to signal if the table exists.</p><pre data-reactid="2418"><code class="hljs js" data-reactid="2419">knex.schema.hasTable(<span class="hljs-string">'users'</span>).then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">exists</span>) </span>{
<span class="hljs-keyword">if</span> (!exists) {
<span class="hljs-keyword">return</span> knex.schema.createTable(<span class="hljs-string">'users'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">t</span>) </span>{
t.increments(<span class="hljs-string">'id'</span>).primary();
t.string(<span class="hljs-string">'first_name'</span>, <span class="hljs-number">100</span>);
t.string(<span class="hljs-string">'last_name'</span>, <span class="hljs-number">100</span>);
t.text(<span class="hljs-string">'bio'</span>);
});
}
});</code></pre></div><div id="Schema-hasColumn" data-reactid="2420"><b data-reactid="2421">hasColumn</b><!-- react-text: 2422 --> — <!-- /react-text --><code data-reactid="2423">knex.schema.hasColumn(tableName, columnName)</code><p data-reactid="2424">Checks if a column exists in the current table, resolves the promise with a boolean, true if the column exists, false otherwise.</p></div><div id="Schema-dropTableIfExists" data-reactid="2425"><b data-reactid="2426">dropTableIfExists</b><!-- react-text: 2427 --> — <!-- /react-text --><code data-reactid="2428">knex.schema.dropTableIfExists(tableName)</code><p data-reactid="2429">Drops a table conditionally if the table exists, specified by tableName.</p><pre class="display" data-reactid="2430"><code class="js hljs" data-reactid="2431">knex.schema.dropTableIfExists(<span class="hljs-string">'users'</span>)</code><br data-reactid="2432"/><!-- react-text: 2433 -->Outputs:<!-- /react-text --><br data-reactid="2434"/><code class="sql hljs" data-reactid="2435"><span class="hljs-keyword">drop</span> <span class="hljs-keyword">table</span> <span class="hljs-keyword">if</span> <span class="hljs-keyword">exists</span> <span class="hljs-string">`users`</span></code></pre></div><div id="Schema-table" data-reactid="2436"><b data-reactid="2437">table</b><!-- react-text: 2438 --> — <!-- /react-text --><code data-reactid="2439">knex.schema.table(tableName, callback)</code><p data-reactid="2440">Chooses a database table, and then modifies the table, using the Schema Building functions inside of the callback.</p><pre class="display" data-reactid="2441"><code class="js hljs" data-reactid="2442">knex.schema.table(<span class="hljs-string">'users'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">table</span>) </span>{
table.dropColumn(<span class="hljs-string">'name'</span>);
table.string(<span class="hljs-string">'first_name'</span>);
table.string(<span class="hljs-string">'last_name'</span>);
})</code><br data-reactid="2443"/><!-- react-text: 2444 -->Outputs:<!-- /react-text --><br data-reactid="2445"/><code class="sql hljs" data-reactid="2446"><span class="hljs-keyword">alter</span> <span class="hljs-keyword">table</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">add</span> <span class="hljs-string">`first_name`</span> <span class="hljs-built_in">varchar</span>(<span class="hljs-number">255</span>), <span class="hljs-keyword">add</span> <span class="hljs-string">`last_name`</span> <span class="hljs-built_in">varchar</span>(<span class="hljs-number">255</span>);
<span class="hljs-keyword">alter</span> <span class="hljs-keyword">table</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">drop</span> <span class="hljs-string">`name`</span></code></pre></div><div id="Schema-raw" data-reactid="2447"><b data-reactid="2448">raw</b><!-- react-text: 2449 --> — <!-- /react-text --><code data-reactid="2450">knex.schema.raw(statement)</code><p data-reactid="2451">Run an arbitrary sql query in the schema builder chain.</p><pre class="display" data-reactid="2452"><code class="js hljs" data-reactid="2453">knex.schema.raw(<span class="hljs-string">"SET sql_mode='TRADITIONAL'"</span>)
.table(<span class="hljs-string">'users'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">table</span>) </span>{
table.dropColumn(<span class="hljs-string">'name'</span>);
table.string(<span class="hljs-string">'first_name'</span>);
table.string(<span class="hljs-string">'last_name'</span>);
})</code><br data-reactid="2454"/><!-- react-text: 2455 -->Outputs:<!-- /react-text --><br data-reactid="2456"/><code class="sql hljs" data-reactid="2457"><span class="hljs-keyword">SET</span> sql_mode=<span class="hljs-string">'TRADITIONAL'</span>;
<span class="hljs-keyword">alter</span> <span class="hljs-keyword">table</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">add</span> <span class="hljs-string">`first_name`</span> <span class="hljs-built_in">varchar</span>(<span class="hljs-number">255</span>), <span class="hljs-keyword">add</span> <span class="hljs-string">`last_name`</span> <span class="hljs-built_in">varchar</span>(<span class="hljs-number">255</span>);
<span class="hljs-keyword">alter</span> <span class="hljs-keyword">table</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">drop</span> <span class="hljs-string">`name`</span></code></pre></div><div id="Schema-queryContext" data-reactid="2458"><b data-reactid="2459">queryContext</b><!-- react-text: 2460 --> — <!-- /react-text --><code data-reactid="2461">knex.schema.queryContext(context)</code><p data-reactid="2462">Allows configuring a context to be passed to the <a href="#Installation-wrap-identifier">wrapIdentifier</a> hook. The context can be any kind of value and will be passed to <code>wrapIdentifier</code> without modification.</p><pre data-reactid="2463"><code class="hljs js" data-reactid="2464">knex.schema.queryContext({ <span class="hljs-attr">foo</span>: <span class="hljs-string">'bar'</span> })
.table(<span class="hljs-string">'users'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">table</span>) </span>{
table.string(<span class="hljs-string">'first_name'</span>);
table.string(<span class="hljs-string">'last_name'</span>);
})</code></pre><p data-reactid="2465">The context configured will be passed to <code>wrapIdentifier</code> for each identifier that needs to be formatted, including the table and column names. However, a different context can be set for the column names via <a href="#Schema-table-queryContext">table.queryContext</a>.</p><p data-reactid="2466">Calling <code>queryContext</code> with no arguments will return any context configured for the schema builder instance.</p></div><h3 id="Schema-Building" data-reactid="2467">Schema Building:</h3><div id="Schema-dropColumn" data-reactid="2468"><b data-reactid="2469">dropColumn</b><!-- react-text: 2470 --> — <!-- /react-text --><code data-reactid="2471">table.dropColumn(name)</code><p data-reactid="2472">Drops a column, specified by the column's name</p></div><div id="Schema-dropColumns" data-reactid="2473"><b data-reactid="2474">dropColumns</b><!-- react-text: 2475 --> — <!-- /react-text --><code data-reactid="2476">table.dropColumns(*columns)</code><p data-reactid="2477">Drops multiple columns, taking a variable number of column names.</p></div><div id="Schema-renameColumn" data-reactid="2478"><b data-reactid="2479">renameColumn</b><!-- react-text: 2480 --> — <!-- /react-text --><code data-reactid="2481">table.renameColumn(from, to)</code><p data-reactid="2482">Renames a column from one name to another.</p></div><div id="Schema-increments" data-reactid="2483"><b data-reactid="2484">increments</b><!-- react-text: 2485 --> — <!-- /react-text --><code data-reactid="2486">table.increments(name)</code><p data-reactid="2487">Adds an auto incrementing column. In PostgreSQL this is a serial; in Amazon Redshift an integer identity(1,1). This will be used as the primary key for the table. Also available is a bigIncrements if you wish to add a bigint incrementing number (in PostgreSQL bigserial).</p><pre data-reactid="2488"><code class="hljs js" data-reactid="2489"><span class="hljs-comment">// create table 'users' with a primary key using 'increments()'</span>
knex.schema.createTable(<span class="hljs-string">'users'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">table</span>) </span>{
table.increments(<span class="hljs-string">'userId'</span>);
table.string(<span class="hljs-string">'name'</span>);
});
<span class="hljs-comment">// reference the 'users' primary key in new table 'posts'</span>
knex.schema.createTable(<span class="hljs-string">'posts'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">table</span>) </span>{
table.integer(<span class="hljs-string">'author'</span>).unsigned().notNullable();
table.string(<span class="hljs-string">'title'</span>, <span class="hljs-number">30</span>);
table.string(<span class="hljs-string">'content'</span>);
table.foreign(<span class="hljs-string">'author'</span>).references(<span class="hljs-string">'userId'</span>).inTable(<span class="hljs-string">'users'</span>);
});</code></pre></div><div id="Schema-integer" data-reactid="2490"><b data-reactid="2491">integer</b><!-- react-text: 2492 --> — <!-- /react-text --><code data-reactid="2493">table.integer(name)</code><p data-reactid="2494">Adds an integer column.</p></div><div id="Schema-bigInteger" data-reactid="2495"><b data-reactid="2496">bigInteger</b><!-- react-text: 2497 --> — <!-- /react-text --><code data-reactid="2498">table.bigInteger(name)</code><p data-reactid="2499">In MySQL or PostgreSQL, adds a bigint column, otherwise adds a normal integer. Note that bigint data is returned as a string in queries because JavaScript may be unable to parse them without loss of precision.</p></div><div id="Schema-text" data-reactid="2500"><b data-reactid="2501">text</b><!-- react-text: 2502 --> — <!-- /react-text --><code data-reactid="2503">table.text(name, [textType])</code><p data-reactid="2504">Adds a text column, with optional textType for MySql text datatype preference. textType may be mediumtext or longtext, otherwise defaults to text.</p></div><div id="Schema-string" data-reactid="2505"><b data-reactid="2506">string</b><!-- react-text: 2507 --> — <!-- /react-text --><code data-reactid="2508">table.string(name, [length])</code><p data-reactid="2509">Adds a string column, with optional length defaulting to 255.</p></div><div id="Schema-float" data-reactid="2510"><b data-reactid="2511">float</b><!-- react-text: 2512 --> — <!-- /react-text --><code data-reactid="2513">table.float(column, [precision], [scale])</code><p data-reactid="2514">Adds a float column, with optional precision (defaults to 8) and scale (defaults to 2).</p></div><div id="Schema-decimal" data-reactid="2515"><b data-reactid="2516">decimal</b><!-- react-text: 2517 --> — <!-- /react-text --><code data-reactid="2518">table.decimal(column, [precision], [scale])</code><p data-reactid="2519">Adds a decimal column, with optional precision (defaults to 8) and scale (defaults to 2). Specifying NULL as precision creates a decimal column that can store numbers of any precision and scale. (Only supported for Oracle, SQLite, Postgres)</p></div><div id="Schema-boolean" data-reactid="2520"><b data-reactid="2521">boolean</b><!-- react-text: 2522 --> — <!-- /react-text --><code data-reactid="2523">table.boolean(name)</code><p data-reactid="2524">Adds a boolean column.</p></div><div id="Schema-date" data-reactid="2525"><b data-reactid="2526">date</b><!-- react-text: 2527 --> — <!-- /react-text --><code data-reactid="2528">table.date(name)</code><p data-reactid="2529">Adds a date column.</p></div><div id="Schema-datetime" data-reactid="2530"><b data-reactid="2531">datetime</b><!-- react-text: 2532 --> — <!-- /react-text --><code data-reactid="2533">table.datetime(name, options={[useTz: boolean], [precision: number]})</code><p data-reactid="2534">Adds a datetime column. By default PostgreSQL creates column with timezone (timestamptz type). This behaviour can be overriden by passing the useTz option (which is by default true for PostgreSQL). MySQL and MSSQL do not have useTz option.</p><p data-reactid="2535">A precision option may be passed:</p><pre data-reactid="2536"><code class="hljs js" data-reactid="2537">table.datetime(<span class="hljs-string">'some_time'</span>, { <span class="hljs-attr">precision</span>: <span class="hljs-number">6</span> }).defaultTo(knex.fn.now(<span class="hljs-number">6</span>))</code></pre></div><div id="Schema-time" data-reactid="2538"><b data-reactid="2539">time</b><!-- react-text: 2540 --> — <!-- /react-text --><code data-reactid="2541">table.time(name, [precision])</code><p data-reactid="2542">Adds a time column, with optional precision for MySQL. Not supported on Amazon Redshift.</p><p data-reactid="2543">In MySQL a precision option may be passed:</p><pre data-reactid="2544"><code class="hljs js" data-reactid="2545">table.time(<span class="hljs-string">'some_time'</span>, { <span class="hljs-attr">precision</span>: <span class="hljs-number">6</span> })</code></pre></div><div id="Schema-timestamp" data-reactid="2546"><b data-reactid="2547">timestamp</b><!-- react-text: 2548 --> — <!-- /react-text --><code data-reactid="2549">table.timestamp(name, options={[useTz: boolean], [precision: number]})</code><p data-reactid="2550">Adds a timestamp column. By default PostgreSQL creates column with timezone (timestamptz type) and MSSQL does not (datetime2). This behaviour can be overriden by passing the useTz option (which is by default false for MSSQL and true for PostgreSQL). MySQL does not have useTz option.</p><pre data-reactid="2551"><code class="hljs js" data-reactid="2552">table.timestamp(<span class="hljs-string">'created_at'</span>).defaultTo(knex.fn.now());</code></pre><p data-reactid="2553">In PostgreSQL and MySQL a precision option may be passed:</p><pre data-reactid="2554"><code class="hljs js" data-reactid="2555">table.timestamp(<span class="hljs-string">'created_at'</span>, { <span class="hljs-attr">precision</span>: <span class="hljs-number">6</span> }).defaultTo(knex.fn.now(<span class="hljs-number">6</span>));</code></pre><p data-reactid="2556">In PostgreSQL and MSSQL a timezone option may be passed:</p><pre data-reactid="2557"><code class="hljs js" data-reactid="2558">table.timestamp(<span class="hljs-string">'created_at'</span>, { <span class="hljs-attr">useTz</span>: <span class="hljs-literal">true</span> });</code></pre></div><div id="Schema-timestamps" data-reactid="2559"><b data-reactid="2560">timestamps</b><!-- react-text: 2561 --> — <!-- /react-text --><code data-reactid="2562">table.timestamps([useTimestamps], [defaultToNow])</code><p data-reactid="2563">Adds created_at and updated_at columns on the database, setting each to datetime types. When true is passed as the first argument a timestamp type is used instead. Both colums default to being not null and using the current timestamp when true is passed as the second argument. Note that on MySQL the .timestamps() only have seconds precision, to get better precision use the .datetime or .timestamp methods directly with precision.</p></div><div id="Schema-dropTimestamps" data-reactid="2564"><b data-reactid="2565">dropTimestamps</b><!-- react-text: 2566 --> — <!-- /react-text --><code data-reactid="2567">table.dropTimestamps()</code><p data-reactid="2568">Drops the columns created_at and updated_at from the table, which can be created via timestamps.</p></div><div id="Schema-binary" data-reactid="2569"><b data-reactid="2570">binary</b><!-- react-text: 2571 --> — <!-- /react-text --><code data-reactid="2572">table.binary(name, [length])</code><p data-reactid="2573">Adds a binary column, with optional length argument for MySQL.</p></div><div id="Schema-enum" data-reactid="2574"><b data-reactid="2575">enum / enu</b><!-- react-text: 2576 --> — <!-- /react-text --><code data-reactid="2577">table.enu(col, values, [options])</code><p data-reactid="2578">Adds a enum column, (aliased to enu, as enum is a reserved word in JavaScript). Implemented as unchecked varchar(255) on Amazon Redshift. Note that the second argument is an array of values. Example:</p><pre data-reactid="2579"><code class="hljs js" data-reactid="2580">table.enu(<span class="hljs-string">'column'</span>, [<span class="hljs-string">'value1'</span>, <span class="hljs-string">'value2'</span>])</code></pre><p data-reactid="2581">For Postgres, an additional options argument can be provided to specify whether or not to use Postgres's native TYPE:</p><pre data-reactid="2582"><code class="hljs js" data-reactid="2583">table.enu(<span class="hljs-string">'column'</span>, [<span class="hljs-string">'value1'</span>, <span class="hljs-string">'value2'</span>], { <span class="hljs-attr">useNative</span>: <span class="hljs-literal">true</span>, <span class="hljs-attr">enumName</span>: <span class="hljs-string">'foo_type'</span> })</code></pre><p data-reactid="2584">It will use the values provided to generate the appropriate TYPE. Example:</p><pre data-reactid="2585"><code class="hljs sql" data-reactid="2586"><span class="hljs-keyword">CREATE</span> <span class="hljs-keyword">TYPE</span> <span class="hljs-string">"foo_type"</span> <span class="hljs-keyword">AS</span> ENUM (<span class="hljs-string">'value1'</span>, <span class="hljs-string">'value2'</span>);</code></pre><p data-reactid="2587">To use an existing native type across columns, specify 'existingType' in the options (this assumes the type has already been created):</p><p class="info" data-reactid="2588">Note: Since the enum values aren't utilized for a native && existing type, the type being passed in for values is immaterial.</p><pre data-reactid="2589"><code class="hljs js" data-reactid="2590">table.enu(<span class="hljs-string">'column'</span>, <span class="hljs-literal">null</span>, { <span class="hljs-attr">useNative</span>: <span class="hljs-literal">true</span>, <span class="hljs-attr">existingType</span>: <span class="hljs-literal">true</span>, <span class="hljs-attr">enumName</span>: <span class="hljs-string">'foo_type'</span> })</code></pre><p data-reactid="2591">If you want to use existing enums from a schema, different from the schema of your current table, specify 'schemaName' in the options:</p><pre data-reactid="2592"><code class="hljs js" data-reactid="2593">table.enu(<span class="hljs-string">'column'</span>, <span class="hljs-literal">null</span>, { <span class="hljs-attr">useNative</span>: <span class="hljs-literal">true</span>, <span class="hljs-attr">existingType</span>: <span class="hljs-literal">true</span>, <span class="hljs-attr">enumName</span>: <span class="hljs-string">'foo_type'</span>, <span class="hljs-attr">schemaName</span>: <span class="hljs-string">'public'</span> })</code></pre></div><div id="Schema-json" data-reactid="2594"><b data-reactid="2595">json</b><!-- react-text: 2596 --> — <!-- /react-text --><code data-reactid="2597">table.json(name)</code><p data-reactid="2598">Adds a json column, using the built-in json type in PostgreSQL, MySQL and SQLite, defaulting to a text column in older versions or in unsupported databases.</p><p data-reactid="2599">For PostgreSQL, due to incompatibility between native array and json types, when setting an array (or a value that could be an array) as the value of a json or jsonb column, you should use JSON.stringify() to convert your value to a string prior to passing it to the query builder, e.g.</p><pre data-reactid="2600"><code class="hljs js" data-reactid="2601">knex.table(<span class="hljs-string">'users'</span>)
.where({<span class="hljs-attr">id</span>: <span class="hljs-number">1</span>})
.update({<span class="hljs-attr">json_data</span>: <span class="hljs-built_in">JSON</span>.stringify(mightBeAnArray)});</code></pre></div><div id="Schema-jsonb" data-reactid="2602"><b data-reactid="2603">jsonb</b><!-- react-text: 2604 --> — <!-- /react-text --><code data-reactid="2605">table.jsonb(name)</code><p data-reactid="2606">Adds a jsonb column. Works similar to table.json(), but uses native jsonb type if possible.</p></div><div id="Schema-uuid" data-reactid="2607"><b data-reactid="2608">uuid</b><!-- react-text: 2609 --> — <!-- /react-text --><code data-reactid="2610">table.uuid(name)</code><p data-reactid="2611">Adds a uuid column - this uses the built-in uuid type in PostgreSQL, and falling back to a char(36) in other databases.</p></div><div id="Schema-comment" data-reactid="2612"><b data-reactid="2613">comment</b><!-- react-text: 2614 --> — <!-- /react-text --><code data-reactid="2615">table.comment(value)</code><p data-reactid="2616">Sets the comment for a table.</p></div><div id="Schema-engine" data-reactid="2617"><b data-reactid="2618">engine</b><!-- react-text: 2619 --> — <!-- /react-text --><code data-reactid="2620">table.engine(val)</code><p data-reactid="2621">Sets the engine for the database table, only available within a createTable call, and only applicable to MySQL.</p></div><div id="Schema-charset" data-reactid="2622"><b data-reactid="2623">charset</b><!-- react-text: 2624 --> — <!-- /react-text --><code data-reactid="2625">table.charset(val)</code><p data-reactid="2626">Sets the charset for the database table, only available within a createTable call, and only applicable to MySQL.</p></div><div id="Schema-collate" data-reactid="2627"><b data-reactid="2628">collate</b><!-- react-text: 2629 --> — <!-- /react-text --><code data-reactid="2630">table.collate(val)</code><p data-reactid="2631">Sets the collation for the database table, only available within a createTable call, and only applicable to MySQL.</p></div><div id="Schema-inherits" data-reactid="2632"><b data-reactid="2633">inherits</b><!-- react-text: 2634 --> — <!-- /react-text --><code data-reactid="2635">table.inherits(val)</code><p data-reactid="2636">Sets the tables that this table inherits, only available within a createTable call, and only applicable to PostgreSQL.</p></div><div id="Schema-specificType" data-reactid="2637"><b data-reactid="2638">specificType</b><!-- react-text: 2639 --> — <!-- /react-text --><code data-reactid="2640">table.specificType(name, type)</code><p data-reactid="2641">Sets a specific type for the column creation, if you'd like to add a column type that isn't supported here.</p></div><div id="Schema-index" data-reactid="2642"><b data-reactid="2643">index</b><!-- react-text: 2644 --> — <!-- /react-text --><code data-reactid="2645">table.index(columns, [indexName], [indexType])</code><p data-reactid="2646">Adds an index to a table over the given columns. A default index name using the columns is used unless indexName is specified. The indexType can be optionally specified for PostgreSQL and MySQL. Amazon Redshift does not allow creating an index.</p></div><div id="Schema-dropIndex" data-reactid="2647"><b data-reactid="2648">dropIndex</b><!-- react-text: 2649 --> — <!-- /react-text --><code data-reactid="2650">table.dropIndex(columns, [indexName])</code><p data-reactid="2651">Drops an index from a table. A default index name using the columns is used unless indexName is specified (in which case columns is ignored). Amazon Redshift does not allow creating an index.</p></div><div id="Schema-unique" data-reactid="2652"><b data-reactid="2653">unique</b><!-- react-text: 2654 --> — <!-- /react-text --><code data-reactid="2655">table.unique(columns, [indexName])</code><p data-reactid="2656">Adds an unique index to a table over the given <code>columns</code>. A default index name using the columns is used unless indexName is specified.</p><pre data-reactid="2657"><code class="hljs js" data-reactid="2658">knex.schema.alterTable(<span class="hljs-string">'users'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">t</span>) </span>{
t.unique(<span class="hljs-string">'email'</span>)
})
knex.schema.alterTable(<span class="hljs-string">'job'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">t</span>) </span>{
t.unique([<span class="hljs-string">'account_id'</span>, <span class="hljs-string">'program_id'</span>])
})</code></pre></div><div id="Schema-foreign" data-reactid="2659"><b data-reactid="2660">foreign</b><!-- react-text: 2661 --> — <!-- /react-text --><code data-reactid="2662">table.foreign(columns, [foreignKeyName])[.onDelete(statement).onUpdate(statement).withKeyName(foreignKeyName)]</code><p data-reactid="2663">Adds a foreign key constraint to a table for an existing column using <code>table.foreign(column).references(column)</code> or multiple columns using <code>table.foreign(columns).references(columns).inTable(table)</code>. A default key name using the columns is used unless foreignKeyName is specified. You can also chain onDelete() and/or onUpdate() to set the reference option (RESTRICT, CASCADE, SET NULL, NO ACTION) for the operation. You can also chain withKeyName() to override default key name that is generated from table and column names (result is identical to specifying second parameter to function foreign()). Note that using foreign() is the same as column.references(column) but it works for existing columns.</p><pre data-reactid="2664"><code class="hljs js" data-reactid="2665">knex.schema.table(<span class="hljs-string">'users'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">table</span>) </span>{
table.integer(<span class="hljs-string">'user_id'</span>).unsigned()
table.foreign(<span class="hljs-string">'user_id'</span>).references(<span class="hljs-string">'Items.user_id_in_items'</span>)
})</code></pre></div><div id="Schema-dropForeign" data-reactid="2666"><b data-reactid="2667">dropForeign</b><!-- react-text: 2668 --> — <!-- /react-text --><code data-reactid="2669">table.dropForeign(columns, [foreignKeyName])</code><p data-reactid="2670">Drops a foreign key constraint from a table. A default foreign key name using the columns is used unless foreignKeyName is specified (in which case columns is ignored).</p></div><div id="Schema-dropUnique" data-reactid="2671"><b data-reactid="2672">dropUnique</b><!-- react-text: 2673 --> — <!-- /react-text --><code data-reactid="2674">table.dropUnique(columns, [indexName])</code><p data-reactid="2675">Drops a unique key constraint from a table. A default unique key name using the columns is used unless indexName is specified (in which case columns is ignored).</p></div><div id="Schema-dropPrimary" data-reactid="2676"><b data-reactid="2677">dropPrimary</b><!-- react-text: 2678 --> — <!-- /react-text --><code data-reactid="2679">table.dropPrimary([constraintName])</code><p data-reactid="2680">Drops the primary key constraint on a table. Defaults to tablename_pkey unless constraintName is specified.</p></div><div id="Schema-table-queryContext" data-reactid="2681"><b data-reactid="2682">queryContext</b><!-- react-text: 2683 --> — <!-- /react-text --><code data-reactid="2684">table.queryContext(context)</code><p data-reactid="2685">Allows configuring a context to be passed to the <a href="#Installation-wrap-identifier">wrapIdentifier</a> hook for formatting table builder identifiers. The context can be any kind of value and will be passed to <code>wrapIdentifier</code> without modification.</p><pre data-reactid="2686"><code class="hljs js" data-reactid="2687">knex.schema.table(<span class="hljs-string">'users'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">table</span>) </span>{
table.queryContext({ <span class="hljs-attr">foo</span>: <span class="hljs-string">'bar'</span> });
table.string(<span class="hljs-string">'first_name'</span>);
table.string(<span class="hljs-string">'last_name'</span>);
})</code></pre><p data-reactid="2688">This method also enables overwriting the context configured for a schema builder instance via <a href="#Schema-queryContext">schema.queryContext</a>:</p><pre data-reactid="2689"><code class="hljs js" data-reactid="2690">knex.schema.queryContext(<span class="hljs-string">'schema context'</span>)
.table(<span class="hljs-string">'users'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">table</span>) </span>{
table.queryContext(<span class="hljs-string">'table context'</span>);
table.string(<span class="hljs-string">'first_name'</span>);
table.string(<span class="hljs-string">'last_name'</span>);
})</code></pre><p data-reactid="2691">Note that it's also possible to overwrite the table builder context for any column in the table definition:</p><pre data-reactid="2692"><code class="hljs js" data-reactid="2693">knex.schema.queryContext(<span class="hljs-string">'schema context'</span>)
.table(<span class="hljs-string">'users'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">table</span>) </span>{
table.queryContext(<span class="hljs-string">'table context'</span>);
table.string(<span class="hljs-string">'first_name'</span>).queryContext(<span class="hljs-string">'first_name context'</span>);
table.string(<span class="hljs-string">'last_name'</span>).queryContext(<span class="hljs-string">'last_name context'</span>);
})</code></pre><p data-reactid="2694">Calling <code>queryContext</code> with no arguments will return any context configured for the table builder instance.</p></div><h3 id="Chainable" data-reactid="2695">Chainable Methods:</h3><p data-reactid="2696">The following three methods may be chained on the schema building methods, as modifiers to the column.</p><div id="Schema-alter" data-reactid="2697"><b data-reactid="2698">alter</b><!-- react-text: 2699 --> — <!-- /react-text --><code data-reactid="2700">column.alter()</code><p data-reactid="2701">Marks the column as an alter / modify, instead of the default add. Note: This only works in .alterTable() and is not supported by SQlite or Amazon Redshift. Alter is <em>not</em> done incrementally over older column type so if you like to add <code>notNull</code> and keep the old default value, the alter statement must contain both <code>.notNull().defaultTo(1).alter()</code>. If one just tries to add <code>.notNull().alter()</code> the old default value will be dropped.</p></div><pre data-reactid="2702"><code data-reactid="2703">knex.schema.alterTable('user', function(t) {
t.increments().primary(); // add
// drops previous default value from column, change type to string and add not nullable constraint
t.string('username', 35).notNullable().alter();
// drops both not null constraint and the default value
t.integer('age').alter();
});</code></pre><div id="Schema-index" data-reactid="2704"><b data-reactid="2705">index</b><!-- react-text: 2706 --> — <!-- /react-text --><code data-reactid="2707">column.index([indexName], [indexType])</code><p data-reactid="2708">Specifies a field as an index. If an indexName is specified, it is used in place of the standard index naming convention of tableName_columnName. The indexType can be optionally specified for PostgreSQL and MySQL. No-op if this is chained off of a field that cannot be indexed.</p></div><div id="Schema-primary" data-reactid="2709"><b data-reactid="2710">primary</b><!-- react-text: 2711 --> — <!-- /react-text --><code data-reactid="2712">column.primary([constraintName]); table.primary(columns, [constraintName])</code><p data-reactid="2713">When called on a single column it will set that column as the primary key for a table. If you need to create a composite primary key, call it on a table with an array of column names instead. Constraint name defaults to <code>tablename_pkey</code> unless <code>constraintName</code> is specified. On Amazon Redshift, all columns included in a primary key must be not nullable.</p></div><div id="Schema-unique" data-reactid="2714"><b data-reactid="2715">unique</b><!-- react-text: 2716 --> — <!-- /react-text --><code data-reactid="2717">column.unique()</code><p data-reactid="2718">Sets the column as unique. On Amazon Redshift, this constraint is not enforced, but it is used by the query planner.</p></div><div id="Schema-references" data-reactid="2719"><b data-reactid="2720">references</b><!-- react-text: 2721 --> — <!-- /react-text --><code data-reactid="2722">column.references(column)</code><p data-reactid="2723">Sets the "column" that the current column references as a foreign key. "column" can either be ".<column>" syntax, or just the column name followed up with a call to inTable to specify the table.</column><table></table></p></div><div id="Schema-inTable" data-reactid="2724"><b data-reactid="2725">inTable</b><!-- react-text: 2726 --> — <!-- /react-text --><code data-reactid="2727">column.inTable(table)</code><p data-reactid="2728">Sets the "table" where the foreign key column is located after calling column.references.</p></div><div id="Schema-onDelete" data-reactid="2729"><b data-reactid="2730">onDelete</b><!-- react-text: 2731 --> — <!-- /react-text --><code data-reactid="2732">column.onDelete(command)</code><p data-reactid="2733">Sets the SQL command to be run "onDelete".</p></div><div id="Schema-onUpdate" data-reactid="2734"><b data-reactid="2735">onUpdate</b><!-- react-text: 2736 --> — <!-- /react-text --><code data-reactid="2737">column.onUpdate(command)</code><p data-reactid="2738">Sets the SQL command to be run "onUpdate".</p></div><div id="Schema-defaultTo" data-reactid="2739"><b data-reactid="2740">defaultTo</b><!-- react-text: 2741 --> — <!-- /react-text --><code data-reactid="2742">column.defaultTo(value)</code><p data-reactid="2743">Sets the default value for the column on an insert.</p></div><div id="Schema-unsigned" data-reactid="2744"><b data-reactid="2745">unsigned</b><!-- react-text: 2746 --> — <!-- /react-text --><code data-reactid="2747">column.unsigned()</code><p data-reactid="2748">Specifies an integer as unsigned. No-op if this is chained off of a non-integer field.</p></div><div id="Schema-notNullable" data-reactid="2749"><b data-reactid="2750">notNullable</b><!-- react-text: 2751 --> — <!-- /react-text --><code data-reactid="2752">column.notNullable()</code><p data-reactid="2753">Adds a not null on the current column being created.</p></div><div id="Schema-nullable" data-reactid="2754"><b data-reactid="2755">nullable</b><!-- react-text: 2756 --> — <!-- /react-text --><code data-reactid="2757">column.nullable()</code><p data-reactid="2758">Default on column creation, this explicitly sets a field to be nullable.</p></div><div id="Schema-first" data-reactid="2759"><b data-reactid="2760">first</b><!-- react-text: 2761 --> — <!-- /react-text --><code data-reactid="2762">column.first()</code><p data-reactid="2763">Sets the column to be inserted on the first position, only used in MySQL alter tables.</p></div><div id="Schema-after" data-reactid="2764"><b data-reactid="2765">after</b><!-- react-text: 2766 --> — <!-- /react-text --><code data-reactid="2767">column.after(field)</code><p data-reactid="2768">Sets the column to be inserted after another, only used in MySQL alter tables.</p></div><div id="Column-comment" data-reactid="2769"><b data-reactid="2770">comment</b><!-- react-text: 2771 --> — <!-- /react-text --><code data-reactid="2772">column.comment(value)</code><p data-reactid="2773">Sets the comment for a column.</p></div><pre data-reactid="2774"><code data-reactid="2775">knex.schema.createTable('accounts', function(t) {
t.increments().primary();
t.string('email').unique().comment('This is the email field');
});</code></pre><div id="Column-collate" data-reactid="2776"><b data-reactid="2777">collate</b><!-- react-text: 2778 --> — <!-- /react-text --><code data-reactid="2779">column.collate(collation)</code><p data-reactid="2780">Sets the collation for a column (only works in MySQL). Here is a list of all available collations: <a href="https://dev.mysql.com/doc/refman/5.5/en/charset-charsets.html">https://dev.mysql.com/doc/refman/5.5/en/charset-charsets.html</a></p></div><pre data-reactid="2781"><code data-reactid="2782">knex.schema.createTable('users', function(t) {
t.increments();
t.string('email').unique().collate('utf8_unicode_ci');
});</code></pre></div><div id="Raw" data-reactid="2783"><h2 id="Raw" data-reactid="2784">Raw</h2><p data-reactid="2785">Sometimes you may need to use a raw expression in a query. Raw query object may be injected pretty much anywhere you want, and using proper bindings can ensure your values are escaped properly, preventing SQL-injection attacks.</p><h3 id="Raw-Bindings" data-reactid="2786">Raw Parameter Binding:</h3><p data-reactid="2787">One can paramterize sql given to <code>knex.raw(sql, bindings)</code>. Parameters can be positional named. One can also choose if parameter should be treated as value or as sql identifier e.g. in case of <code>'TableName.ColumnName'</code> reference.</p><pre class="display" data-reactid="2788"><code class="js hljs" data-reactid="2789">knex(<span class="hljs-string">'users'</span>)
.select(knex.raw(<span class="hljs-string">'count(*) as user_count, status'</span>))
.where(knex.raw(<span class="hljs-number">1</span>))
.orWhere(knex.raw(<span class="hljs-string">'status <> ?'</span>, [<span class="hljs-number">1</span>]))
.groupBy(<span class="hljs-string">'status'</span>)</code><br data-reactid="2790"/><!-- react-text: 2791 -->Outputs:<!-- /react-text --><br data-reactid="2792"/><code class="sql hljs" data-reactid="2793"><span class="hljs-keyword">select</span> <span class="hljs-keyword">count</span>(*) <span class="hljs-keyword">as</span> user_count, <span class="hljs-keyword">status</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-number">1</span> <span class="hljs-keyword">or</span> <span class="hljs-keyword">status</span> <> <span class="hljs-number">1</span> <span class="hljs-keyword">group</span> <span class="hljs-keyword">by</span> <span class="hljs-string">`status`</span></code></pre><p data-reactid="2794">Positional bindings <code>?</code> are interpreted as values and <code>??</code> are interpreted as identifiers.</p><pre class="display" data-reactid="2795"><code class="js hljs" data-reactid="2796">knex(<span class="hljs-string">'users'</span>).where(knex.raw(<span class="hljs-string">'?? = ?'</span>, [<span class="hljs-string">'user.name'</span>, <span class="hljs-number">1</span>]))</code><br data-reactid="2797"/><!-- react-text: 2798 -->Outputs:<!-- /react-text --><br data-reactid="2799"/><code class="sql hljs" data-reactid="2800"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`user`</span>.<span class="hljs-string">`name`</span> = <span class="hljs-number">1</span></code></pre><p data-reactid="2801">Named bindings such as <code>:name</code> are interpreted as values and <code>:name:</code> interpreted as identifiers. Named bindings are processed so long as the value is anything other than <code>undefined</code>.</p><pre class="display" data-reactid="2802"><code class="js hljs" data-reactid="2803">knex(<span class="hljs-string">'users'</span>)
.where(knex.raw(<span class="hljs-string">':name: = :thisGuy or :name: = :otherGuy or :name: = :undefinedBinding'</span>, {
<span class="hljs-attr">name</span>: <span class="hljs-string">'users.name'</span>,
<span class="hljs-attr">thisGuy</span>: <span class="hljs-string">'Bob'</span>,
<span class="hljs-attr">otherGuy</span>: <span class="hljs-string">'Jay'</span>,
<span class="hljs-attr">undefinedBinding</span>: <span class="hljs-literal">undefined</span>
}))</code><br data-reactid="2804"/><!-- react-text: 2805 -->Error:<!-- /react-text --><br data-reactid="2806"/><code class="sql hljs" data-reactid="2807">Undefined binding(s) detected for keys [undefinedBinding] when compiling RAW query: `users`.`name` = ? or `users`.`name` = ? or `users`.`name` = :undefinedBinding</code></pre><p data-reactid="2808">For simpler queries where one only has a single binding, <code>.raw</code> can accept said binding as its second parameter.</p><pre class="display" data-reactid="2809"><code class="js hljs" data-reactid="2810">knex(<span class="hljs-string">'users'</span>)
.where(
knex.raw(<span class="hljs-string">'LOWER("login") = ?'</span>, <span class="hljs-string">'knex'</span>)
)
.orWhere(
knex.raw(<span class="hljs-string">'accesslevel = ?'</span>, <span class="hljs-number">1</span>)
)
.orWhere(
knex.raw(<span class="hljs-string">'updtime = ?'</span>, <span class="hljs-keyword">new</span> <span class="hljs-built_in">Date</span>.UTC(<span class="hljs-string">'01-01-2016'</span>))
)</code><br data-reactid="2811"/><!-- react-text: 2812 -->Error:<!-- /react-text --><br data-reactid="2813"/><code class="sql hljs" data-reactid="2814">Date.UTC is not a constructor</code></pre><p data-reactid="2815">Since there is no unified syntax for array bindings, instead you need to treat them as multiple values by adding <code>?</code> directly in your query.</p><pre class="display" data-reactid="2816"><code class="js hljs" data-reactid="2817"><span class="hljs-keyword">const</span> myArray = [<span class="hljs-number">1</span>,<span class="hljs-number">2</span>,<span class="hljs-number">3</span>]
knex.raw(<span class="hljs-string">'select * from users where id in ('</span> + myArray.map(<span class="hljs-function"><span class="hljs-params">_</span> =></span> <span class="hljs-string">'?'</span>).join(<span class="hljs-string">','</span>) + <span class="hljs-string">')'</span>, [...myArray]);
<span class="hljs-comment">// query will become: select * from users where id in (?, ?, ?) with bindings [1,2,3]</span></code><br data-reactid="2818"/><!-- react-text: 2819 -->Error:<!-- /react-text --><br data-reactid="2820"/><code class="sql hljs" data-reactid="2821">Unexpected token const</code></pre><p data-reactid="2822">To prevent replacement of <code>?</code> one can use the escape sequence <code>\\?</code>.</p><pre class="display" data-reactid="2823"><code class="js hljs" data-reactid="2824">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).where(<span class="hljs-string">'id'</span>, <span class="hljs-string">'='</span>, <span class="hljs-number">1</span>).whereRaw(<span class="hljs-string">'?? \\? ?'</span>, [<span class="hljs-string">'jsonColumn'</span>, <span class="hljs-string">'jsonKey'</span>])</code><br data-reactid="2825"/><!-- react-text: 2826 -->Outputs:<!-- /react-text --><br data-reactid="2827"/><code class="sql hljs" data-reactid="2828"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`id`</span> = <span class="hljs-number">1</span> <span class="hljs-keyword">and</span> <span class="hljs-string">`jsonColumn`</span> ? <span class="hljs-string">'jsonKey'</span></code></pre><p data-reactid="2829">To prevent replacement of named bindings one can use the escape sequence <code>\\:</code>.</p><pre class="display" data-reactid="2830"><code class="js hljs" data-reactid="2831">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).whereRaw(<span class="hljs-string">":property: = '\\:value' OR \\:property: = :value"</span>, {
<span class="hljs-attr">property</span>: <span class="hljs-string">'name'</span>,
<span class="hljs-attr">value</span>: <span class="hljs-string">'Bob'</span>
})</code><br data-reactid="2832"/><!-- react-text: 2833 -->Outputs:<!-- /react-text --><br data-reactid="2834"/><code class="sql hljs" data-reactid="2835"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`name`</span> = <span class="hljs-string">':value'</span> <span class="hljs-keyword">OR</span> :property: = <span class="hljs-string">'Bob'</span></code></pre><h3 id="Raw-Expressions" data-reactid="2836">Raw Expressions:</h3><p data-reactid="2837">Raw expressions are created by using <code>knex.raw(sql, [bindings])</code> and passing this as a value for any value in the query chain.</p><pre class="display" data-reactid="2838"><code class="js hljs" data-reactid="2839">knex(<span class="hljs-string">'users'</span>)
.select(knex.raw(<span class="hljs-string">'count(*) as user_count, status'</span>))
.where(knex.raw(<span class="hljs-number">1</span>))
.orWhere(knex.raw(<span class="hljs-string">'status <> ?'</span>, [<span class="hljs-number">1</span>]))
.groupBy(<span class="hljs-string">'status'</span>)</code><br data-reactid="2840"/><!-- react-text: 2841 -->Outputs:<!-- /react-text --><br data-reactid="2842"/><code class="sql hljs" data-reactid="2843"><span class="hljs-keyword">select</span> <span class="hljs-keyword">count</span>(*) <span class="hljs-keyword">as</span> user_count, <span class="hljs-keyword">status</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span> <span class="hljs-keyword">where</span> <span class="hljs-number">1</span> <span class="hljs-keyword">or</span> <span class="hljs-keyword">status</span> <> <span class="hljs-number">1</span> <span class="hljs-keyword">group</span> <span class="hljs-keyword">by</span> <span class="hljs-string">`status`</span></code></pre><h3 id="Raw-Queries" data-reactid="2844">Raw Queries:</h3><p data-reactid="2845">The <code>knex.raw</code> may also be used to build a full query and execute it, as a standard query builder query would be executed. The benefit of this is that it uses the connection pool and provides a standard interface for the different client libraries.</p><pre data-reactid="2846"><code class="hljs js" data-reactid="2847">knex.raw(<span class="hljs-string">'select * from users where id = ?'</span>, [<span class="hljs-number">1</span>]).then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">resp</span>) </span>{ ... });</code></pre><p class="info" data-reactid="2848">Note that the response will be whatever the underlying sql library would typically return on a 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.</p><h3 id="Raw-queries-wrapped" data-reactid="2849">Wrapped Queries:</h3><p data-reactid="2850">The raw query builder also comes with a <code>wrap</code> method, which allows wrapping the query in a value:</p><pre class="display" data-reactid="2851"><code class="js hljs" data-reactid="2852"><span class="hljs-keyword">var</span> subcolumn = knex.raw(<span class="hljs-string">'select avg(salary) from employee where dept_no = e.dept_no'</span>)
.wrap(<span class="hljs-string">'('</span>, <span class="hljs-string">') avg_sal_dept'</span>);
knex.select(<span class="hljs-string">'e.lastname'</span>, <span class="hljs-string">'e.salary'</span>, subcolumn)
.from(<span class="hljs-string">'employee as e'</span>)
.whereRaw(<span class="hljs-string">'dept_no = e.dept_no'</span>)</code><br data-reactid="2853"/><!-- react-text: 2854 -->Outputs:<!-- /react-text --><br data-reactid="2855"/><code class="sql hljs" data-reactid="2856"><span class="hljs-keyword">select</span> <span class="hljs-string">`e`</span>.<span class="hljs-string">`lastname`</span>, <span class="hljs-string">`e`</span>.<span class="hljs-string">`salary`</span>, (<span class="hljs-keyword">select</span> <span class="hljs-keyword">avg</span>(salary) <span class="hljs-keyword">from</span> employee <span class="hljs-keyword">where</span> dept_no = e.dept_no) avg_sal_dept <span class="hljs-keyword">from</span> <span class="hljs-string">`employee`</span> <span class="hljs-keyword">as</span> <span class="hljs-string">`e`</span> <span class="hljs-keyword">where</span> dept_no = e.dept_no</code></pre><p data-reactid="2857">Note that the example above be achieved more easily using the <a href="#Builder-as">as</a> method.</p><pre class="display" data-reactid="2858"><code class="js hljs" data-reactid="2859"><span class="hljs-keyword">var</span> subcolumn = knex.avg(<span class="hljs-string">'salary'</span>)
.from(<span class="hljs-string">'employee'</span>)
.whereRaw(<span class="hljs-string">'dept_no = e.dept_no'</span>)
.as(<span class="hljs-string">'avg_sal_dept'</span>);
knex.select(<span class="hljs-string">'e.lastname'</span>, <span class="hljs-string">'e.salary'</span>, subcolumn)
.from(<span class="hljs-string">'employee as e'</span>)
.whereRaw(<span class="hljs-string">'dept_no = e.dept_no'</span>)</code><br data-reactid="2860"/><!-- react-text: 2861 -->Outputs:<!-- /react-text --><br data-reactid="2862"/><code class="sql hljs" data-reactid="2863"><span class="hljs-keyword">select</span> <span class="hljs-string">`e`</span>.<span class="hljs-string">`lastname`</span>, <span class="hljs-string">`e`</span>.<span class="hljs-string">`salary`</span>, (<span class="hljs-keyword">select</span> <span class="hljs-keyword">avg</span>(<span class="hljs-string">`salary`</span>) <span class="hljs-keyword">from</span> <span class="hljs-string">`employee`</span> <span class="hljs-keyword">where</span> dept_no = e.dept_no) <span class="hljs-keyword">as</span> <span class="hljs-string">`avg_sal_dept`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`employee`</span> <span class="hljs-keyword">as</span> <span class="hljs-string">`e`</span> <span class="hljs-keyword">where</span> dept_no = e.dept_no</code></pre></div><div id="Ref" data-reactid="2864"><h2 id="Ref" data-reactid="2865">Ref</h2><p data-reactid="2866">Can be used to create references in a query, such as column- or tablenames. This is a good and shorter alternative to using <code>knex.raw('??', 'tableName.columName') which essentially does the same thing.</code></p><h3 id="Ref-Usage" data-reactid="2867">Usage:</h3><p data-reactid="2868"><code>knex.ref</code> can be used essentially anywhere in a build-chain. Here is an example:</p><pre class="display" data-reactid="2869"><code class="js hljs" data-reactid="2870">knex(knex.ref(<span class="hljs-string">'Users'</span>).withSchema(<span class="hljs-string">'TenantId'</span>))
.where(knex.ref(<span class="hljs-string">'Id'</span>), <span class="hljs-number">1</span>)
.orWhere(knex.ref(<span class="hljs-string">'Name'</span>), <span class="hljs-string">'Admin'</span>)
.select([<span class="hljs-string">'Id'</span>, knex.ref(<span class="hljs-string">'Name'</span>).as(<span class="hljs-string">'Username'</span>)])</code><br data-reactid="2871"/><!-- react-text: 2872 -->Outputs:<!-- /react-text --><br data-reactid="2873"/><code class="sql hljs" data-reactid="2874"><span class="hljs-keyword">select</span> <span class="hljs-string">`Id`</span>, <span class="hljs-string">`Name`</span> <span class="hljs-keyword">as</span> <span class="hljs-string">`Username`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`TenantId`</span>.<span class="hljs-string">`Users`</span> <span class="hljs-keyword">where</span> <span class="hljs-string">`Id`</span> = <span class="hljs-number">1</span> <span class="hljs-keyword">or</span> <span class="hljs-string">`Name`</span> = <span class="hljs-string">'Admin'</span></code></pre><h3 id="Ref-withSchema" data-reactid="2875">withSchema:</h3><p data-reactid="2876">The Ref function supports schema using <code>.withSchema(string)</code>:</p><pre class="display" data-reactid="2877"><code class="js hljs" data-reactid="2878">knex(knex.ref(<span class="hljs-string">'users'</span>).withSchema(<span class="hljs-string">'TenantId'</span>)).select()</code><br data-reactid="2879"/><!-- react-text: 2880 -->Outputs:<!-- /react-text --><br data-reactid="2881"/><code class="sql hljs" data-reactid="2882"><span class="hljs-keyword">select</span> * <span class="hljs-keyword">from</span> <span class="hljs-string">`TenantId`</span>.<span class="hljs-string">`users`</span></code></pre><h3 id="Ref-alias" data-reactid="2883">alias:</h3><p data-reactid="2884">Alias is supported using <code>.alias(string)</code></p><pre class="display" data-reactid="2885"><code class="js hljs" data-reactid="2886">knex(<span class="hljs-string">'users'</span>)
.select(knex.ref(<span class="hljs-string">'Id'</span>).as(<span class="hljs-string">'UserId'</span>))</code><br data-reactid="2887"/><!-- react-text: 2888 -->Outputs:<!-- /react-text --><br data-reactid="2889"/><code class="sql hljs" data-reactid="2890"><span class="hljs-keyword">select</span> <span class="hljs-string">`Id`</span> <span class="hljs-keyword">as</span> <span class="hljs-string">`UserId`</span> <span class="hljs-keyword">from</span> <span class="hljs-string">`users`</span></code></pre></div><div id="Utility" data-reactid="2891"><h2 id="Utility" data-reactid="2892">Utility</h2><p data-reactid="2893">A collection of utilities that the knex library provides for convenience.</p><h3 id="Utility-BatchInsert" data-reactid="2894">Batch Insert</h3><div data-reactid="2895"><p data-reactid="2896">The <code>batchInsert</code> utility will insert a batch of rows wrapped inside a transaction <em>(which is automatically created unless explicitly given a transaction using <a href="#Builder-transacting">transacting</a>)</em>, at a given <code>chunkSize</code>.</p><p data-reactid="2897">It's primarily designed to be used when you have thousands of rows to insert into a table.</p><p data-reactid="2898">By default, the <code>chunkSize</code> is set to 1000.</p><p data-reactid="2899">BatchInsert also allows for <a href="#Builder-returning">returning values</a> and supplying transactions using <a href="#Builder-transacting">transacting</a>.</p></div><pre data-reactid="2900"><code class="hljs js" data-reactid="2901"><span class="hljs-keyword">var</span> rows = [{...}, {...}];
<span class="hljs-keyword">var</span> chunkSize = <span class="hljs-number">30</span>;
knex.batchInsert(<span class="hljs-string">'TableName'</span>, rows, chunkSize)
.returning(<span class="hljs-string">'id'</span>)
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">ids</span>) </span>{ ... })
.catch(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">error</span>) </span>{ ... });
knex.transaction(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">tr</span>) </span>{
<span class="hljs-keyword">return</span> knex.batchInsert(<span class="hljs-string">'TableName'</span>, rows, chunkSize)
.transacting(tr)
})
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{ ... })
.catch(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">error</span>) </span>{ ... });</code></pre></div><div id="Interfaces" data-reactid="2902"><h2 id="Interfaces" data-reactid="2903">Interfaces</h2><p data-reactid="2904">Knex.js provides several options to deal with query output. The following methods are present on the query builder, schema builder, and the raw builder:</p><h3 id="Interfaces-Promises" data-reactid="2905">Promises</h3><p data-reactid="2906"><a href="https://github.com/petkaantonov/bluebird#what-are-promises-and-why-should-i-use-them">Promises</a> are the preferred way of dealing with queries in knex, as they allow you to return values from a fulfillment handler, which in turn become the value of the promise. The main benefit of promises are the ability to catch thrown errors without crashing the node app, making your code behave like a <strong>.try / .catch / .finally</strong> in synchronous code.</p><pre data-reactid="2907"><code class="hljs js" data-reactid="2908">knex.select(<span class="hljs-string">'name'</span>)
.from(<span class="hljs-string">'users'</span>)
.where(<span class="hljs-string">'id'</span>, <span class="hljs-string">'>'</span>, <span class="hljs-number">20</span>)
.andWhere(<span class="hljs-string">'id'</span>, <span class="hljs-string">'<'</span>, <span class="hljs-number">200</span>)
.limit(<span class="hljs-number">10</span>)
.offset(x)
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">rows</span>) </span>{
<span class="hljs-keyword">return</span> _.pluck(rows, <span class="hljs-string">'name'</span>);
})
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">names</span>) </span>{
<span class="hljs-keyword">return</span> knex.select(<span class="hljs-string">'id'</span>).from(<span class="hljs-string">'nicknames'</span>).whereIn(<span class="hljs-string">'nickname'</span>, names);
})
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">rows</span>) </span>{
<span class="hljs-built_in">console</span>.log(rows);
})
.catch(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">error</span>) </span>{
<span class="hljs-built_in">console</span>.error(error)
});</code></pre><div id="Interfaces-then" data-reactid="2909"><b data-reactid="2910">then</b><!-- react-text: 2911 --> — <!-- /react-text --><code data-reactid="2912">.then(onFulfilled, [onRejected])</code><p data-reactid="2913">Coerces the current query builder chain into a promise state, accepting the resolve and reject handlers as specified by the Promises/A+ spec. As stated in the spec, more than one call to the then 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><pre data-reactid="2914"><code class="hljs js" data-reactid="2915">knex.select(<span class="hljs-string">'*'</span>)
.from(<span class="hljs-string">'users'</span>)
.where({<span class="hljs-attr">name</span>: <span class="hljs-string">'Tim'</span>})
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">rows</span>) </span>{
<span class="hljs-keyword">return</span> knex.insert({<span class="hljs-attr">user_id</span>: rows[<span class="hljs-number">0</span>].id, <span class="hljs-attr">name</span>: <span class="hljs-string">'Test'</span>}, <span class="hljs-string">'id'</span>).into(<span class="hljs-string">'accounts'</span>);
})
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">id</span>) </span>{
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'Inserted Account '</span> + id);
})
.catch(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">error</span>) </span>{ <span class="hljs-built_in">console</span>.error(error); });</code></pre></div><div id="Interfaces-catch" data-reactid="2916"><b data-reactid="2917">catch</b><!-- react-text: 2918 --> — <!-- /react-text --><code data-reactid="2919">.catch(onRejected)</code><p data-reactid="2920">Coerces the current query builder into a promise state, catching any error thrown by the query, the same as calling .then(null, onRejected).</p><pre data-reactid="2921"><code class="hljs js" data-reactid="2922"><span class="hljs-keyword">return</span> knex.insert({<span class="hljs-attr">id</span>: <span class="hljs-number">1</span>, <span class="hljs-attr">name</span>: <span class="hljs-string">'Test'</span>}, <span class="hljs-string">'id'</span>)
.into(<span class="hljs-string">'accounts'</span>)
.catch(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">error</span>) </span>{
<span class="hljs-built_in">console</span>.error(error);
}).then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">return</span> knex.select(<span class="hljs-string">'*'</span>)
.from(<span class="hljs-string">'accounts'</span>)
.where(<span class="hljs-string">'id'</span>, <span class="hljs-number">1</span>);
}).then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">rows</span>) </span>{
<span class="hljs-built_in">console</span>.log(rows[<span class="hljs-number">0</span>]);
})
.catch(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">error</span>) </span>{
<span class="hljs-built_in">console</span>.error(error);
});</code></pre></div><div id="Interfaces-return" data-reactid="2923"><b data-reactid="2924">return</b><!-- react-text: 2925 --> — <!-- /react-text --><code data-reactid="2926">.return(value)</code><p data-reactid="2927">Shorthand for calling .then(function() { return value }).</p><pre data-reactid="2928"><code class="hljs js" data-reactid="2929"><span class="hljs-comment">// Without return:</span>
knex.insert(values).into(<span class="hljs-string">'users'</span>)
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">return</span> {<span class="hljs-attr">inserted</span>: <span class="hljs-literal">true</span>};
});
knex.insert(values).into(<span class="hljs-string">'users'</span>).return({<span class="hljs-attr">inserted</span>: <span class="hljs-literal">true</span>});</code></pre></div><h3 id="Interfaces-Callbacks" data-reactid="2930">Callbacks</h3><div id="Interfaces-asCallback" data-reactid="2931"><b data-reactid="2932">asCallback</b><!-- react-text: 2933 --> — <!-- /react-text --><code data-reactid="2934">.asCallback(callback)</code><p data-reactid="2935">If you'd prefer a callback interface over promises, the asCallback function accepts a standard node style callback for executing the query chain. Note that as with the then method, subsequent calls to the same query chain will return the same result.</p><pre data-reactid="2936"><code class="hljs js" data-reactid="2937">knex.select(<span class="hljs-string">'name'</span>).from(<span class="hljs-string">'users'</span>)
.where(<span class="hljs-string">'id'</span>, <span class="hljs-string">'>'</span>, <span class="hljs-number">20</span>)
.andWhere(<span class="hljs-string">'id'</span>, <span class="hljs-string">'<'</span>, <span class="hljs-number">200</span>)
.limit(<span class="hljs-number">10</span>)
.offset(x)
.asCallback(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">err, rows</span>) </span>{
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">return</span> <span class="hljs-built_in">console</span>.error(err);
knex.select(<span class="hljs-string">'id'</span>).from(<span class="hljs-string">'nicknames'</span>)
.whereIn(<span class="hljs-string">'nickname'</span>, _.pluck(rows, <span class="hljs-string">'name'</span>))
.asCallback(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">err, rows</span>) </span>{
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">return</span> <span class="hljs-built_in">console</span>.error(err);
<span class="hljs-built_in">console</span>.log(rows);
});
});</code></pre></div><h3 id="Interfaces-Streams" data-reactid="2938">Streams</h3><p data-reactid="2939">Streams are a powerful way of piping data through as it comes in, rather than all at once. You can read more about streams <a href="https://github.com/substack/stream-handbook">here at substack's stream handbook</a>. See the following for example uses of stream & pipe. If you wish to use streams with PostgreSQL, you must also install the <a href="https://github.com/brianc/node-pg-query-stream">pg-query-stream</a> module. On an HTTP server, make sure to <a href="https://github.com/tgriesser/knex/wiki/Manually-Closing-Streams">manually close your streams</a> if a request is aborted.</p><div id="Interfaces-stream" data-reactid="2940"><b data-reactid="2941">stream</b><!-- react-text: 2942 --> — <!-- /react-text --><code data-reactid="2943">.stream([options], [callback])</code><p data-reactid="2944">If called with a callback, the callback is passed the stream and a promise is returned. Otherwise, the readable stream is returned.</p><pre data-reactid="2945"><code class="hljs js" data-reactid="2946"><span class="hljs-comment">// Retrieve the stream:</span>
<span class="hljs-keyword">var</span> stream = knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).stream();
stream.pipe(writableStream);
<span class="hljs-comment">// With options:</span>
<span class="hljs-keyword">var</span> stream = knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).stream({<span class="hljs-attr">highWaterMark</span>: <span class="hljs-number">5</span>});
stream.pipe(writableStream);
<span class="hljs-comment">// Use as a promise:</span>
<span class="hljs-keyword">var</span> stream = knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>)
.where(knex.raw(<span class="hljs-string">'id = ?'</span>, [<span class="hljs-number">1</span>]))
.stream(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">stream</span>) </span>{
stream.pipe(writableStream);
})
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{ <span class="hljs-comment">// ... })</span>
.catch(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">e</span>) </span>{ <span class="hljs-built_in">console</span>.error(e); });</code></pre></div><div id="Interfaces-pipe" data-reactid="2947"><b data-reactid="2948">pipe</b><!-- react-text: 2949 --> — <!-- /react-text --><code data-reactid="2950">.pipe(writableStream)</code><p data-reactid="2951">Pipe a stream for the current query to a writableStream.</p><pre data-reactid="2952"><code class="hljs js" data-reactid="2953"><span class="hljs-keyword">var</span> stream = knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).pipe(writableStream);</code></pre></div><h3 id="Interfaces-Events" data-reactid="2954">Events</h3><div id="Interfaces-query" data-reactid="2955"><b data-reactid="2956">query</b><p data-reactid="2957">A query event is fired just before a query takes place, providing data about the query, including the connection's <code>__knexUid</code> / <code>__knexTxId</code> properties and any other information about the query as described in toSQL. Useful for logging all queries throughout your application.</p><pre data-reactid="2958"><code class="hljs js" data-reactid="2959">knex.select(<span class="hljs-string">'*'</span>)
.from(<span class="hljs-string">'users'</span>)
.on(<span class="hljs-string">'query'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">data</span>) </span>{
app.log(data);
})
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-comment">// ...</span>
});</code></pre></div><div id="Interfaces-query-error" data-reactid="2960"><b data-reactid="2961">query-error</b><p data-reactid="2962">A query-error event is fired when an error occurs when running a query, providing the error object and data about the query, including the connection's <code>__knexUid</code> / <code>__knexTxId</code> properties and any other information about the query as described in toSQL. Useful for logging all query errors throughout your application.</p><pre data-reactid="2963"><code class="hljs js" data-reactid="2964">knex.select([<span class="hljs-string">'NonExistentColumn'</span>])
.from(<span class="hljs-string">'users'</span>)
.on(<span class="hljs-string">'query-error'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">error, obj</span>) </span>{
app.log(error);
})
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{ <span class="hljs-comment">// ... })</span>
.catch(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">error</span>) </span>{
<span class="hljs-comment">// Same error object as the query-error event provides.</span>
});</code></pre></div><div id="Interfaces-query-response" data-reactid="2965"><b data-reactid="2966">query-response</b><p data-reactid="2967">A query-response event is fired when a successful query has been run, providing the response of the query and data about the query, including the connection's <code>__knexUid</code> / <code>__knexTxId</code> properties and any other information about the query as described in toSQL, and finally the query builder used for the query.</p><pre data-reactid="2968"><code class="hljs js" data-reactid="2969">knex.select(<span class="hljs-string">'*'</span>)
.from(<span class="hljs-string">'users'</span>)
.on(<span class="hljs-string">'query-response'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">response, obj, builder</span>) </span>{
<span class="hljs-comment">// ...</span>
})
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">response</span>) </span>{
<span class="hljs-comment">// Same response as the emitted event</span>
})
.catch(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">error</span>) </span>{ });</code></pre></div><div id="Interfaces-start" data-reactid="2970"><b data-reactid="2971">start</b><p data-reactid="2972">A <code>start</code> event is fired right before a query-builder is compiled. Note: While this event can be used to alter a builders state prior to compilation it is not to be recommended. Future goals include ways of doing this in a different manner such as hooks.</p><pre data-reactid="2973"><code class="hljs js" data-reactid="2974">knex.select(<span class="hljs-string">'*'</span>)
.from(<span class="hljs-string">'users'</span>)
.on(<span class="hljs-string">'start'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">builder</span>) </span>{
builder
.where(<span class="hljs-string">'IsPrivate'</span>, <span class="hljs-number">0</span>)
})
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">Rows</span>) </span>{
<span class="hljs-comment">//Only contains Rows where IsPrivate = 0</span>
})
.catch(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">error</span>) </span>{ });</code></pre></div><h3 id="Interfaces-Other" data-reactid="2975">Other</h3><div id="Interfaces-toString" data-reactid="2976"><b data-reactid="2977">toString</b><!-- react-text: 2978 --> — <!-- /react-text --><code data-reactid="2979">.toString()</code><p data-reactid="2980">Returns an array of query strings filled out with the correct values based on bindings, etc. Useful for debugging, but should not be used to create queries for running them against DB.</p><pre data-reactid="2981"><code class="hljs js" data-reactid="2982"><span class="hljs-keyword">var</span> toStringQuery = knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>).where(<span class="hljs-string">'id'</span>, <span class="hljs-number">1</span>).toString();
<span class="hljs-comment">// Outputs: console.log(toStringQuery); </span>
<span class="hljs-comment">// select * from "users" where "id" = 1</span></code></pre></div><div id="Interfaces-toSQL" data-reactid="2983"><b data-reactid="2984">toSQL</b><!-- react-text: 2985 --> — <!-- /react-text --><code data-reactid="2986">.toSQL() and toSQL().toNative()</code><p data-reactid="2987">Returns an array of query strings filled out with the correct values based on bindings, etc. Useful for debugging and building queries for running them manually with DB driver. <code>.toSQL().toNative()</code> outputs object with sql string and bindings in a dialects format in the same way that knex internally sends them to underlying DB driver.</p><pre data-reactid="2988"><code class="hljs js" data-reactid="2989">knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>)
.where(knex.raw(<span class="hljs-string">'id = ?'</span>, [<span class="hljs-number">1</span>]))
.toSQL()
<span class="hljs-comment">// Outputs:</span>
<span class="hljs-comment">// {</span>
<span class="hljs-comment">// bindings: [1],</span>
<span class="hljs-comment">// method: 'select',</span>
<span class="hljs-comment">// sql: 'select * from "users" where id = ?',</span>
<span class="hljs-comment">// options: undefined,</span>
<span class="hljs-comment">// toNative: function () {}</span>
<span class="hljs-comment">// }</span>
knex.select(<span class="hljs-string">'*'</span>).from(<span class="hljs-string">'users'</span>)
.where(knex.raw(<span class="hljs-string">'id = ?'</span>, [<span class="hljs-number">1</span>]))
.toSQL().toNative()
<span class="hljs-comment">// Outputs for postgresql dialect:</span>
<span class="hljs-comment">// {</span>
<span class="hljs-comment">// bindings: [1],</span>
<span class="hljs-comment">// sql: 'select * from "users" where id = $1',</span>
<span class="hljs-comment">// }</span></code></pre></div></div><div id="Migrations" data-reactid="2990"><h2 id="Migrations" data-reactid="2991">Migrations</h2><p data-reactid="2992">Migrations allow for you to define sets of schema changes so upgrading a database is a breeze.</p><h3 id="Migrations-CLI" data-reactid="2993">Migration CLI</h3><p data-reactid="2994">The migration CLI is bundled with the knex install, and is driven by the <a href="https://github.com/tkellen/node-liftoff">node-liftoff</a> module. To install globally, run:</p><pre data-reactid="2995"><code data-reactid="2996">$ npm install knex -g</code></pre><div data-reactid="2997"><p data-reactid="2998">The migration CLI accepts the following general command-line options. You can view help text and additional options for each command using <code>--help</code>. E.g. <code>knex migrate:latestVersion --help</code>.</p></div><ul data-reactid="2999"><li data-reactid="3000"><code>--debug</code>: Run with debugging</li><li data-reactid="3001"><code>--knexfile [path]</code>: Specify the knexfile path</li><li data-reactid="3002"><code>--knexpath [path]</code>: Specify the path to the knex instance</li><li data-reactid="3003"><code>--cwd [path]</code>: Specify the working directory</li><li data-reactid="3004"><code>--client [name]</code>: Set the DB client without a knexfile</li><li data-reactid="3005"><code>--connection [address]</code>: Set the DB connection without a knexfile</li><li data-reactid="3006"><code>--migrations-table-name</code>: Set the migration table name without a knexfile</li><li data-reactid="3007"><code>--migrations-directory</code>: Set the migrations directory without a knexfile</li><li data-reactid="3008"><code>--env</code>: environment, default: process.env.NODE_ENV || development</li><li data-reactid="3009"><code>--help</code>: Display help text for a particular command and exit.</li></ul><p data-reactid="3010">Migrations use a <strong>knexfile</strong>, which specify various configuration settings for the module. To create a new knexfile, run the following:</p><pre data-reactid="3011"><code data-reactid="3012">$ knex init
# or for .ts
$ knex init -x ts</code></pre><p data-reactid="3013">will create a sample knexfile.js - the file which contains our various database configurations. Once you have a knexfile.js, you can use the migration tool to create migration files to the specified directory (default migrations). Creating new migration files can be achieved by running:</p><pre data-reactid="3014"><code data-reactid="3015">$ knex migrate:make migration_name
# or for .ts
$ knex migrate:make migration_name -x ts</code></pre><ul data-reactid="3016"><li data-reactid="3017">you can also create your migration using a specific stub file, this serves as a migration template to speed up development for common migration operations</li><li data-reactid="3018">if the --stub option is not passed, the CLI will use either the knex default stub for the chosen extension, or the config.stub file</li></ul><pre data-reactid="3019"><code data-reactid="3020">$ knex migrate:make --stub </path/to/stub/file>
# or
$ knex migrate:make --stub <name></code></pre><ul data-reactid="3021"><li data-reactid="3022">if a stub path is provided, it must be relative to the knexfile.[js, ts, etc] location</li><li data-reactid="3023">if a <name> is used, the stub is selected by its file name. The CLI will look for this file in the config.migrations.directory folder. If the config.migrations.directory is not defined, this operation will fail</li></ul><p data-reactid="3024">Once you have finished writing the migrations, you can update the database matching your <code>NODE_ENV</code> by running:</p><pre data-reactid="3025"><code data-reactid="3026">$ knex migrate:latest</code></pre><p data-reactid="3027">You can also pass the <code>--env</code> flag or set <code>NODE_ENV</code> to select an alternative environment:</p><pre data-reactid="3028"><code data-reactid="3029">$ knex migrate:latest --env production
# or
$ NODE_ENV=production knex migrate:latest</code></pre><p data-reactid="3030">To rollback the last batch of migrations:</p><pre data-reactid="3031"><code data-reactid="3032">$ knex migrate:rollback</code></pre><p data-reactid="3033">To rollback all the completed migrations:</p><pre data-reactid="3034"><code data-reactid="3035">$ knex migrate:rollback --all</code></pre><p data-reactid="3036">To run the next migration that has not yet been run</p><pre data-reactid="3037"><code data-reactid="3038">$ knex migrate:up</code></pre><p data-reactid="3039">To run the specified migration that has not yet been run</p><pre data-reactid="3040"><code data-reactid="3041">$ knex migrate:up 001_migration_name.js</code></pre><p data-reactid="3042">To undo the last migration that was run</p><pre data-reactid="3043"><code data-reactid="3044">$ knex migrate:down</code></pre><p data-reactid="3045">To undo the specified migration that was run</p><pre data-reactid="3046"><code data-reactid="3047">$ knex migrate:down 001_migration_name.js</code></pre><p data-reactid="3048">To list both completed and pending migrations:</p><pre data-reactid="3049"><code data-reactid="3050">$ knex migrate:list</code></pre><h2 id="Seeds" data-reactid="3051">Seed files</h2><p data-reactid="3052">Seed files allow you to populate your database with test or seed data independent of your migration files.</p><h3 id="Seeds-CLI" data-reactid="3053">Seed CLI</h3><p data-reactid="3054">To create a seed file, run:</p><pre data-reactid="3055"><code data-reactid="3056">$ knex seed:make seed_name</code></pre><p data-reactid="3057">Seed files are created in the directory specified in your knexfile.js for the current environment. A sample seed configuration looks like:</p><pre data-reactid="3058"><code data-reactid="3059">development: {
client: ...,
connection: { ... },
seeds: {
directory: './seeds/dev'
}
}</code></pre><div data-reactid="3060"><p data-reactid="3061">If no <code>seeds.directory</code> is defined, files are created in <code>./seeds</code>. Note that the seed directory needs to be a relative path. Absolute paths are not supported (nor is it good practice).</p><p data-reactid="3062">To run seed files, execute:</p></div><pre data-reactid="3063"><code data-reactid="3064">$ knex seed:run</code></pre><p data-reactid="3065">Seed files are executed in alphabetical order. Unlike migrations, <em>every</em> seed file will be executed when you run the command. You should design your seed files to reset tables as needed before inserting data.</p><p data-reactid="3066">To run a specific seed file, execute:</p><pre data-reactid="3067"><code data-reactid="3068">$ knex seed:run --specific=seed-filename.js</code></pre><h3 id="knexfile" data-reactid="3069">knexfile.js</h3><p data-reactid="3070">A knexfile.js or knexfile.coffee generally contains all of the configuration for your database. It can optionally provide different configuration for different environments. You may pass a <code>--knexfile</code> option to any of the command line statements to specify an alternate path to your knexfile.</p><h4 data-reactid="3071">Basic configuration:</h4><pre data-reactid="3072"><code class="hljs js" data-reactid="3073"><span class="hljs-built_in">module</span>.exports = {
<span class="hljs-attr">client</span>: <span class="hljs-string">'pg'</span>,
<span class="hljs-attr">connection</span>: process.env.DATABASE_URL || { <span class="hljs-attr">user</span>: <span class="hljs-string">'me'</span>, <span class="hljs-attr">database</span>: <span class="hljs-string">'my_app'</span> }
};</code></pre><h4 data-reactid="3074">Environment configuration:</h4><pre data-reactid="3075"><code class="hljs js" data-reactid="3076"><span class="hljs-built_in">module</span>.exports = {
<span class="hljs-attr">development</span>: {
<span class="hljs-attr">client</span>: <span class="hljs-string">'pg'</span>,
<span class="hljs-attr">connection</span>: { <span class="hljs-attr">user</span>: <span class="hljs-string">'me'</span>, <span class="hljs-attr">database</span>: <span class="hljs-string">'my_app'</span> }
},
<span class="hljs-attr">production</span>: { <span class="hljs-attr">client</span>: <span class="hljs-string">'pg'</span>, <span class="hljs-attr">connection</span>: process.env.DATABASE_URL }
};</code></pre><h4 data-reactid="3077">Custom migration:</h4><p data-reactid="3078">You may provide a custom migration stub to be used in place of the default option.</p><pre data-reactid="3079"><code class="hljs js" data-reactid="3080"><span class="hljs-built_in">module</span>.exports = {
<span class="hljs-attr">client</span>: <span class="hljs-string">'pg'</span>,
<span class="hljs-attr">migrations</span>: {
<span class="hljs-attr">stub</span>: <span class="hljs-string">'migration.stub'</span>
}
};</code></pre><h4 data-reactid="3081">Generated migration extension:</h4><p data-reactid="3082">You can control extension of generated migrations.</p><pre data-reactid="3083"><code class="hljs js" data-reactid="3084"><span class="hljs-built_in">module</span>.exports = {
<span class="hljs-attr">client</span>: <span class="hljs-string">'pg'</span>,
<span class="hljs-attr">migrations</span>: {
<span class="hljs-attr">extension</span>: <span class="hljs-string">'ts'</span>
}
};</code></pre><h3 id="Migrations-API" data-reactid="3085">Migration API</h3><div data-reactid="3086"><p data-reactid="3087"><code>knex.migrate</code> is the class utilized by the knex migrations cli.</p><p data-reactid="3088">Each method takes an optional <code>config</code> object, which may specify the following properties:</p></div><ul data-reactid="3089"><li data-reactid="3090"><code>directory</code>: a relative path to the directory containing the migration files. Can be an array of paths (default <code>./migrations</code>)</li><li data-reactid="3091"><code>extension</code>: the file extension used for the generated migration files (default <code>js</code>)</li><li data-reactid="3092"><code>tableName</code>: the table name used for storing the migration state (default <code>knex_migrations</code>)</li><li data-reactid="3093"><code>schemaName</code>: the schema name used for storing the table with migration state (optional parameter, only works on DBs that support multiple schemas in a single DB, such as PostgreSQL)</li><li data-reactid="3094"><code>disableTransactions</code>: don't run migrations inside transactions (default <code>false</code>)</li><li data-reactid="3095"><code>disableMigrationsListValidation</code>: do not validate that all the already executed migrations are still present in migration directories (default <code>false</code>)</li><li data-reactid="3096"><code>sortDirsSeparately</code>: if true and multiple directories are specified, all migrations from a single directory will be executed before executing migrations in the next folder (default <code>false</code>)</li><li data-reactid="3097"><code>loadExtensions</code>: array of file extensions which knex will treat as migrations. For example, if you have typescript transpiled into javascript in the same folder, you want to execute only javascript migrations. In this case, set <code>loadExtensions</code> to <code>['.js']</code> (Notice the dot!) (default <code>['.co', '.coffee', '.eg', '.iced', '.js', '.litcoffee', '.ls', '.ts']</code>)</li><li data-reactid="3098"><code>migrationSource</code>: specify a custom migration source, see <a href="#custom-migration-sources">Custom Migration Source</a> for more info (default filesystem)</li></ul><h4 id="Migrations-API-transactions" data-reactid="3099">Transactions in migrations</h4><p data-reactid="3100">By default, each migration is run inside a transaction. Whenever needed, one can disable transactions for all migrations via the common migration config option <code>config.disableTransactions</code> or per-migration, via exposing a boolean property <code>config.transaction</code> from a migration file:</p><pre data-reactid="3101"><code class="hljs js" data-reactid="3102">exports.up = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">knex</span>) </span>{
<span class="hljs-keyword">return</span> knex.schema
.createTable(<span class="hljs-string">'users'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">table</span>) </span>{
table.increments(<span class="hljs-string">'id'</span>);
table.string(<span class="hljs-string">'first_name'</span>, <span class="hljs-number">255</span>).notNullable();
table.string(<span class="hljs-string">'last_name'</span>, <span class="hljs-number">255</span>).notNullable();
})
.createTable(<span class="hljs-string">'products'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">table</span>) </span>{
table.increments(<span class="hljs-string">'id'</span>);
table.decimal(<span class="hljs-string">'price'</span>).notNullable();
table.string(<span class="hljs-string">'name'</span>, <span class="hljs-number">1000</span>).notNullable();
});
};
exports.down = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">knex</span>) </span>{
<span class="hljs-keyword">return</span> knex.schema
.dropTable(<span class="hljs-string">"products"</span>)
.dropTable(<span class="hljs-string">"users"</span>);
};
exports.config = { <span class="hljs-attr">transaction</span>: <span class="hljs-literal">false</span> };</code></pre><p data-reactid="3103">The same config property can be used for enabling transaction per-migration in case the common configuration has <code>disableTransactions: true</code>.</p><div id="Migrations-make" data-reactid="3104"><b data-reactid="3105">make</b><!-- react-text: 3106 --> — <!-- /react-text --><code data-reactid="3107">knex.migrate.make(name, [config])</code><p data-reactid="3108">Creates a new migration, with the name of the migration being added.</p></div><div id="Migrations-latest" data-reactid="3109"><b data-reactid="3110">latest</b><!-- react-text: 3111 --> — <!-- /react-text --><code data-reactid="3112">knex.migrate.latest([config])</code><p data-reactid="3113">Runs all migrations that have not yet been run.</p></div><p data-reactid="3114">If you need to run something only after all migrations have finished their execution, you can do something like this:</p><pre data-reactid="3115"><code class="hljs js" data-reactid="3116">knex.migrate.latest()
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">return</span> knex.seed.run();
})
.then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-comment">// migrations are finished</span>
});</code></pre><div id="Migrations-rollback" data-reactid="3117"><b data-reactid="3118">rollback</b><!-- react-text: 3119 --> — <!-- /react-text --><code data-reactid="3120">knex.migrate.rollback([config], [all])</code><p data-reactid="3121">Rolls back the latest migration group. If the <code>all</code> parameter is truthy, all applied migrations will be rolled back instead of just the last batch. The default value for this parameter is <code>false</code>.</p></div><div id="Migrations-up" data-reactid="3122"><b data-reactid="3123">up</b><!-- react-text: 3124 --> — <!-- /react-text --><code data-reactid="3125">knex.migrate.up([config])</code><p data-reactid="3126">Runs the specified (by <code>config.name</code> parameter) or the next chronological migration that has not yet be run.</p></div><div id="Migrations-down" data-reactid="3127"><b data-reactid="3128">down</b><!-- react-text: 3129 --> — <!-- /react-text --><code data-reactid="3130">knex.migrate.down([config])</code><p data-reactid="3131">Will undo the specified (by <code>config.name</code> parameter) or the last migration that was run.</p></div><div id="Migrations-currentVersion" data-reactid="3132"><b data-reactid="3133">currentVersion</b><!-- react-text: 3134 --> — <!-- /react-text --><code data-reactid="3135">knex.migrate.currentVersion([config])</code><p data-reactid="3136">Retrieves and returns the current migration version, as a promise. If there aren't any migrations run yet, returns "none" as the value for the currentVersion.</p></div><div id="Migrations-list" data-reactid="3137"><b data-reactid="3138">list</b><!-- react-text: 3139 --> — <!-- /react-text --><code data-reactid="3140">knex.migrate.list([config])</code><p data-reactid="3141">Will return list of completed and pending migrations</p></div><h3 id="Notes-about-locks" data-reactid="3142">Notes about locks</h3><p data-reactid="3143">A lock system is there to prevent multiple processes from running the same migration batch in the same time. When a batch of migrations is about to be run, the migration system first tries to get a lock using a <code>SELECT ... FOR UPDATE</code> statement (preventing race conditions from happening). If it can get a lock, the migration batch will run. If it can't, it will wait until the lock is released.</p><p data-reactid="3144">Please note that if your process unfortunately crashes, the lock will have to be <em>manually</em> removed in order to let migrations run again. The locks are saved in a table called "<code>tableName</code>_lock"; it has a column called <code>is_locked</code> that you need to set to <code>0</code> in order to release the lock. The <code>index</code> column in the lock table exists for compatibility with some database clusters that require a primary key, but is otherwise unused.</p><h3 id="custom-migration-sources" data-reactid="3145">Custom migration sources</h3><p data-reactid="3146">Knex supports custom migration sources, allowing you full control of where your migrations come from. This can be useful for custom folder structures, when bundling with webpack/browserify and other scenarios.</p><pre data-reactid="3147"><code class="hljs js" data-reactid="3148"><span class="hljs-comment">// Create a custom migration source class</span>
<span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">MyMigrationSource</span> </span>{
<span class="hljs-comment">// Must return a Promise containing a list of migrations. </span>
<span class="hljs-comment">// Migrations can be whatever you want, they will be passed as</span>
<span class="hljs-comment">// arguments to getMigrationName and getMigration</span>
getMigrations() {
<span class="hljs-comment">// In this example we are just returning migration names</span>
<span class="hljs-keyword">return</span> <span class="hljs-built_in">Promise</span>.resolve([<span class="hljs-string">'migration1'</span>])
}
getMigrationName(migration) {
<span class="hljs-keyword">return</span> migration;
}
getMigration(migration) {
<span class="hljs-keyword">switch</span>(migration) {
<span class="hljs-keyword">case</span> <span class="hljs-string">'migration1'</span>:
<span class="hljs-keyword">return</span> {
up(knex) { <span class="hljs-comment">/* ... * / }
down(knex) { /* ... * / }
}
}
},
}
// pass an instance of your migration source as knex config
knex.migrate.latest({ migrationSource: new MyMigrationSource() })</span></code></pre><h4 data-reactid="3149">Webpack migration source example</h4><p data-reactid="3150">An example of how to create a migration source where migrations are included in a webpack bundle.</p><pre data-reactid="3151"><code class="hljs js" data-reactid="3152"><span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">WebpackMigrationSource</span> </span>{
<span class="hljs-keyword">constructor</span>(migrationContext) {
<span class="hljs-keyword">this</span>.migrationContext = migrationContext;
}
getMigrations() {
<span class="hljs-keyword">return</span> <span class="hljs-built_in">Promise</span>.resolve(<span class="hljs-keyword">this</span>.migrationContext.keys().sort())
}
getMigrationName(migration) {
<span class="hljs-keyword">return</span> migration
}
getMigration(migration) {
<span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>.migrationContext(migration)
}
}