Documentation Source Text

Check-in [a6ea023899]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Rename the "sqlite.html" page to "cli.html". Keep an "sqlite.html" page that redirects to "cli.html".
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: a6ea023899ca8c95feb03a858b029c33f863fac8
User & Date: drh 2014-04-22 00:32:41
Context
2014-04-25
20:47
Fix more typos in the foreignkey.html document. check-in: 25bc66990e user: drh tags: version-3.8.4.3
2014-04-22
01:06
Update the version number to 3.8.5. Add a change log. check-in: aabef1a296 user: drh tags: trunk
00:32
Rename the "sqlite.html" page to "cli.html". Keep an "sqlite.html" page that redirects to "cli.html". check-in: a6ea023899 user: drh tags: trunk
2014-04-21
18:20
Update the command-line shell documentation with a discussion of CSV import and export. check-in: 070bfddab9 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Show Whitespace Changes Patch

Changes to pages/c_interface.in.

1100
1101
1102
1103
1104
1105
1106
1107
1108
1109

<h3>6.0 Usage Examples</h3>

<p>For examples of how the SQLite C/C++ interface can be used,
refer to the source code for the <b>sqlite</b> program in the
file <b>src/shell.c</b> of the source tree.
Additional information about sqlite is available at
<a href="sqlite.html">sqlite.html</a>.
See also the sources to the Tcl interface for SQLite in
the source file <b>src/tclsqlite.c</b>.</p>







|


1100
1101
1102
1103
1104
1105
1106
1107
1108
1109

<h3>6.0 Usage Examples</h3>

<p>For examples of how the SQLite C/C++ interface can be used,
refer to the source code for the <b>sqlite</b> program in the
file <b>src/shell.c</b> of the source tree.
Additional information about sqlite is available at
<a href="cli.html">cli.html</a>.
See also the sources to the Tcl interface for SQLite in
the source file <b>src/tclsqlite.c</b>.</p>

Name change from pages/sqlite.in to pages/cli.in.

1
2

3
4
5
6
7
8
9
..
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
..
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
..
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
...
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
...
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
...
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
...
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
...
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
...
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
...
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
...
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
...
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
...
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
...
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
...
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
...
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
...
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
...
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
...
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
<title>Command Line Shell For SQLite</title>
<tcl>hd_keywords {CLI} {Command Line Interface} {command-line shell}</tcl>


<h1 align=center>
Command Line Shell For SQLite
</h1>

<p>The SQLite project provides a simple command-line utility named
<b>sqlite3</b> (or <b>sqlite3.exe</b> on windows)
................................................................................
message then prompt you to enter SQL.  Type in SQL statements (terminated
by a semicolon), press "Enter" and the SQL will be executed.</p>

<p>For example, to create a new SQLite database named "ex1" 
with a single table named "tbl1", you might do this:</p>

<tcl>
proc Code {body} {
  hd_puts {<blockquote><pre>}
  regsub -all {&} [string trim $body] {\&amp;} body
  regsub -all {>} $body {\&gt;} body
  regsub -all {<} $body {\&lt;} body
  regsub -all {\(\(\(} $body {<b>} body
  regsub -all {\)\)\)} $body {</b>} body
  regsub -all {\[\[\[} $body {<i>} body
................................................................................
  regsub -all {\]\]\]} $body {</i>} body
  #regsub -all { } $body {\&nbsp;} body
  #regsub -all \n $body <br>\n body
  hd_puts $body
  hd_puts {</pre></blockquote>}
}

Code {
$ (((sqlite3 ex1)))
SQLite version 3.8.4 2014-02-11 16:24:34
Enter ".help" for usage hints.
sqlite> (((create table tbl1(one varchar(10), two smallint);)))
sqlite> (((insert into tbl1 values('hello!',10);)))
sqlite> (((insert into tbl1 values('goodbye', 20);)))
sqlite> (((select * from tbl1;)))
................................................................................
The sqlite3 program looks for a semicolon to know when your SQL command is
complete.  If you omit the semicolon, sqlite3 will give you a
continuation prompt and wait for you to enter more text to be
added to the current SQL command.  This feature allows you to
enter SQL commands that span multiple lines.  For example:</p>


<tcl>Code {
sqlite> (((CREATE TABLE tbl2 ()))
   ...> (((  f1 varchar(30) primary key,)))
   ...> (((  f2 text,)))
   ...> (((  f3 real)))
   ...> ((();)))
sqlite> 
}</tcl>
................................................................................
<p>Windows users can double-click on the <b>sqlite3.exe</b> icon to cause
the command-line shell to pop-up a terminal window running SQLite.  Note,
however, that by default this SQLite session is using an in-memory database,
not a file on disk, and so all changes will be lost when the session exits.
To use a persistent disk file as the database, enter the ".open" command
immediately after the terminal window starts up:

<tcl>Code {
SQLite version 3.8.4 2014-02-11 16:24:34
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.
sqlite> (((.open ex1.db)))
sqlite> 
}</tcl>
................................................................................
use a full pathname to ensure that the file is in the directory that you
think it is in.  Use forward-slashes as the directory separator character.
In other words use "c:/work/ex1.db", not "c:\work\ex1.db".</p>

<p>Alternatively, you can create a new database using the default in-memory
storage, then save that database into a disk file using the ".save" command:

<tcl>Code {
SQLite version 3.8.4 2014-02-11 16:24:34
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.
sqlite> [[[... many SQL commands omitted ...]]]
sqlite> (((.save ex1.db)))
sqlite> 
................................................................................
</p>

<p>
For a listing of the available dot commands, you can enter ".help"
at any time.  For example:
</p>

<tcl>Code {
sqlite> (((.help)))
.backup ?DB? FILE      Backup DB (default "main") to FILE
.bail ON|OFF           Stop after hitting an error.  Default OFF
.clone NEWDB           Clone data into NEWDB from the existing database
.databases             List names and files of attached databases
.dump ?TABLE? ...      Dump the database in an SQL text format
                         If TABLE specified, only dump tables matching
................................................................................
<p>The default output mode is "list".  In
list mode, each record of a query result is written on one line of
output and each column within that record is separated by a specific
separator string.  The default separator is a pipe symbol ("|").
List mode is especially useful when you are going to send the output
of a query to another program (such as AWK) for additional processing.</p>

<tcl>Code {
sqlite> (((.mode list)))
sqlite> (((select * from tbl1;)))
hello|10
goodbye|20
sqlite>
}</tcl>

<p>You can use the ".separator" dot command to change the separator
for list mode.  For example, to change the separator to a comma and
a space, you could do this:</p>

<tcl>Code {
sqlite> (((.separator ", ")))
sqlite> (((select * from tbl1;)))
hello, 10
goodbye, 20
sqlite>
}</tcl>

<p>In "line" mode, each column in a row of the database
is shown on a line by itself.  Each line consists of the column
name, an equal sign and the column data.  Successive records are
separated by a blank line.  Here is an example of line mode
output:</p>

<tcl>Code {
sqlite> (((.mode line)))
sqlite> (((select * from tbl1;)))
one = hello
two = 10

one = goodbye
two = 20
sqlite>
}</tcl>

<p>In column mode, each record is shown on a separate line with the
data aligned in columns.  For example:</p>

<tcl>Code {
sqlite> (((.mode column)))
sqlite> (((select * from tbl1;)))
one         two       
----------  ----------
hello       10        
goodbye     20        
sqlite>
}</tcl>

<p>By default, each column is at least 10 characters wide. 
Data that is too wide to fit in a column is truncated.  You can
adjust the column widths using the ".width" command.  Like this:</p>

<tcl>Code {
sqlite> (((.width 12 6)))
sqlite> (((select * from tbl1;)))
one           two   
------------  ------
hello         10    
goodbye       20    
sqlite>
................................................................................
right-justified columns.</p>

<p>The column labels that appear on the first two lines of output
can be turned on and off using the ".header" dot command.  In the
examples above, the column labels are on.  To turn them off you
could do this:</p>

<tcl>Code {
sqlite> (((.header off)))
sqlite> (((select * from tbl1;)))
hello         10    
goodbye       20    
sqlite>
}</tcl>

................................................................................
is formatted to look like SQL INSERT statements.  You can use insert
mode to generate text that can later be used to input data into a 
different database.</p>

<p>When specifying insert mode, you have to give an extra argument
which is the name of the table to be inserted into.  For example:</p>

<tcl>Code {
sqlite> (((.mode insert new_table)))
sqlite> (((select * from tbl1;)))
INSERT INTO 'new_table' VALUES('hello',10);
INSERT INTO 'new_table' VALUES('goodbye',20);
sqlite>
}</tcl>

................................................................................
for looking at the output of an EXPLAIN command.  The EXPLAIN command
is an SQLite-specific SQL extension that is useful for debugging.  If any
regular SQL is prefaced by EXPLAIN, then the SQL command is parsed and
analyzed but is not executed.  Instead, the sequence of virtual machine
instructions that would have been used to execute the SQL command are
returned like a query result.  For example:</p>

<tcl>Code {
sqlite> (((.explain)))
sqlite> (((explain delete from tbl1 where two<20;)))
addr  opcode         p1    p2    p3    p4             p5  comment      
----  -------------  ----  ----  ----  -------------  --  -------------
0     Trace          0     0     0                    00               
1     Goto           0     18    0                    00               
2     Null           0     1     0                    00  r[1]=NULL    
................................................................................

<p>By default, sqlite3 sends query results to standard output.  You
can change this using the ".output" command.  Just put the name of
an output file as an argument to the .output command and all subsequent
query results will be written to that file.  Use ".output stdout" to
begin writing to standard output again.  For example:</p>

<tcl>Code {
sqlite> (((.mode list)))
sqlite> (((.separator |)))
sqlite> (((.output test_file_1.txt)))
sqlite> (((select * from tbl1;)))
sqlite> (((.exit)))
$ (((cat test_file_1.txt)))
hello|10
................................................................................
("|") then the remaining characters are treated as a command and the
output is sent to that command.  This makes it easy to pipe the results
of a query into some other process.  For example, a Mac, the 
"open -f" command opens a text editor to display the content that
it reads from standard input.  So to see the results of a query
in a text editor, one could type:</p>

<tcl>Code {
sqlite3> (((.output '|open -f')))
sqlite3> (((SELECT * FROM bigTable;)))
sqlite3> (((.output stdout)))
}</tcl>

<h3>Querying the database schema</h3>

................................................................................
nothing that these commands do that cannot be done by some other
means.  These commands are provided purely as a shortcut.</p>

<p>For example, to see a list of the tables in the database, you
can enter ".tables".</p>


<tcl>Code {
sqlite> (((.tables)))
tbl1
tbl2
sqlite>
}</tcl>


................................................................................
indices are desired.  Last, but not least, is the ".schema" command.
With no arguments, the ".schema" command shows the original CREATE TABLE
and CREATE INDEX statements that were used to build the current database.
If you give the name of a table to ".schema", it shows the original
CREATE statement used to make that table and all if its indices.
We have:</p>

<tcl>Code {
sqlite> (((.schema)))
create table tbl1(one varchar(10), two smallint)
CREATE TABLE tbl2 (
  f1 varchar(30) primary key,
  f2 text,
  f3 real
)
................................................................................
ORDER BY substr(type,2,1), name
</pre></blockquote>

<p>The "%s" in the query is replace by your argument.  This allows you
to view the schema for some subset of the database.</p>


<tcl>Code {
sqlite> (((.schema %abc%)))
}</tcl>


<p>
Along these same lines,
the ".table" command also accepts a pattern as its first argument.
................................................................................
the current connection.  There will always be at least 2.  The first
one is "main", the original database opened.  The second is "temp",
the database used for temporary tables. There may be additional 
databases listed for databases attached using the ATTACH statement.
The first output column is the name the database is attached with, 
and the second column is the filename of the external file.</p>

<tcl>Code {
sqlite> (((.databases)))
}</tcl>


<tcl>hd_fragment csv {CSV import}</tcl>
<h3>CSV Import</h3>

................................................................................
name of the disk file from which CSV data is to be read and the name of the
SQLite table into which the CSV data is to be inserted.

<p>Note that it is important to set the "mode" to "csv" before running the
 ".import" command.  This is necessary to prevent the command-line shell
from trying to interpret the input file text as some other format.

<tcl>Code {
sqlite> (((.mode csv)))
sqlite> (((.import C:/work/somedata.csv tab1)))
}</tcl>

<p>There are two cases to consider:  (1) Table "tab1" does not previously
exist and (2) table "tab1" does already exist.

................................................................................
<tcl>hd_fragment csvout {CSV export}</tcl>
<h3>CSV Export</h3>

<p>To export an SQLite table (or part of a table) as CSV, simply set
the "mode" to "csv" and then run a query to extract the desired rows
of the table.

<tcl>Code {
sqlite> (((.header on)))
sqlite> (((.output c:/work/dataout.csv)))
sqlite> (((.mode csv)))
sqlite> (((SELECT * FROM tab1;)))
sqlite> (((.output stdout)))
}</tcl>

................................................................................
<p>Use the ".dump" command to convert the entire contents of a
database into a single ASCII text file.  This file can be converted
back into a database by piping it back into <b>sqlite3</b>.</p>

<p>A good way to make an archival copy of a database is this:</p>


<tcl>Code {
$ (((echo '.dump' | sqlite3 ex1 | gzip -c >ex1.dump.gz)))
}</tcl>


<p>This generates a file named <b>ex1.dump.gz</b> that contains everything
you need to reconstruct the database at a later time, or on another
machine.  To reconstruct the database, just type:</p>


<tcl>Code {
$ (((zcat ex1.dump.gz | sqlite3 ex2)))
}</tcl>


<p>The text format is pure SQL so you
can also use the .dump command to export an SQLite database
into other popular SQL database engines.  Like this:</p>


<tcl>Code {
$ (((createdb ex2)))
$ (((sqlite3 ex1 .dump | psql ex2)))
}</tcl>


<h3>Other Dot Commands</h3>

................................................................................
database name.  When the sqlite3 program is launched with two
arguments, the second argument is passed to the SQLite library
for processing, the query results are printed on standard output
in list mode, and the program exits.  This mechanism is designed
to make sqlite3 easy to use in conjunction with programs like
"awk".  For example:</p>

<tcl>Code {
$ (((sqlite3 ex1 'select * from tbl1' |)))
> ((( awk '{printf "<tr><td>%s<td>%s\n",$1,$2 }')))
<tr><td>hello<td>10
<tr><td>goodbye<td>20
$
}</tcl>


|
>







 







|







 







|







 







|







 







|







 







|







 







|







 







|











|













|













|













|







 







|







 







|







 







|







 







|







 







|







 







|







 







|







 







|







 







|







 







|







 







|







 







|









|









|







 







|







1
2
3
4
5
6
7
8
9
10
..
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
..
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
..
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
...
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
...
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
...
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
...
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
...
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
...
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
...
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
...
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
...
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
...
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
...
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
...
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
...
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
...
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
...
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
...
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
<title>Command Line Shell For SQLite</title>
<tcl>hd_keywords {CLI} {Command Line Interface} {command-line shell} \
     {command-line interface} </tcl>

<h1 align=center>
Command Line Shell For SQLite
</h1>

<p>The SQLite project provides a simple command-line utility named
<b>sqlite3</b> (or <b>sqlite3.exe</b> on windows)
................................................................................
message then prompt you to enter SQL.  Type in SQL statements (terminated
by a semicolon), press "Enter" and the SQL will be executed.</p>

<p>For example, to create a new SQLite database named "ex1" 
with a single table named "tbl1", you might do this:</p>

<tcl>
proc DisplayCode {body} {
  hd_puts {<blockquote><pre>}
  regsub -all {&} [string trim $body] {\&amp;} body
  regsub -all {>} $body {\&gt;} body
  regsub -all {<} $body {\&lt;} body
  regsub -all {\(\(\(} $body {<b>} body
  regsub -all {\)\)\)} $body {</b>} body
  regsub -all {\[\[\[} $body {<i>} body
................................................................................
  regsub -all {\]\]\]} $body {</i>} body
  #regsub -all { } $body {\&nbsp;} body
  #regsub -all \n $body <br>\n body
  hd_puts $body
  hd_puts {</pre></blockquote>}
}

DisplayCode {
$ (((sqlite3 ex1)))
SQLite version 3.8.4 2014-02-11 16:24:34
Enter ".help" for usage hints.
sqlite> (((create table tbl1(one varchar(10), two smallint);)))
sqlite> (((insert into tbl1 values('hello!',10);)))
sqlite> (((insert into tbl1 values('goodbye', 20);)))
sqlite> (((select * from tbl1;)))
................................................................................
The sqlite3 program looks for a semicolon to know when your SQL command is
complete.  If you omit the semicolon, sqlite3 will give you a
continuation prompt and wait for you to enter more text to be
added to the current SQL command.  This feature allows you to
enter SQL commands that span multiple lines.  For example:</p>


<tcl>DisplayCode {
sqlite> (((CREATE TABLE tbl2 ()))
   ...> (((  f1 varchar(30) primary key,)))
   ...> (((  f2 text,)))
   ...> (((  f3 real)))
   ...> ((();)))
sqlite> 
}</tcl>
................................................................................
<p>Windows users can double-click on the <b>sqlite3.exe</b> icon to cause
the command-line shell to pop-up a terminal window running SQLite.  Note,
however, that by default this SQLite session is using an in-memory database,
not a file on disk, and so all changes will be lost when the session exits.
To use a persistent disk file as the database, enter the ".open" command
immediately after the terminal window starts up:

<tcl>DisplayCode {
SQLite version 3.8.4 2014-02-11 16:24:34
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.
sqlite> (((.open ex1.db)))
sqlite> 
}</tcl>
................................................................................
use a full pathname to ensure that the file is in the directory that you
think it is in.  Use forward-slashes as the directory separator character.
In other words use "c:/work/ex1.db", not "c:\work\ex1.db".</p>

<p>Alternatively, you can create a new database using the default in-memory
storage, then save that database into a disk file using the ".save" command:

<tcl>DisplayCode {
SQLite version 3.8.4 2014-02-11 16:24:34
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.
sqlite> [[[... many SQL commands omitted ...]]]
sqlite> (((.save ex1.db)))
sqlite> 
................................................................................
</p>

<p>
For a listing of the available dot commands, you can enter ".help"
at any time.  For example:
</p>

<tcl>DisplayCode {
sqlite> (((.help)))
.backup ?DB? FILE      Backup DB (default "main") to FILE
.bail ON|OFF           Stop after hitting an error.  Default OFF
.clone NEWDB           Clone data into NEWDB from the existing database
.databases             List names and files of attached databases
.dump ?TABLE? ...      Dump the database in an SQL text format
                         If TABLE specified, only dump tables matching
................................................................................
<p>The default output mode is "list".  In
list mode, each record of a query result is written on one line of
output and each column within that record is separated by a specific
separator string.  The default separator is a pipe symbol ("|").
List mode is especially useful when you are going to send the output
of a query to another program (such as AWK) for additional processing.</p>

<tcl>DisplayCode {
sqlite> (((.mode list)))
sqlite> (((select * from tbl1;)))
hello|10
goodbye|20
sqlite>
}</tcl>

<p>You can use the ".separator" dot command to change the separator
for list mode.  For example, to change the separator to a comma and
a space, you could do this:</p>

<tcl>DisplayCode {
sqlite> (((.separator ", ")))
sqlite> (((select * from tbl1;)))
hello, 10
goodbye, 20
sqlite>
}</tcl>

<p>In "line" mode, each column in a row of the database
is shown on a line by itself.  Each line consists of the column
name, an equal sign and the column data.  Successive records are
separated by a blank line.  Here is an example of line mode
output:</p>

<tcl>DisplayCode {
sqlite> (((.mode line)))
sqlite> (((select * from tbl1;)))
one = hello
two = 10

one = goodbye
two = 20
sqlite>
}</tcl>

<p>In column mode, each record is shown on a separate line with the
data aligned in columns.  For example:</p>

<tcl>DisplayCode {
sqlite> (((.mode column)))
sqlite> (((select * from tbl1;)))
one         two       
----------  ----------
hello       10        
goodbye     20        
sqlite>
}</tcl>

<p>By default, each column is at least 10 characters wide. 
Data that is too wide to fit in a column is truncated.  You can
adjust the column widths using the ".width" command.  Like this:</p>

<tcl>DisplayCode {
sqlite> (((.width 12 6)))
sqlite> (((select * from tbl1;)))
one           two   
------------  ------
hello         10    
goodbye       20    
sqlite>
................................................................................
right-justified columns.</p>

<p>The column labels that appear on the first two lines of output
can be turned on and off using the ".header" dot command.  In the
examples above, the column labels are on.  To turn them off you
could do this:</p>

<tcl>DisplayCode {
sqlite> (((.header off)))
sqlite> (((select * from tbl1;)))
hello         10    
goodbye       20    
sqlite>
}</tcl>

................................................................................
is formatted to look like SQL INSERT statements.  You can use insert
mode to generate text that can later be used to input data into a 
different database.</p>

<p>When specifying insert mode, you have to give an extra argument
which is the name of the table to be inserted into.  For example:</p>

<tcl>DisplayCode {
sqlite> (((.mode insert new_table)))
sqlite> (((select * from tbl1;)))
INSERT INTO 'new_table' VALUES('hello',10);
INSERT INTO 'new_table' VALUES('goodbye',20);
sqlite>
}</tcl>

................................................................................
for looking at the output of an EXPLAIN command.  The EXPLAIN command
is an SQLite-specific SQL extension that is useful for debugging.  If any
regular SQL is prefaced by EXPLAIN, then the SQL command is parsed and
analyzed but is not executed.  Instead, the sequence of virtual machine
instructions that would have been used to execute the SQL command are
returned like a query result.  For example:</p>

<tcl>DisplayCode {
sqlite> (((.explain)))
sqlite> (((explain delete from tbl1 where two<20;)))
addr  opcode         p1    p2    p3    p4             p5  comment      
----  -------------  ----  ----  ----  -------------  --  -------------
0     Trace          0     0     0                    00               
1     Goto           0     18    0                    00               
2     Null           0     1     0                    00  r[1]=NULL    
................................................................................

<p>By default, sqlite3 sends query results to standard output.  You
can change this using the ".output" command.  Just put the name of
an output file as an argument to the .output command and all subsequent
query results will be written to that file.  Use ".output stdout" to
begin writing to standard output again.  For example:</p>

<tcl>DisplayCode {
sqlite> (((.mode list)))
sqlite> (((.separator |)))
sqlite> (((.output test_file_1.txt)))
sqlite> (((select * from tbl1;)))
sqlite> (((.exit)))
$ (((cat test_file_1.txt)))
hello|10
................................................................................
("|") then the remaining characters are treated as a command and the
output is sent to that command.  This makes it easy to pipe the results
of a query into some other process.  For example, a Mac, the 
"open -f" command opens a text editor to display the content that
it reads from standard input.  So to see the results of a query
in a text editor, one could type:</p>

<tcl>DisplayCode {
sqlite3> (((.output '|open -f')))
sqlite3> (((SELECT * FROM bigTable;)))
sqlite3> (((.output stdout)))
}</tcl>

<h3>Querying the database schema</h3>

................................................................................
nothing that these commands do that cannot be done by some other
means.  These commands are provided purely as a shortcut.</p>

<p>For example, to see a list of the tables in the database, you
can enter ".tables".</p>


<tcl>DisplayCode {
sqlite> (((.tables)))
tbl1
tbl2
sqlite>
}</tcl>


................................................................................
indices are desired.  Last, but not least, is the ".schema" command.
With no arguments, the ".schema" command shows the original CREATE TABLE
and CREATE INDEX statements that were used to build the current database.
If you give the name of a table to ".schema", it shows the original
CREATE statement used to make that table and all if its indices.
We have:</p>

<tcl>DisplayCode {
sqlite> (((.schema)))
create table tbl1(one varchar(10), two smallint)
CREATE TABLE tbl2 (
  f1 varchar(30) primary key,
  f2 text,
  f3 real
)
................................................................................
ORDER BY substr(type,2,1), name
</pre></blockquote>

<p>The "%s" in the query is replace by your argument.  This allows you
to view the schema for some subset of the database.</p>


<tcl>DisplayCode {
sqlite> (((.schema %abc%)))
}</tcl>


<p>
Along these same lines,
the ".table" command also accepts a pattern as its first argument.
................................................................................
the current connection.  There will always be at least 2.  The first
one is "main", the original database opened.  The second is "temp",
the database used for temporary tables. There may be additional 
databases listed for databases attached using the ATTACH statement.
The first output column is the name the database is attached with, 
and the second column is the filename of the external file.</p>

<tcl>DisplayCode {
sqlite> (((.databases)))
}</tcl>


<tcl>hd_fragment csv {CSV import}</tcl>
<h3>CSV Import</h3>

................................................................................
name of the disk file from which CSV data is to be read and the name of the
SQLite table into which the CSV data is to be inserted.

<p>Note that it is important to set the "mode" to "csv" before running the
 ".import" command.  This is necessary to prevent the command-line shell
from trying to interpret the input file text as some other format.

<tcl>DisplayCode {
sqlite> (((.mode csv)))
sqlite> (((.import C:/work/somedata.csv tab1)))
}</tcl>

<p>There are two cases to consider:  (1) Table "tab1" does not previously
exist and (2) table "tab1" does already exist.

................................................................................
<tcl>hd_fragment csvout {CSV export}</tcl>
<h3>CSV Export</h3>

<p>To export an SQLite table (or part of a table) as CSV, simply set
the "mode" to "csv" and then run a query to extract the desired rows
of the table.

<tcl>DisplayCode {
sqlite> (((.header on)))
sqlite> (((.output c:/work/dataout.csv)))
sqlite> (((.mode csv)))
sqlite> (((SELECT * FROM tab1;)))
sqlite> (((.output stdout)))
}</tcl>

................................................................................
<p>Use the ".dump" command to convert the entire contents of a
database into a single ASCII text file.  This file can be converted
back into a database by piping it back into <b>sqlite3</b>.</p>

<p>A good way to make an archival copy of a database is this:</p>


<tcl>DisplayCode {
$ (((echo '.dump' | sqlite3 ex1 | gzip -c >ex1.dump.gz)))
}</tcl>


<p>This generates a file named <b>ex1.dump.gz</b> that contains everything
you need to reconstruct the database at a later time, or on another
machine.  To reconstruct the database, just type:</p>


<tcl>DisplayCode {
$ (((zcat ex1.dump.gz | sqlite3 ex2)))
}</tcl>


<p>The text format is pure SQL so you
can also use the .dump command to export an SQLite database
into other popular SQL database engines.  Like this:</p>


<tcl>DisplayCode {
$ (((createdb ex2)))
$ (((sqlite3 ex1 .dump | psql ex2)))
}</tcl>


<h3>Other Dot Commands</h3>

................................................................................
database name.  When the sqlite3 program is launched with two
arguments, the second argument is passed to the SQLite library
for processing, the query results are printed on standard output
in list mode, and the program exits.  This mechanism is designed
to make sqlite3 easy to use in conjunction with programs like
"awk".  For example:</p>

<tcl>DisplayCode {
$ (((sqlite3 ex1 'select * from tbl1' |)))
> ((( awk '{printf "<tr><td>%s<td>%s\n",$1,$2 }')))
<tr><td>hello<td>10
<tr><td>goodbye<td>20
$
}</tcl>

Changes to pages/download.in.

119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
  This is a snapshot (as of VERSION) of the current SQLite code under 
  development, packaged and ready to build using the
  <a href="http://www.tcl.tk/doc/tea/">Tcl Extension Architecture (TEA)</a>.
  Use this snapshot for testing only.  This is not a release.
}
Product {snapshot/sqlite-shell-win32-x86-DATE.zip} {
  This is a snapshot (as of VERSION) build of the 
  <a href="sqlite.html">sqlite3.exe command-line shell</a>
  shell program for 32-bit windows.
}
Product {snapshot/sqlite-shell-win64-x64-DATE.zip} {
  This is a snapshot (as of VERSION) build of the 
  <a href="sqlite.html">sqlite3.exe command-line shell</a>
  shell program for 64-bit windows.
}

Product {snapshot/sqlite-winrt81-DATE.vsix} {
  This is a snapshot (as of VERSION) for
  a complete VSIX package with an extension SDK and all other components
  needed to use SQLite for WinRT 8.1 application development with Visual Studio







|




|







119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
  This is a snapshot (as of VERSION) of the current SQLite code under 
  development, packaged and ready to build using the
  <a href="http://www.tcl.tk/doc/tea/">Tcl Extension Architecture (TEA)</a>.
  Use this snapshot for testing only.  This is not a release.
}
Product {snapshot/sqlite-shell-win32-x86-DATE.zip} {
  This is a snapshot (as of VERSION) build of the 
  [CLI | sqlite3.exe command-line shell]
  shell program for 32-bit windows.
}
Product {snapshot/sqlite-shell-win64-x64-DATE.zip} {
  This is a snapshot (as of VERSION) build of the 
  [CLI  | sqlite3.exe command-line shell]
  shell program for 64-bit windows.
}

Product {snapshot/sqlite-winrt81-DATE.vsix} {
  This is a snapshot (as of VERSION) for
  a complete VSIX package with an extension SDK and all other components
  needed to use SQLite for WinRT 8.1 application development with Visual Studio

Changes to pages/features.in.

29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
<li><a href="selfcontained.html">Self-contained</a>:
    no external dependencies.</li>
<li>Cross-platform: Unix (Linux, Mac OS-X, Android, iOS) and Windows
    (Win32, WinCE, WinRT)
    are supported out of the box.  Easy to port to other systems.
<li>Sources are in the <a href="copyright.html">public domain</a>.
    Use for any purpose.</li>
<li>Comes with a standalone <a href="sqlite.html">command-line interface</a>
    (CLI) client that can be used to administer SQLite databases.</li>
</ul>
</p>

<h2>Suggested Uses For SQLite:</h2>

<p><ul>







|







29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
<li><a href="selfcontained.html">Self-contained</a>:
    no external dependencies.</li>
<li>Cross-platform: Unix (Linux, Mac OS-X, Android, iOS) and Windows
    (Win32, WinCE, WinRT)
    are supported out of the box.  Easy to port to other systems.
<li>Sources are in the <a href="copyright.html">public domain</a>.
    Use for any purpose.</li>
<li>Comes with a standalone [command-line interface]
    (CLI) client that can be used to administer SQLite databases.</li>
</ul>
</p>

<h2>Suggested Uses For SQLite:</h2>

<p><ul>

Changes to pages/quickstart.in.

16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

<ul>
<li><p>At a shell or DOS prompt, enter: "<b>sqlite3 test.db</b>".  This will
create a new database named "test.db".  (You can use a different name if
you like.)</p></li>
<li><p>Enter SQL commands at the prompt to create and populate the
new database.</p></li>
<li><p>Additional documentation is available <a href="sqlite.html">here</a></li>
</ul>

<h2>Write Programs That Use SQLite</h2>

<ul>
<li><p>Below is a simple 
[http://www.tcl.tk | TCL program] that demonstrates how to use







|







16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

<ul>
<li><p>At a shell or DOS prompt, enter: "<b>sqlite3 test.db</b>".  This will
create a new database named "test.db".  (You can use a different name if
you like.)</p></li>
<li><p>Enter SQL commands at the prompt to create and populate the
new database.</p></li>
<li><p>Additional documentation is available [CLI | here]</li>
</ul>

<h2>Write Programs That Use SQLite</h2>

<ul>
<li><p>Below is a simple 
[http://www.tcl.tk | TCL program] that demonstrates how to use

Added rawpages/sqlite.html.





















>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
<html>
<head>
<meta http-equiv="refresh" content="0; ./cli.html">
</head>
<!-- The "cli.html" page used to be called "sqlite.html".  This is a replace
     "sqlite.html" page that automatically redirects to the new "cli.html" -->
<body>
Redirect to <a href="./cli.html">./cli.html</a>
</body>
</html>