Documentation Source Text

Check-in [d2d3de4f3f]
Login

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

Overview
Comment:Improvements to CLI documentation. Expand the Examples section of the loadable extension document.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: d2d3de4f3ff6d3b107d031e385baf4ee71eb7316
User & Date: drh 2017-03-15 15:59:53
Context
2017-03-15
20:32
Further refinement to the loadable extension documentation. check-in: cecf106465 user: drh tags: trunk
15:59
Improvements to CLI documentation. Expand the Examples section of the loadable extension document. check-in: d2d3de4f3f user: drh tags: trunk
14:08
Fix typos and improve the wording of the .selftest documentation. check-in: 6aaee6c270 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/cli.in.

194
195
196
197
198
199
200

201
202
203

204
205
206
207
208
209
210
...
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
...
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
...
326
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
367
...
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
...
499
500
501
502
503
504
505
506
507
508
509

510
511
512
513
514
515
516
517
518
519
520
521
...
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
.quit                  Exit this program
.read FILENAME         Execute SQL in FILENAME
.restore ?DB? FILE     Restore content of DB (default "main") from FILE
.save FILE             Write in-memory database into FILE
.scanstats on|off      Turn sqlite3_stmt_scanstatus() metrics on or off
.schema ?PATTERN?      Show the CREATE statements matching PATTERN
                          Add --indent for pretty-printing

.separator COL ?ROW?   Change the column separator and optionally the row
                         separator for both the output mode and .import
.session CMD ...       Create or control sessions

.shell CMD ARGS...     Run CMD ARGS... in a system shell
.show                  Show the current values for various settings
.stats ?on|off?        Show stats or turn stats on or off
.system CMD ARGS...    Run CMD ARGS... in a system shell
.tables ?TABLE?        List names of tables
                         If TABLE specified, only list tables matching
                         LIKE pattern TABLE.
................................................................................
}</tclscript>

<tcl>hd_fragment dotrules</tcl>
<h1>Rules for "dot-commands"</h1>

<p>Ordinary SQL statements are free-form, and can be
spread across multiple lines, and can have whitespace and
comments anywhere.  But dot-commands are
more restrictive:

<ul>
<li>A dot-command must begin with the "." at the left margin
    with no preceding whitespace.
<li>The dot-command must be entirely contained on a single input line.
<li>A dot-command cannot occur in the middle of an ordinary SQL
    statement.  In other words, a dot-command cannot occur at a
    continuation prompt.
<li>Dot-commands do not recognize comments.
</ul>

<p>And, of course, it is important to remember that the dot-commands
are interpreted by the sqlite3.exe command-line program, not by
SQLite itself.  So none of the dot-commands will work as an argument
to SQLite interfaces like [sqlite3_prepare()] or [sqlite3_exec()].

<tcl>hd_fragment dotmode</tcl>
<h1>Changing Output Formats</h1>

................................................................................
<p>The sqlite3 program is able to show the results of a query
in eight different formats: "csv", "column", "html", "insert",
"line", "list", "quote", "tabs", and "tcl".
You can use the ".mode" dot command to switch between these output
formats.</p>

<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>

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

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

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

<p>The next ".mode" command will reset the ".separator" back to its default.
So you will need repeat the ".separator" command whenever you change
modes if you want to continue using a non-standard separator.

<p>In "quote" mode, the output is formatted as SQL literals.  Strings are
enclosed in single-quotes within internal single-quotes escaped by doubling.
Blobs are displayed in hexadecimal blob literal notation (Ex: x'abcd').
Numbers are displayed as ASCII text and NULL values are shown as "NULL".
All columns are separated from each other by a comma (or whatever alternative
character is selected using ".separator").

<tclscript>DisplayCode {
sqlite> (((.mode quote)))
................................................................................
hello       10        
goodbye     20        
sqlite>
}</tclscript>

<p>By default, each column is between 1 and 10 characters wide, depending
on the column header name and the width of the first column of data.
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>

<tclscript>DisplayCode {
sqlite> (((.width 12 6)))
sqlite> (((select * from tbl1;)))
one           two   
------------  ------
hello         10    
................................................................................
<p>If you specify a column a width of 0, then the column
width is automatically adjusted to be the maximum of three
numbers: 10, the width of the header, and the width of the
first row of data.  This makes the column width self-adjusting.
The default width setting for every column is this 
auto-adjusting 0 value.</p>

<p>You can specify a negative column width to get
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>

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

<p>Another useful output mode is "insert".  In insert mode, the output
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>

<tclscript>DisplayCode {
................................................................................

<tclscript>DisplayCode {
SELECT name FROM sqlite_master 
WHERE type IN ('table','view') AND name NOT LIKE 'sqlite_%'
ORDER BY 1
} </tclscript>

<p>The ".indices" command works in a similar way to list all of
the indices for a particular table.  The ".indices" command takes
a single argument which is the name of the table for which the
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>

<tclscript>DisplayCode {
sqlite> (((.schema)))
create table tbl1(one varchar(10), two smallint)
CREATE TABLE tbl2 (
  f1 varchar(30) primary key,
  f2 text,
................................................................................
list mode, then entering the following query:</p>

<tclscript>DisplayCode {
SELECT sql FROM sqlite_master
ORDER BY tbl_name, type DESC, name
} </tclscript>

<p>Or, if you give an argument to ".schema" because you only
want the schema for a single table, the query looks like this:</p>

<tclscript>DisplayCode {
SELECT sql FROM sqlite_master
WHERE type!='meta' AND sql NOT NULL AND name NOT LIKE 'sqlite_%'
ORDER BY substr(type,2,1), name
} </tclscript>

<p>
You can supply an argument to the .schema command.  If you do, the
query looks like this:
</p>

<tclscript>DisplayCode {
SELECT sql FROM sqlite_master
WHERE tbl_name LIKE '%s'
  AND type!='meta' AND sql NOT NULL AND name NOT LIKE 'sqlite_%'
ORDER BY substr(type,2,1), name
} </tclscript>

<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>


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


<p>
Along these same lines,
the ".table" command also accepts a pattern as its first argument.
If you give an argument to the .table command, a "%" is both
appended and prepended and a LIKE clause is added to the query.
This allows you to list only those tables that match a particular
pattern.</p>

<p>The ".databases" command shows a list of all databases open in
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>







>



>







 







|












|







 







|
|












|







 







|







 







|
|







 







<
|







 







|







 







|
|
|
<
>
|
|
<
<
<







 







<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<







194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
...
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
...
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
...
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
...
354
355
356
357
358
359
360

361
362
363
364
365
366
367
368
...
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
...
500
501
502
503
504
505
506
507
508
509

510
511
512



513
514
515
516
517
518
519
...
533
534
535
536
537
538
539






































540
541
542
543
544
545
546
.quit                  Exit this program
.read FILENAME         Execute SQL in FILENAME
.restore ?DB? FILE     Restore content of DB (default "main") from FILE
.save FILE             Write in-memory database into FILE
.scanstats on|off      Turn sqlite3_stmt_scanstatus() metrics on or off
.schema ?PATTERN?      Show the CREATE statements matching PATTERN
                          Add --indent for pretty-printing
.selftest ?--init?     Run tests defined in the SELFTEST table
.separator COL ?ROW?   Change the column separator and optionally the row
                         separator for both the output mode and .import
.session CMD ...       Create or control sessions
.sha3sum ?OPTIONS...?  Compute a SHA3 hash of database content
.shell CMD ARGS...     Run CMD ARGS... in a system shell
.show                  Show the current values for various settings
.stats ?on|off?        Show stats or turn stats on or off
.system CMD ARGS...    Run CMD ARGS... in a system shell
.tables ?TABLE?        List names of tables
                         If TABLE specified, only list tables matching
                         LIKE pattern TABLE.
................................................................................
}</tclscript>

<tcl>hd_fragment dotrules</tcl>
<h1>Rules for "dot-commands"</h1>

<p>Ordinary SQL statements are free-form, and can be
spread across multiple lines, and can have whitespace and
comments anywhere.  Dot-commands are
more restrictive:

<ul>
<li>A dot-command must begin with the "." at the left margin
    with no preceding whitespace.
<li>The dot-command must be entirely contained on a single input line.
<li>A dot-command cannot occur in the middle of an ordinary SQL
    statement.  In other words, a dot-command cannot occur at a
    continuation prompt.
<li>Dot-commands do not recognize comments.
</ul>

<p>The dot-commands
are interpreted by the sqlite3.exe command-line program, not by
SQLite itself.  So none of the dot-commands will work as an argument
to SQLite interfaces like [sqlite3_prepare()] or [sqlite3_exec()].

<tcl>hd_fragment dotmode</tcl>
<h1>Changing Output Formats</h1>

................................................................................
<p>The sqlite3 program is able to show the results of a query
in eight different formats: "csv", "column", "html", "insert",
"line", "list", "quote", "tabs", and "tcl".
You can use the ".mode" dot command to switch between these output
formats.</p>

<p>The default output mode is "list".  In
list mode, each row of a query result is written on one line of
output and each column within that row 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>

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

<p>Use the ".separator" dot command to change the separator.
For example, to change the separator to a comma and
a space, you could do this:</p>

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

<p>The next ".mode" command will reset the ".separator" back to its default.
So you will need repeat the ".separator" command whenever you change
modes if you want to continue using a non-standard separator.

<p>In "quote" mode, the output is formatted as SQL literals.  Strings are
enclosed in single-quotes and internal single-quotes are escaped by doubling.
Blobs are displayed in hexadecimal blob literal notation (Ex: x'abcd').
Numbers are displayed as ASCII text and NULL values are shown as "NULL".
All columns are separated from each other by a comma (or whatever alternative
character is selected using ".separator").

<tclscript>DisplayCode {
sqlite> (((.mode quote)))
................................................................................
hello       10        
goodbye     20        
sqlite>
}</tclscript>

<p>By default, each column is between 1 and 10 characters wide, depending
on the column header name and the width of the first column of data.
Data that is too wide to fit in a column is truncated.  Use the
".width" dot-command to adjust column widths, like this:</p>

<tclscript>DisplayCode {
sqlite> (((.width 12 6)))
sqlite> (((select * from tbl1;)))
one           two   
------------  ------
hello         10    
................................................................................
<p>If you specify a column a width of 0, then the column
width is automatically adjusted to be the maximum of three
numbers: 10, the width of the header, and the width of the
first row of data.  This makes the column width self-adjusting.
The default width setting for every column is this 
auto-adjusting 0 value.</p>


<p>Use a negative column width for 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>

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

<p>Another useful output mode is "insert".  In insert mode, the output
is formatted to look like SQL INSERT statements.  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>

<tclscript>DisplayCode {
................................................................................

<tclscript>DisplayCode {
SELECT name FROM sqlite_master 
WHERE type IN ('table','view') AND name NOT LIKE 'sqlite_%'
ORDER BY 1
} </tclscript>

<p>The ".indexes" command works in a similar way to list all of
the indexes. If the ".indexes" command is given an argument which is
the name of a table, then it shows just indexes on that table.


<p>The ".schema" command shows the complete schema for the database,
or for a single table if an optional tablename argument is provided:




<tclscript>DisplayCode {
sqlite> (((.schema)))
create table tbl1(one varchar(10), two smallint)
CREATE TABLE tbl2 (
  f1 varchar(30) primary key,
  f2 text,
................................................................................
list mode, then entering the following query:</p>

<tclscript>DisplayCode {
SELECT sql FROM sqlite_master
ORDER BY tbl_name, type DESC, name
} </tclscript>







































<p>The ".databases" command shows a list of all databases open in
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>

Changes to pages/loadext.in.

210
211
212
213
214
215
216


217
218
219
220




































221
222
223
224
225
226
227
  **     sqlite3_vfs_register()
  ** to register the new features that your extension adds.
  */
  return rc;
}
</codeblock>



<p>Many examples of complete and working loadable extensions can be seen in the
SQLite source tree in the
<a href="http://www.sqlite.org/src/tree?name=ext/misc&ci=trunk">ext/misc</a>
subdirectory.</p>





































<tcl>hd_fragment persist {persistent loadable extensions}</tcl>
<h1>Persistent Loadable Extensions</h1>

<p>The default behavior for a loadable extension is that it is unloaded
from process memory when the database connection that originally invoked
[sqlite3_load_extension()] closes.  (In other words, the xDlUnload method 







>
>
|
|
<
<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







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
  **     sqlite3_vfs_register()
  ** to register the new features that your extension adds.
  */
  return rc;
}
</codeblock>

<h2>Example Extensions</h2>

<p>Many examples of complete and working loadable extensions can be 
seen in the SQLite source tree in the


[https://www.sqlite.org/src/file/ext/misc|ext/misc] subdirectory.
Each file in that directory is a separate extension.  Documentation
is provided by a header comment on the file.
Here are brief notes on a few of the extensions in 
the [https://www.sqlite.org/src/file/ext/misc|ext/misc] subdirectory:

<ul>
<li><p>
[https://www.sqlite.org/src/file/ext/misc/carray.c|carray.c] &mdash;
Implementation of the [carray table-valued function].
<li><p>
[https://www.sqlite.org/src/file/ext/misc/compress.c|compress.c] &mdash;
Implementation of [application-defined SQL functions] compress() and
uncompress() that do zLib compression of text or blob content.
<li><p>
[https://www.sqlite.org/src/file/ext/misc/json1.c|json1.c] &mdash;
Implementation of [JSON SQL functions] and [table-valued functions].
This is a larger and more complex extension.
<li><p>
[https://www.sqlite.org/src/file/ext/misc/memvfs.c|memvfs.c] &mdash;
Implementation of a new [VFS] that stores all content in-memory.
<li><p>
[https://www.sqlite.org/src/file/ext/misc/rot13.c|rot13.c] &mdash;
Implementation of a [https://en.wikipedia.org/wiki/ROT13|rot13()] 
SQL function.  This is a very simple example of an extension function
and is useful as a template for creating new extensions.
<li><p>
[https://www.sqlite.org/src/file/ext/misc/series.c|series.c] &mdash;
Implementation of the generate_series [virtual table] and
[table-valued function].  This is a relatively simple example of a
virtual table implementation which can serve as a template for writing
new virtual tables.
</ul>




<tcl>hd_fragment persist {persistent loadable extensions}</tcl>
<h1>Persistent Loadable Extensions</h1>

<p>The default behavior for a loadable extension is that it is unloaded
from process memory when the database connection that originally invoked
[sqlite3_load_extension()] closes.  (In other words, the xDlUnload method