Documentation updates. (CVS 1946)

FossilOrigin-Name: 799f5383c0c72a74c7b29f9f40fc949f3248a499
This commit is contained in:
drh 2004-09-08 13:06:21 +00:00
parent fa6bc0000f
commit 916d68efea
5 changed files with 131 additions and 81 deletions

View File

@ -1,5 +1,5 @@
C Wildcards\swith\sthe\ssame\sname\smap\sinto\sthe\ssame\svariable\snumber.\s\sNew\napi\ssqlite3_bind_parameter_index()\sadded\sto\smap\swildcard\snames\sinto\nwildcard\sindex\snumbers.\s\sSupport\sfor\s"?nnn"\swildcards.\s(CVS\s1945)
D 2004-09-07T16:19:53
C Documentation\supdates.\s(CVS\s1946)
D 2004-09-08T13:06:21
F Makefile.in 65a7c43fcaf9a710d62f120b11b6e435eeb4a450
F Makefile.linux-gcc a9e5a0d309fa7c38e7c14d3ecf7690879d3a5457
F README f1de682fbbd94899d50aca13d387d1b3fd3be2dd
@ -210,9 +210,9 @@ F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff
F www/arch.fig d5f9752a4dbf242e9cfffffd3f5762b6c63b3bcf
F www/arch.gif f845a64772062e82d17980a349f95f1f0b4c8054
F www/arch.png 82ef36db1143828a7abc88b1e308a5f55d4336f4
F www/arch.tcl b833057e89aeb43335c0bf84a3d5b7f9d11df6fa
F www/arch.tcl 126611ffd57e0dfac28d71ab04d7a78697ab4b80
F www/arch2.fig ae2432145c26cfa148fa0116589517ad3cd5fc65
F www/arch2.gif 49c6bb36160f03ca2b89eaa5bfb1f560c7d68ee7
F www/arch2.gif 6f2d47c4e0c5842c0d6b5513fd8249393d7c7003
F www/arch2b.fig d22a2c9642d584b89d4088b1e51e2bb0f7c04bed
F www/audit.tcl 90e09d580f79c7efec0c7d6f447b7ec5c2dce5c0
F www/c_interface.tcl 83b39203e1ded4c2dab97f42edf31279a308efcb
@ -233,7 +233,7 @@ F www/faq.tcl 3a1776818d9bd973ab0c3048ec7ad6b1ad091ae5
F www/fileformat.tcl f71a06a0d533c7df408539c64113b4adeaf29764
F www/formatchng.tcl d1dfecedfb25e122ab513a1e0948b15cb4f0be46
F www/index.tcl 618733d540dcf28226cc8eb00816f0baaa03064d
F www/lang.tcl b2ba401104a76e7842469b33a968f5eda9bd462b
F www/lang.tcl 604683def6e987db1703faf580d9b2150905fda1
F www/lockingv3.tcl afcd22f0f063989cff2f4d57bbc38d719b4c6e75
F www/mingw.tcl d96b451568c5d28545fefe0c80bee3431c73f69c
F www/nulls.tcl ede975a29def48838c606d4a0c0185d44f90a789
@ -248,7 +248,7 @@ F www/tclsqlite.tcl 560ecd6a916b320e59f2917317398f3d59b7cc25
F www/vdbe.tcl 59288db1ac5c0616296b26dce071c36cb611dfe9
F www/version3.tcl 092a01f5ef430d2c4acc0ae558d74c4bb89638a0
F www/whentouse.tcl a8335bce47cc2fddb07f19052cb0cb4d9129a8e4
P f323e4f86a08fe6448cbd4ff7cab459e8039d9f1
R b14b673cf74913bc0aa77288120014ba
P 435b3f301fbb6953adc974c7f03589b06e9114c3
R e9ed3557bbf8633eb729c636ad21e3fd
U drh
Z abec07c7d353cf60af4ed426f1ba4bbf
Z d578a3410535617a4415c71c00fd3edf

View File

@ -1 +1 @@
435b3f301fbb6953adc974c7f03589b06e9114c3
799f5383c0c72a74c7b29f9f40fc949f3248a499

View File

@ -1,7 +1,7 @@
#
# Run this Tcl script to generate the sqlite.html file.
#
set rcsid {$Id: arch.tcl,v 1.14 2004/07/17 21:56:10 drh Exp $}
set rcsid {$Id: arch.tcl,v 1.15 2004/09/08 13:06:21 drh Exp $}
source common.tcl
header {Architecture of SQLite}
puts {
@ -24,63 +24,40 @@ and how they interrelate is shown at the right. The text that
follows will provide a quick overview of each of these components.
</p>
<h3>History</h3>
<p>
There are two main C interfaces to the SQLite library:
<b>sqlite_exec()</b> and <b>sqlite_compile()</b>. Prior to
version 2.8.0 (2003-Feb-16) only sqlite_exec() was supported.
For version 2.8.0, the sqlite_exec and sqlite_compile methods
existed as peers. Beginning with version 2.8.13, the sqlite_compile
method is the primary interface, and sqlite_exec is implemented
using sqlite_compile. Externally, this change is an enhancement
that maintains backwards compatibility. But internally,
the plumbing is very different. The diagram at the right shows
the structure of SQLite for version 2.8.13 and following.
</p>
<p>
This document describes the structure for SQLite version 2.X.
SQLite version 3.0.0 introduces many new features and capabilities.
The basic architecture of the library remains the same. However,
some of the details described here are different. For example,
the code was in the file <b>os.c</b> has now been split out into
several file, on for each operating system. And
the prefix on the names of API routines changed from <b>sqlite_</b>
to <b>sqlite3_</b>.
This document describes SQLite version 3.0. Version 2.8 and
earlier are similar but the details differ.
</p>
<h3>Interface</h3>
<p>Much of the public interface to the SQLite library is implemented by
functions found in the <b>main.c</b> source file though some routines are
functions found in the <b>main.c</b>, <b>legacy.c</b>, and
<b>vdbeapi.c</b> source files
though some routines are
scattered about in other files where they can have access to data
structures with file scope. The
<b>sqlite_get_table()</b> routine is implemented in <b>table.c</b>.
<b>sqlite_step()</b> is found in <b>vdbe.c</b>.
<b>sqlite_mprintf()</b> is found in <b>printf.c</b>.
<b>sqlite3_get_table()</b> routine is implemented in <b>table.c</b>.
<b>sqlite3_mprintf()</b> is found in <b>printf.c</b>.
<b>sqlite3_complete()</b> is in <b>tokenize.c</b>.
The Tcl interface is implemented by <b>tclsqlite.c</b>. More
information on the C interface to SQLite is
<a href="c_interface.html">available separately</a>.<p>
<a href="capi3ref.html">available separately</a>.<p>
<p>To avoid name collisions with other software, all external
symbols in the SQLite library begin with the prefix <b>sqlite</b>.
symbols in the SQLite library begin with the prefix <b>sqlite3</b>.
Those symbols that are intended for external use (in other words,
those symbols which form the API for SQLite) begin
with <b>sqlite_</b>.</p>
<h3>SQL Command Processor</h3>
<p>
with <b>sqlite3_</b>.</p>
<h3>Tokenizer</h3>
<p>When a string containing SQL statements is to be executed, the
interface passes that string to the tokenizer. The job of the tokenizer
is to break the original string up into tokens and pass those tokens
one by one to the parser. The tokenizer is hand-coded in C.
All of the code for the tokenizer
is contained in the <b>tokenize.c</b> source file.</p>
one by one to the parser. The tokenizer is hand-coded in C in
the file <b>tokenize.c</b>.
<p>Note that in this design, the tokenizer calls the parser. People
who are familiar with YACC and BISON may be used to doing things the
@ -113,20 +90,30 @@ lemon is found in the "doc" subdirectory of the distribution.
<p>After the parser assembles tokens into complete SQL statements,
it calls the code generator to produce virtual machine code that
will do the work that the SQL statements request. There are many
files in the code generator: <b>build.c</b>, <b>copy.c</b>,
files in the code generator:
<b>attach.c</b>,
<b>auth.c</b>,
<b>build.c</b>,
<b>delete.c</b>,
<b>expr.c</b>, <b>insert.c</b>, <b>pragma.c</b>,
<b>select.c</b>, <b>trigger.c</b>, <b>update.c</b>, <b>vacuum.c</b>
<b>expr.c</b>,
<b>insert.c</b>,
<b>pragma.c</b>,
<b>select.c</b>,
<b>trigger.c</b>,
<b>update.c</b>,
<b>vacuum.c</b>
and <b>where.c</b>.
In these files is where most of the serious magic happens.
<b>expr.c</b> handles code generation for expressions.
<b>where.c</b> handles code generation for WHERE clauses on
SELECT, UPDATE and DELETE statements. The files <b>copy.c</b>,
SELECT, UPDATE and DELETE statements. The files <b>attach.c</b>,
<b>delete.c</b>, <b>insert.c</b>, <b>select.c</b>, <b>trigger.c</b>
<b>update.c</b>, and <b>vacuum.c</b> handle the code generation
for SQL statements with the same names. (Each of these files calls routines
in <b>expr.c</b> and <b>where.c</b> as necessary.) All other
SQL statements are coded out of <b>build.c</b>.</p>
SQL statements are coded out of <b>build.c</b>.
The <b>auth.c</b> file implements the functionality of
<b>sqlite3_set_authorizer()</b>.</p>
<h3>Virtual Machine</h3>
@ -146,14 +133,28 @@ between the virtual machine and the rest of the SQLite library and
<b>vdbeInt.h</b> which defines structure private the virtual machine.
The <b>vdbeaux.c</b> file contains utilities used by the virtual
machine and interface modules used by the rest of the library to
construct VM programs.</p>
construct VM programs. The <b>vdbeapi.c</b> file contains external
interfaces to the virtual machine such as the
<b>sqlite3_bind_...</b> family of functions. Individual values
(strings, integer, floating point numbers, and BLOBs) are stored
in an internal object named "Mem" which is implemented by
<b>vdbemem.c</b>.</p>
<p>
SQLite implements SQL functions using callbacks to C-language routines.
Even the built-in SQL functions are implemented this way. Most of
the built-in SQL functions (ex: <b>coalesce()</b>, <b>count()</b>,
<b>substr()</b>, and so forth) can be found in <b>func.c</b>.
Date and time conversion functions are found in <b>date.c</b>.
</p>
<h3>B-Tree</h3>
<p>An SQLite database is maintained on disk using a B-tree implementation
found in the <b>btree.c</b> source file. A separate B-tree is used for
each table and index in the database. All B-trees are stored in the
same disk file.</p>
same disk file. Details of the file format are recorded in a large
comment at the beginning of <b>btree.c</b>.</p>
<p>The interface to the B-tree subsystem is defined by the header file
<b>btree.h</b>.
@ -161,11 +162,13 @@ same disk file.</p>
<h3>Page Cache</h3>
<p>The B-tree module requests information from the disk in 1024 byte
chunks. The page cache is reponsible for reading, writing, and
<p>The B-tree module requests information from the disk in fixed-size
chunks. The default chunk size is 1024 bytes but can vary between 512
and 65536 bytes.
The page cache is reponsible for reading, writing, and
caching these chunks.
The page cache also provides the rollback and atomic commit abstraction
and takes care of reader/writer locking of the database file. The
and takes care of locking of the database file. The
B-tree driver requests particular pages from the page cache and notifies
the page cache when it wants to modify pages or commit or rollback
changes and the page cache handles all the messy details of making sure
@ -181,12 +184,38 @@ is defined by the header file <b>pager.h</b>.
<p>
In order to provide portability between POSIX and Win32 operating systems,
SQLite uses an abstraction layer to interface with the operating system.
The <b>os.c</b> file contains about 20 routines used for opening and
closing files, deleting files, creating and deleting locks on files,
flushing the disk cache, and so forth. Each of these functions contains
two implementations separated by #ifdefs: one for POSIX and the other
for Win32. The interface to the OS abstraction layer is defined by
the <b>os.h</b> header file.
The interface to the OS abstraction layer is defined in
<b>os.h</b>. Each supported operating system has its own implementation:
<b>os_unix.c</b> for Unix, <b>os_win.c</b> for windows, and so forth.
Each of these operating-specific implements typically has its own
header file: <b>os_unix.h</b>, <b>os_win.h</b>, etc.
</p>
<h3>Utilities</h3>
<p>
Memory allocation and caseless string comparison routines are located
in <b>util.c</b>.
Symbol tables used by the parser are maintained by hash tables found
in <b>hash.c</b>. The <b>utf.c</b> source file contains Unicode
conversion subroutines.
SQLite has its own private implementation of <b>printf()</b> (with
some extensions) in <b>printf.c</b> and its own random number generator
in <b>random.c</b>.
</p>
<h3>Test Code</h3>
<p>
If you count regression test scripts,
more than half the total code base of SQLite is devoted to testing.
There are many <b>assert()</b> statements in the main code files.
In additional, the source files <b>test1.c</b> through <b>test5.c</b>
together with <b>md5.c</b> implement extensions used for testing
purposes only. The <b>os_test.c</b> backend interface is used to
simulate power failures to verify the crash-recovery mechanism in
the pager.
</p>
}
footer $rcsid

Binary file not shown.

Before

Width:  |  Height:  |  Size: 7.0 KiB

After

Width:  |  Height:  |  Size: 6.3 KiB

View File

@ -1,7 +1,7 @@
#
# Run this Tcl script to generate the sqlite.html file.
#
set rcsid {$Id: lang.tcl,v 1.71 2004/07/18 20:52:32 drh Exp $}
set rcsid {$Id: lang.tcl,v 1.72 2004/09/08 13:06:21 drh Exp $}
source common.tcl
header {Query Language Understood by SQLite}
puts {
@ -183,8 +183,7 @@ ROLLBACK [TRANSACTION [<name>]]
puts {
<p>Beginning in version 2.0, SQLite supports transactions with
rollback and atomic commit. See <a href="#attach">ATTACH</a> for
an exception when there are attached databases.</p>
rollback and atomic commit.</p>
<p>The optional transaction name is ignored. SQLite currently
does not allow nested transactions.</p>
@ -261,6 +260,9 @@ puts {
<p>The COPY command is available in SQLite version 2.8 and earlier.
The COPY command has been removed from SQLite version 3.0 due to
complications in trying to support it in a mixed UTF-8/16 environment.
In version 3.0, the <a href="sqlite.html">command-line shell</a>
contains a new command <b>.import</b> that can be used as a substitute
for COPY.
</p>
<p>The COPY command is an extension used to load large amounts of
@ -389,10 +391,10 @@ for use by the engine.</p>
<p>Each column definition is the name of the column followed by the
datatype for that column, then one or more optional column constraints.
SQLite is <a href="datatypes.html">typeless</a>.
The datatype for the column does not restrict what data may be put
in that column.
All information is stored as null-terminated strings.
See <a href="datatype3.html">Datatypes In SQLite Version 3</a> for
additional information.
The UNIQUE constraint causes an index to be created on the specified
columns. This index must contain unique keys.
The DEFAULT constraint
@ -448,8 +450,9 @@ work.</p>
<p>There are no arbitrary limits on the number
of columns or on the number of constraints in a table.
The total amount of data in a single row is limited to about
1 megabytes. (This limit can be increased to 16MB by changing
a single #define in the source code and recompiling.)</p>
1 megabytes in version 2.8. In version 3.0 there is no arbitrary
limit on the amount of data in a row.</p>
<p>The CREATE TABLE AS form defines the table to be
the result set of a query. The names of the table columns are
@ -704,7 +707,8 @@ DROP INDEX [<database-name> .] <index-name>
}
puts {
<p>The DROP INDEX statement removes an index added with the <a href="#createindex">
<p>The DROP INDEX statement removes an index added
with the <a href="#createindex">
CREATE INDEX</a> statement. The index named is completely removed from
the disk. The only way to recover the index is to reenter the
appropriate CREATE INDEX command. Non-temporary indexes on tables in
@ -921,7 +925,7 @@ their result across all rows of the result set.</p>
<p>The functions shown below are available by default. Additional
functions may be written in C and added to the database engine using
the <a href="c_interface.html#cfunc">sqlite_create_function()</a>
the <a href="capi3ref.html#cfunc">sqlite3_create_function()</a>
API.</p>
<table border=0 cellpadding=10>
@ -941,8 +945,8 @@ all arguments are NULL then NULL is returned. There must be at least
<a name="globFunc"></a>
<td valign="top" align="right">glob(<i>X</i>,<i>Y</i>)</td>
<td valign="top">This function is used to implement the
"<b>Y GLOB X</b>" syntax of SQLite. The
<a href="c_interface.html#cfunc">sqlite_create_function()</a>
"<b>X GLOB Y</b>" syntax of SQLite. The
<a href="capi3ref.html#sqlite3_create_function">sqlite3_create_function()</a>
interface can
be used to override this function and thereby change the operation
of the <a href="#glob">GLOB</a> operator.</td>
@ -973,8 +977,8 @@ characters is returned, not the number of bytes.</td>
<a name="likeFunc"></a>
<td valign="top" align="right">like(<i>X</i>,<i>Y</i>)</td>
<td valign="top">This function is used to implement the
"<b>Y LIKE X</b>" syntax of SQL. The
<a href="c_interface.html#cfunc">sqlite_create_function()</a>
"<b>X LIKE Y</b>" syntax of SQL. The
<a href="capi3ref.html#sqlite3_create_function">sqlite_create_function()</a>
interface can
be used to override this function and thereby change the operation
of the <a href="#like">LIKE</a> operator.</td>
@ -1012,6 +1016,17 @@ only a single argument.</td>
otherwise return NULL.</td>
</tr>
<tr>
<td valign="top" align="right">quote(<i>X</i>)</td>
<td valign="top">This routine returns a string which is the value of
its argument suitable for inclusion into another SQL statement.
Strings are surrounded by single-quotes with escapes on interior quotes
as needed. BLOBs are encoded as hexadecimal literals.
The current implementation of VACUUM uses this function. The function
is also useful when writing triggers to implement undo/redo functionality.
</td>
</tr>
<tr>
<td valign="top" align="right">random(*)</td>
<td valign="top">Return a random integer between -2147483648 and
@ -1053,8 +1068,9 @@ then characters indices refer to actual UTF-8 characters, not bytes.</td>
<tr>
<td valign="top" align="right">typeof(<i>X</i>)</td>
<td valign="top">Return the type of the expression <i>X</i>. The only
return values are "numeric" and "text". SQLite's type handling is
explained in <a href="datatypes.html">Datatypes in SQLite</a>.</td>
return values are "null", "integer", "real", "text", and "blob".
SQLite's type handling is
explained in <a href="datatype3.html">Datatypes in SQLite Version 3</a>.</td>
</tr>
<tr>
@ -1069,7 +1085,8 @@ UTF-8 strings.</td>
<p>
The following aggregate functions are available by default. Additional
aggregate functions written in C may be added using the
<a href="c_interface.html#cfunc">sqlite_create_aggregate()</a> API.</p>
<a href="capi3ref.html#sqlite3_create_function">sqlite3_create_function()</a>
API.</p>
<table border=0 cellpadding=10>
<tr>
@ -1270,8 +1287,10 @@ is returned it is as an integer.</p>
<li><p><b>PRAGMA default_cache_size;
<br>PRAGMA default_cache_size = </b><i>Number-of-pages</i><b>;</b></p>
<p>Query or change the maximum number of database disk pages that SQLite
will hold in memory at once. Each page uses 1K on disk and about 1.5K in memory.
This pragma works like the <a href="#pragma_cache_size"><b>cache_size</b></a>
will hold in memory at once. Each page uses 1K on disk and about
1.5K in memory.
This pragma works like the
<a href="#pragma_cache_size"><b>cache_size</b></a>
pragma with the additional
feature that it changes the cache size persistently. With this pragma,
you can set the cache size once and that setting is retained and reused
@ -1308,7 +1327,9 @@ is returned it is as an integer.</p>
<p>This pragma changes the synchronous mode persistently. Once changed,
the mode stays as set even if the database is closed and reopened. The
<a href="#pragma_synchronous"><b>synchronous</b></a> pragma does the same
thing but only applies the setting to the current session.</p></li>
thing but only applies the setting to the current session.
</p></li>
<a name="pragma_default_temp_store"></a>
<li><p><b>PRAGMA default_temp_store;