From: drh Date: Wed, 8 Sep 2004 13:06:21 +0000 (+0000) Subject: Documentation updates. (CVS 1946) X-Git-Tag: version-3.6.10~4200 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=916d68efea12c98bc2c30f9ee5e3261e5838015a;p=thirdparty%2Fsqlite.git Documentation updates. (CVS 1946) FossilOrigin-Name: 799f5383c0c72a74c7b29f9f40fc949f3248a499 --- diff --git a/manifest b/manifest index f584ab9a63..e525a1b33d 100644 --- a/manifest +++ b/manifest @@ -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 diff --git a/manifest.uuid b/manifest.uuid index ddef491877..f06cb123ab 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -435b3f301fbb6953adc974c7f03589b06e9114c3 \ No newline at end of file +799f5383c0c72a74c7b29f9f40fc949f3248a499 \ No newline at end of file diff --git a/www/arch.tcl b/www/arch.tcl index 39977484eb..dede214c3d 100644 --- a/www/arch.tcl +++ b/www/arch.tcl @@ -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.

-

History

-There are two main C interfaces to the SQLite library: -sqlite_exec() and sqlite_compile(). 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. -

- -

-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 os.c has now been split out into -several file, on for each operating system. And -the prefix on the names of API routines changed from sqlite_ -to sqlite3_. +This document describes SQLite version 3.0. Version 2.8 and +earlier are similar but the details differ.

Interface

Much of the public interface to the SQLite library is implemented by -functions found in the main.c source file though some routines are +functions found in the main.c, legacy.c, and +vdbeapi.c source files +though some routines are scattered about in other files where they can have access to data structures with file scope. The -sqlite_get_table() routine is implemented in table.c. -sqlite_step() is found in vdbe.c. -sqlite_mprintf() is found in printf.c. +sqlite3_get_table() routine is implemented in table.c. +sqlite3_mprintf() is found in printf.c. +sqlite3_complete() is in tokenize.c. The Tcl interface is implemented by tclsqlite.c. More information on the C interface to SQLite is -available separately.

+available separately.

To avoid name collisions with other software, all external -symbols in the SQLite library begin with the prefix sqlite. +symbols in the SQLite library begin with the prefix sqlite3. Those symbols that are intended for external use (in other words, those symbols which form the API for SQLite) begin -with sqlite_.

- -

SQL Command Processor

- -

+with sqlite3_.

Tokenizer

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 tokenize.c source file.

+one by one to the parser. The tokenizer is hand-coded in C in +the file tokenize.c.

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.

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: build.c, copy.c, +files in the code generator: +attach.c, +auth.c, +build.c, delete.c, -expr.c, insert.c, pragma.c, -select.c, trigger.c, update.c, vacuum.c +expr.c, +insert.c, +pragma.c, +select.c, +trigger.c, +update.c, +vacuum.c and where.c. In these files is where most of the serious magic happens. expr.c handles code generation for expressions. where.c handles code generation for WHERE clauses on -SELECT, UPDATE and DELETE statements. The files copy.c, +SELECT, UPDATE and DELETE statements. The files attach.c, delete.c, insert.c, select.c, trigger.c update.c, and vacuum.c handle the code generation for SQL statements with the same names. (Each of these files calls routines in expr.c and where.c as necessary.) All other -SQL statements are coded out of build.c.

+SQL statements are coded out of build.c. +The auth.c file implements the functionality of +sqlite3_set_authorizer().

Virtual Machine

@@ -146,14 +133,28 @@ between the virtual machine and the rest of the SQLite library and vdbeInt.h which defines structure private the virtual machine. The vdbeaux.c file contains utilities used by the virtual machine and interface modules used by the rest of the library to -construct VM programs.

+construct VM programs. The vdbeapi.c file contains external +interfaces to the virtual machine such as the +sqlite3_bind_... family of functions. Individual values +(strings, integer, floating point numbers, and BLOBs) are stored +in an internal object named "Mem" which is implemented by +vdbemem.c.

+ +

+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: coalesce(), count(), +substr(), and so forth) can be found in func.c. +Date and time conversion functions are found in date.c. +

B-Tree

An SQLite database is maintained on disk using a B-tree implementation found in the btree.c 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.

+same disk file. Details of the file format are recorded in a large +comment at the beginning of btree.c.

The interface to the B-tree subsystem is defined by the header file btree.h. @@ -161,11 +162,13 @@ same disk file.

Page Cache

-

The B-tree module requests information from the disk in 1024 byte -chunks. The page cache is reponsible for reading, writing, and +

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 pager.h.

In order to provide portability between POSIX and Win32 operating systems, SQLite uses an abstraction layer to interface with the operating system. -The os.c 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 os.h header file. +The interface to the OS abstraction layer is defined in +os.h. Each supported operating system has its own implementation: +os_unix.c for Unix, os_win.c for windows, and so forth. +Each of these operating-specific implements typically has its own +header file: os_unix.h, os_win.h, etc.

+ +

Utilities

+ +

+Memory allocation and caseless string comparison routines are located +in util.c. +Symbol tables used by the parser are maintained by hash tables found +in hash.c. The utf.c source file contains Unicode +conversion subroutines. +SQLite has its own private implementation of printf() (with +some extensions) in printf.c and its own random number generator +in random.c. +

+ +

Test Code

+ +

+If you count regression test scripts, +more than half the total code base of SQLite is devoted to testing. +There are many assert() statements in the main code files. +In additional, the source files test1.c through test5.c +together with md5.c implement extensions used for testing +purposes only. The os_test.c backend interface is used to +simulate power failures to verify the crash-recovery mechanism in +the pager. +

+ } footer $rcsid diff --git a/www/arch2.gif b/www/arch2.gif index ef91eacdcc..cca2925172 100644 Binary files a/www/arch2.gif and b/www/arch2.gif differ diff --git a/www/lang.tcl b/www/lang.tcl index aa699c0ed1..5f0e3f45df 100644 --- a/www/lang.tcl +++ b/www/lang.tcl @@ -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 []] puts {

Beginning in version 2.0, SQLite supports transactions with -rollback and atomic commit. See ATTACH for -an exception when there are attached databases.

+rollback and atomic commit.

The optional transaction name is ignored. SQLite currently does not allow nested transactions.

@@ -261,6 +260,9 @@ puts {

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 command-line shell +contains a new command .import that can be used as a substitute +for COPY.

The COPY command is an extension used to load large amounts of @@ -389,10 +391,10 @@ for use by the engine.

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 typeless. 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 Datatypes In SQLite Version 3 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.

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

+1 megabytes in version 2.8. In version 3.0 there is no arbitrary +limit on the amount of data in a row.

+

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 [ .] } puts { -

The DROP INDEX statement removes an index added with the +

The DROP INDEX statement removes an index added +with the CREATE INDEX 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.

The functions shown below are available by default. Additional functions may be written in C and added to the database engine using -the sqlite_create_function() +the sqlite3_create_function() API.

@@ -941,8 +945,8 @@ all arguments are NULL then NULL is returned. There must be at least @@ -973,8 +977,8 @@ characters is returned, not the number of bytes. @@ -1012,6 +1016,17 @@ only a single argument. otherwise return NULL. + + + + + +return values are "null", "integer", "real", "text", and "blob". +SQLite's type handling is +explained in Datatypes in SQLite Version 3. @@ -1069,7 +1085,8 @@ UTF-8 strings.

The following aggregate functions are available by default. Additional aggregate functions written in C may be added using the -sqlite_create_aggregate() API.

+sqlite3_create_function() +API.

glob(X,Y) This function is used to implement the -"Y GLOB X" syntax of SQLite. The -sqlite_create_function() +"X GLOB Y" syntax of SQLite. The +sqlite3_create_function() interface can be used to override this function and thereby change the operation of the GLOB operator. like(X,Y) This function is used to implement the -"Y LIKE X" syntax of SQL. The -sqlite_create_function() +"X LIKE Y" syntax of SQL. The +sqlite_create_function() interface can be used to override this function and thereby change the operation of the LIKE operator.
quote(X)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. +
random(*) Return a random integer between -2147483648 and @@ -1053,8 +1068,9 @@ then characters indices refer to actual UTF-8 characters, not bytes.
typeof(X) Return the type of the expression X. The only -return values are "numeric" and "text". SQLite's type handling is -explained in Datatypes in SQLite.
@@ -1270,8 +1287,10 @@ is returned it is as an integer.

  • PRAGMA default_cache_size;
    PRAGMA default_cache_size =     Number-of-pages;

    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 cache_size + will hold in memory at once. Each page uses 1K on disk and about + 1.5K in memory. + This pragma works like the + cache_size 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.

    This pragma changes the synchronous mode persistently. Once changed, the mode stays as set even if the database is closed and reopened. The synchronous pragma does the same - thing but only applies the setting to the current session.

    • + thing but only applies the setting to the current session. + +

  • PRAGMA default_temp_store;