1.3 Queries.
R-tree tables may be queried using all of the same SQL syntax supported
- by regular tables. However, some query patterns are more efficient faster
+ by regular tables. However, some query patterns are more efficient
than others.
R-trees support fast lookup by primary key value (O(logN), like
2. COMPILATION AND USAGE
- The easiest way to compile and use the ICU extension is to build
+ The easiest way to compile and use the RTREE extension is to build
and use it as a dynamically loadable SQLite extension. To do this
using gcc on *nix:
gcc -shared rtree.c -o libSqliteRtree.so
You may need to add "-I" flags so that gcc can find sqlite3ext.h
- and sqlite3.h. The resulting shared lib, libSqliteIcu.so, may be
+ and sqlite3.h. The resulting shared lib, libSqliteRtree.so, may be
loaded into sqlite in the same way as any other dynamicly loadable
extension.
[2] Norbert Beckmann, Hans-Peter Kriegel, Ralf Schneider, Bernhard Seeger,
"The R*-tree: An Efficient and Robust Access Method for Points and
Rectangles", Universitaet Bremen, 1990.
-
-
-
** This file contains code for implementations of the r-tree and r*-tree
** algorithms packaged as an SQLite virtual table module.
**
-** $Id: rtree.c,v 1.1 2008/05/26 18:41:54 danielk1977 Exp $
+** $Id: rtree.c,v 1.2 2008/05/26 20:19:25 drh Exp $
*/
#if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_RTREE)
#include <string.h>
#include <assert.h>
-typedef sqlite3_int64 i64;
-typedef unsigned char u8;
-typedef unsigned int u32;
+#ifndef SQLITE_CORE
+ typedef sqlite3_int64 i64;
+ typedef unsigned char u8;
+ typedef unsigned int u32;
+#endif
typedef struct Rtree Rtree;
typedef struct RtreeCursor RtreeCursor;
return sqlite3_reset(pRtree->pWriteParent);
}
-static int insertCell(Rtree *, RtreeNode *, RtreeCell *, int);
+static int rtreeInsertCell(Rtree *, RtreeNode *, RtreeCell *, int);
#if VARIANT_GUTTMAN_LINEAR_SPLIT
/*
leftbbox.iRowid = pLeft->iNode;
if( pNode->iNode==1 ){
- rc = insertCell(pRtree, pLeft->pParent, &leftbbox, iHeight+1);
+ rc = rtreeInsertCell(pRtree, pLeft->pParent, &leftbbox, iHeight+1);
if( rc!=SQLITE_OK ){
goto splitnode_out;
}
nodeOverwriteCell(pRtree, pParent, &leftbbox, iCell);
AdjustTree(pRtree, pParent, &leftbbox);
}
- if( (rc = insertCell(pRtree, pRight->pParent, &rightbbox, iHeight+1)) ){
+ if( (rc = rtreeInsertCell(pRtree, pRight->pParent, &rightbbox, iHeight+1)) ){
goto splitnode_out;
}
rc = ChooseLeaf(pRtree, p, iHeight, &pInsert);
if( rc==SQLITE_OK ){
int rc2;
- rc = insertCell(pRtree, pInsert, p, iHeight);
+ rc = rtreeInsertCell(pRtree, pInsert, p, iHeight);
rc2 = nodeRelease(pRtree, pInsert);
if( rc==SQLITE_OK ){
rc = rc2;
** Insert cell pCell into node pNode. Node pNode is the head of a
** subtree iHeight high (leaf nodes have iHeight==0).
*/
-static int insertCell(
+static int rtreeInsertCell(
Rtree *pRtree,
RtreeNode *pNode,
RtreeCell *pCell,
rc = ChooseLeaf(pRtree, &cell, pNode->iNode, &pInsert);
if( rc==SQLITE_OK ){
int rc2;
- rc = insertCell(pRtree, pInsert, &cell, pNode->iNode);
+ rc = rtreeInsertCell(pRtree, pInsert, &cell, pNode->iNode);
rc2 = nodeRelease(pRtree, pInsert);
if( rc==SQLITE_OK ){
rc = rc2;
if( rc==SQLITE_OK ){
int rc2;
pRtree->iReinsertHeight = -1;
- rc = insertCell(pRtree, pLeaf, &cell, 0);
+ rc = rtreeInsertCell(pRtree, pLeaf, &cell, 0);
rc2 = nodeRelease(pRtree, pLeaf);
if( rc==SQLITE_OK ){
rc = rc2;
--- /dev/null
+/*
+** 2008 May 26
+**
+** The author disclaims copyright to this source code. In place of
+** a legal notice, here is a blessing:
+**
+** May you do good and not evil.
+** May you find forgiveness for yourself and forgive others.
+** May you share freely, never taking more than you give.
+**
+******************************************************************************
+**
+** This header file is used by programs that want to link against the
+** RTREE library. All it does is declare the sqlite3RtreeInit() interface.
+*/
+#include "sqlite3.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif /* __cplusplus */
+
+int sqlite3RtreeInit(sqlite3 *db);
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif /* __cplusplus */
fts3_porter.o \
fts3_tokenizer.o \
fts3_tokenizer1.o
+EXTOBJ += rtree.o
# All of the source code files.
#
$(TOP)/ext/fts3/fts3_tokenizer1.c
SRC += \
$(TOP)/ext/icu/icu.c
+SRC += \
+ $(TOP)/ext/rtree/rtree.h \
+ $(TOP)/ext/rtree/rtree.c
# Generated source code files
$(TOP)/ext/fts3/fts3.h \
$(TOP)/ext/fts3/fts3_hash.h \
$(TOP)/ext/fts3/fts3_tokenizer.h
+EXTHDR += \
+ $(TOP)/ext/rtree/rtree.h
# This is the default Makefile target. The objects listed here
# are what get build when you type just "make" with no arguments.
-C Import\s'rtree'\sextension.\s(CVS\s5159)
-D 2008-05-26T18:41:54
+C Update\sthe\samalgamation\sbuilder\sto\sincorporate\sthe\sRTREE\sextension.\s(CVS\s5160)
+D 2008-05-26T20:19:25
F Makefile.arm-wince-mingw32ce-gcc ac5f7b2cef0cd850d6f755ba6ee4ab961b1fadf7
F Makefile.in 79aeba12300a54903f1b1257c1e7c190234045dd
F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654
F ext/fts3/mkfts3amal.tcl 252ecb7fe6467854f2aa237bf2c390b74e71f100
F ext/icu/README.txt 3b130aa66e7a681136f6add198b076a2f90d1e33
F ext/icu/icu.c 12e763d288d23b5a49de37caa30737b971a2f1e2
-F ext/rtree/README decb7976cfacf834074d15028af99344439e30c3
-F ext/rtree/rtree.c f56f8a5888d3584f5b19112ade2855db5a985690
+F ext/rtree/README 64b8300581ba2553a4522ec78812dc940482906b
+F ext/rtree/rtree.c 9352fa04c917a3603ddfa9b0623e0cf039227470
+F ext/rtree/rtree.h 834dbcb82dc85b2481cde6a07cdadfddc99e9b9e
F ext/rtree/rtree.test ec173a9420ff012e4d29b3063add143583a597a7
F ext/rtree/rtree1.test 96563843773129eaec544f52768853f06be61d9c
F ext/rtree/rtree2.test 98f3c39b03577330566abf3c7e1e0baf8f9aa521
F ext/rtree/viewrtree.tcl 09526398dae87a5a87c5aac2b3854dbaf8376869
F install-sh 9d4de14ab9fb0facae2f48780b874848cbf2f895
F ltmain.sh 09fe5815427dc7d0abb188bbcdf0e34896577210
-F main.mk 6c01687f355dc8c7dff14a952a7c720b3a4c11a6
+F main.mk 0fdc9417630e829cae994efee59038810f091e33
F mkdll.sh 712e74f3efe08a6ba12b2945d018a29a89d7fe3b
F mkextu.sh 416f9b7089d80e5590a29692c9d9280a10dbad9f
F mkextw.sh 1a866b53637dab137191341cc875575a5ca110fb
F mkopcodec.awk 3fb9bf077053c968451f4dd03d11661ac373f9d1
F mkopcodeh.awk 513946ce4429bf2723aef0d640eb4d2493deb68e
F mkso.sh 24bde4c09e6fe80f718db3c31c068f45e13a2f2c
-F publish.sh 3ecffcfa9d4718b20fc8f1891ac529056636d37f
+F publish.sh 5efba7d327e0acf6633136f7f096c88aaa26df73
F publish_osx.sh 2ad2ee7d50632dff99949edc9c162dbb052f7534
F spec.template b2f6c4e488cbc3b993a57deba22cbc36203c4da3
F sqlite.pc.in c322c6244c6395955dca34d87955aabde7df7623
F src/journal.c cffd2cd214e58c0e99c3ff632b3bee6c7cbb260e
F src/legacy.c 8f5a2b25d9673b4004287cf2bf51dbf7d0738406
F src/loadext.c eac6c61810a3b531808774bec7f3d238cfe261f3
-F src/main.c 51f02209493572630dfcf4d4c8855f08aae21b9b
+F src/main.c 25358a404194d7571cdd3be001919a53b80106db
F src/malloc.c 12c1ae98ef1eff34b13c9eb526e0b7b479e1e820
F src/md5.c 008216bbb5d34c6fbab5357aa68575ad8a31516a
F src/mem1.c fc716ff521b6dd3e43eaa211967383308800e70a
F tool/memleak3.tcl 7707006ee908cffff210c98158788d85bb3fcdbf
F tool/mkkeywordhash.c ef93810fc41fb3d3dbacf9a33a29be88ea99ffa9
F tool/mkopts.tcl 66ac10d240cc6e86abd37dc908d50382f84ff46e x
-F tool/mksqlite3c.tcl f8f8233344494ad8a193056fe346f8f616951b78
+F tool/mksqlite3c.tcl da45d6d596f536d361e428874e7071710803de1e
F tool/mksqlite3internalh.tcl 47737a925fb02fce43e2c0a14b3cc17574a4d44a
F tool/omittest.tcl 7d1fdf469e2f4d175f70c36e469db64a1626fabb
F tool/opcodeDoc.awk b3a2a3d5d3075b8bd90b7afe24283efdd586659c
F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff
F tool/speedtest8.c e74126bc12178fa29904f711bb100212a5448041
F tool/speedtest8inst1.c 025879132979a5fdec11218472cba6cf8f6ec854
-F www/34to35.tcl 942e479aa7740b55d714dce0f0b2cb6ca91c3f20
-F www/arch.fig d5f9752a4dbf242e9cfffffd3f5762b6c63b3bcf
-F www/arch.gif f845a64772062e82d17980a349f95f1f0b4c8054
-F www/arch.png 82ef36db1143828a7abc88b1e308a5f55d4336f4
-F www/arch.tcl 03a6c66b1b34209d2897352e058377b421f0b80e
-F www/arch2.fig ae2432145c26cfa148fa0116589517ad3cd5fc65
-F www/arch2.gif 6f2d47c4e0c5842c0d6b5513fd8249393d7c7003
-F www/arch2b.fig d22a2c9642d584b89d4088b1e51e2bb0f7c04bed
-F www/audit.tcl 90e09d580f79c7efec0c7d6f447b7ec5c2dce5c0
-F www/autoinc.tcl b357f5ba954b046ee35392ce0f884a2fcfcdea06
-F www/c_interface.tcl b51b08591554c16a0c3ef718364a508ac25abc7e
-F www/capi3.tcl 88884dd743039d1a95aa57f4a5eb369de7744716
-F www/capi3ref.tcl 167c2d5b45da22d77b2493b00d44b001b4ec83b1
-F www/changes.tcl 7540ccadb3072f3aba44f9f745aad0f4a0458a55
-F www/common.tcl 2b793e5c31486c8a01dd27dc0a631ad93704438e
-F www/compile.tcl 276546d7eb445add5a867193bbd80f6919a6b084
-F www/conflict.tcl cdd0f4b59b0ba6d61f67e6a38f3ae45853bacb30
-F www/copyright-release.html 294e011760c439c44951a6bfecd4c81a1ae359e8
-F www/copyright-release.pdf cfca3558fc97095e57c6117d08f1f5b80d95125a
-F www/copyright.tcl b698824cea9b503751bf7380a98883a264d600a0
-F www/datatype3.tcl f7b6831c9088549efe021df4f71a34c0095d4e94
-F www/datatypes.tcl 7c786d2e8ff434346764534ec015966d17efce60
-F www/different.tcl 8b76ae88bf73e38097b7936e198df4f89baf587c
-F www/direct1b.gif 32b48b764244817b6b591898dc52a04299a7b8a7
-F www/docs.tcl be3fabaead4a21ec5315934f5eac10b4e79081c7
-F www/download.tcl d59a0244f22a975c3f9deafb535fc20549cb8c45
-F www/dynload.tcl 02eb8273aa78cfa9070dd4501dca937fb22b466c
-F www/faq.tcl ebdcad6041d66220b866ac49bcd55726c3bd80ef
-F www/fileformat.tcl 900c95b9633abc3dcfc384d9ddd8eb4876793059
-F www/formatchng.tcl 722a9c08be4f7325b3a545abfe508cfbabe20eb7
-F www/fullscanb.gif f7c94cb227f060511f8909e10f570157263e9a25
-F www/index-ex1-x-b.gif f9b1d85c3fa2435cf38b15970c7e3aa1edae23a3
-F www/index.tcl d23c2491aed9fef025c95b0d0f954ee6a28703dd
-F www/indirect1b1.gif adfca361d2df59e34f9c5cac52a670c2bfc303a1
-F www/lang.tcl e015c489a30cbf5669bc6aef5c932a6b4f6ddf48
-F www/limits.tcl 9035eb73e814ccb298595fd57670dec817533616
-F www/lockingv3.tcl e52345bd20323bef6146bfce18ae0829b2b7c87d
-F www/mingw.tcl d96b451568c5d28545fefe0c80bee3431c73f69c
-F www/mkapidoc.tcl 2fdbb765c38a4467687ba390e07c1229d4939a3b
-F www/nulls.tcl ec35193f92485b87b90a994a01d0171b58823fcf
-F www/oldnews.tcl acfcfc6e90c41ef46a605c87972cdb6061867e1f
-F www/omitted.tcl ee6b46f83d513b2187869740da829a700e1a355e
-F www/opcode.tcl 5bd68059416b223515a680d410a9f7cb6736485f
-F www/optimizer.tcl d6812a10269bd0d7c488987aac0ad5036cace9dc
-F www/optimizing.tcl f0b2538988d1bbad16cbfe63ec6e8f48c9eb04e5
-F www/optoverview.tcl 815df406a38c9f69b27d37e8f7ede004c6d9f19e
-F www/pragma.tcl 93b37b2b7f39be33d3462416f2af8a627561960a
-F www/quickstart.tcl 8708a4ca83fbf55c66af1782992626f20c3df095
-F www/shared.gif 265bae80c5b311c5a86e47662821076ffaf5c6ea
-F www/sharedcache.tcl 3ebec81110e606af6fd65a3c4c19562cb173b29c
-F www/speed.tcl 656ed5be8cc9d536353e1a96927b925634a62933
-F www/sqlite.tcl abb87f0d74a4fe9642987466bb59fe6abada988f
-F www/support.tcl 1b94f4a98abfddcc1b13fb41565c8f66629cdf03
-F www/table-ex1b2.gif a588d21a2d88bb2a2ef0431fcc5ed5aa48c0bbc5
-F www/tclsqlite.tcl 8be95ee6dba05eabcd27a9d91331c803f2ce2130
-F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0
-F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b
-F www/whentouse.tcl fc46eae081251c3c181bd79c5faef8195d7991a5
-P 33548744369643cc8843b74ad1fc1b7d5988d7a4
-R 675fcc0cf171d37f901dfc59fa943c1b
-U danielk1977
-Z a3cfe87334f3bee1a0f0c75b4054c9e1
+P b104dcd6adadbd3fe15a348fe9d4d290119e139e
+R b2d59c86708fea19320a46b10d663097
+U drh
+Z 0bf3965fe2dcc107d2419d0fa0170efc
-b104dcd6adadbd3fe15a348fe9d4d290119e139e
\ No newline at end of file
+aa8eba3360c31182f5238e96b83a382374f40fab
\ No newline at end of file
#
make clean
make sqlite3.c
-CFLAGS="-Os -DSQLITE_ENABLE_FTS3=1 -DSQLITE_THREADSAFE=0"
+CFLAGS="-Os -DSQLITE_ENABLE_FTS3=0 -DSQLITE_ENABLE_RTREE=0"
+CFLAGS="$CFLAGS -DSQLITE_THREADSAFE=0"
echo '***** '"COMPILING sqlite3-$VERS.bin..."
gcc $CFLAGS -Itsrc sqlite3.c tsrc/shell.c -o sqlite3 -ldl
strip sqlite3
#
TCLDIR=/home/drh/tcltk/846/linux/846linux
TCLSTUBLIB=$TCLDIR/libtclstub8.4g.a
-CFLAGS="-Os -DSQLITE_ENABLE_FTS3=1 -DHAVE_LOCALTIME_R=1 -DHAVE_GMTIME_R=1"
+CFLAGS="-Os -DSQLITE_ENABLE_FTS3=3 -DSQLITE_ENABLE_RTREE=1"
+CFLAGS="$CFLAGS -DHAVE_LOCALTIME_R=1 -DHAVE_GMTIME_R=1"
echo '***** BUILDING shared libraries for linux'
gcc $CFLAGS -shared tclsqlite3.c $TCLSTUBLIB -o tclsqlite3.so -lpthread
strip tclsqlite3.so
# Build the sqlite.exe executable for windows.
#
OPTS='-DSTATIC_BUILD=1 -DNDEBUG=1 -DSQLITE_THREADSAFE=0'
-OPTS="$OPTS -DSQLITE_ENABLE_FTS3=1"
+OPTS="$OPTS -DSQLITE_ENABLE_FTS3=1 -DSQLITE_ENABLE_RTREE=1"
i386-mingw32msvc-gcc -Os $OPTS -Itsrc -I$TCLDIR sqlite3.c tsrc/shell.c \
-o sqlite3.exe
zip doc/sqlite-$VERSW.zip sqlite3.exe
** other files are for internal use by SQLite and should not be
** accessed by users of the library.
**
-** $Id: main.c,v 1.441 2008/05/26 18:41:54 danielk1977 Exp $
+** $Id: main.c,v 1.442 2008/05/26 20:19:26 drh Exp $
*/
#include "sqliteInt.h"
#include <ctype.h>
+
#ifdef SQLITE_ENABLE_FTS3
# include "fts3.h"
#endif
+#ifdef SQLITE_ENABLE_RTREE
+# include "rtree.h"
+#endif
/*
** The version of the library
#ifdef SQLITE_ENABLE_RTREE
if( !db->mallocFailed && rc==SQLITE_OK){
- extern int sqlite3RtreeInit(sqlite3*);
rc = sqlite3RtreeInit(db);
}
#endif
os_os2.h
pager.h
parse.h
+ rtree.h
sqlite3ext.h
sqlite3.h
sqliteInt.h
fts3_porter.c
fts3_tokenizer.c
fts3_tokenizer1.c
+
+ rtree.c
} {
copy_file tsrc/$file
}
+++ /dev/null
-#
-# Run this TCL script to generate HTML for the goals.html file.
-#
-set rcsid {$Id: 34to35.tcl,v 1.4 2007/10/01 13:54:11 drh Exp $}
-source common.tcl
-header {SQLite Changes From Version 3.4.2 To 3.5.0}
-
-proc CODE {text} {
- puts "<blockquote><pre>"
- puts $text
- puts "</pre></blockquote>"
-}
-proc SYNTAX {text} {
- puts "<blockquote><pre>"
- set t2 [string map {& & < < > >} $text]
- regsub -all "/(\[^\n/\]+)/" $t2 {</b><i>\1</i><b>} t3
- puts "<b>$t3</b>"
- puts "</pre></blockquote>"
-}
-proc IMAGE {name {caption {}}} {
- puts "<center><img src=\"$name\">"
- if {$caption!=""} {
- puts "<br>$caption"
- }
- puts "</center>"
-}
-proc PARAGRAPH {text} {
- # regsub -all "/(\[a-zA-Z0-9\]+)/" $text {<i>\1</i>} t2
- #regsub -all "\\*(\[^\n*\]+)\\*" $text {<tt><b><big>\1</big></b></tt>} t3
- regsub -all {\[([^]\n]+)\]} $text {[resolve_link \1]} t3
- puts "<p>[subst -novar -noback $t3]</p>\n"
-}
-proc resolve_link {args} {
- set a2 [split $args |]
- set id [string trim [lindex $a2 0]]
- if {[lindex $a2 1]==""} {
- set display [string trim [lindex $a2 0]]
- } else {
- set display [string trim [lrange $a2 1 end]]
- }
- regsub -all {[^a-zA-Z0-9_]} $id {} id
- return "<a href=\"capi3ref.html#$id\">$display</a>"
-}
-set level(0) 0
-set level(1) 0
-proc HEADING {n name {tag {}}} {
- if {$tag!=""} {
- puts "<a name=\"$tag\">"
- }
- global level
- incr level($n)
- for {set i [expr {$n+1}]} {$i<10} {incr i} {
- set level($i) 0
- }
- if {$n==0} {
- set num {}
- } elseif {$n==1} {
- set num $level(1).0
- } else {
- set num $level(1)
- for {set i 2} {$i<=$n} {incr i} {
- append num .$level($i)
- }
- }
- incr n 1
- puts "<h$n>$num $name</h$n>"
-}
-
-HEADING 0 {Moving From SQLite 3.4.2 to 3.5.0}
-
-PARAGRAPH {
- SQLite version 3.5.0 introduces a new OS interface layer that
- is incompatible with all prior versions of SQLite. In addition,
- a few existing interfaces have been generalized to work across all
- database connections within a process rather than just all
- connections within a thread. The purpose of this article
- is to describe the changes to 3.5.0 in detail so that users
- of prior versions of SQLite can judge what, if any, effort will
- be required to upgrade to newer versions.
-}
-
-HEADING 1 {Overview Of Changes}
-
-PARAGRAPH {
- A quick enumeration of the changes in SQLite version 3.5.0
- is provide here. Subsequent sections will describe these
- changes in more detail.
-}
-PARAGRAPH {
- <ol>
- <li>The OS interface layer has been completely reworked:
- <ol type="a">
- <li>The undocumented <b>sqlite3_os_switch()</b> interface has
- been removed.</li>
- <li>The <b>SQLITE_ENABLE_REDEF_IO</b> compile-time flag no longer functions.
- I/O procedures are now always redefinable.</li>
- <li>Three new objects are defined for specifying I/O procedures:
- [sqlite3_vfs], [sqlite3_file], and [sqlite3_io_methods].</li>
- <li>Three new interfaces are used to create alternative OS interfaces:
- [sqlite3_vfs_register()], [sqlite3_vfs_unregister()], and
- [sqlite3_vfs_find()].</li>
- <li>A new interface has been added to provided additional control over
- the creation of new database connections: [sqlite3_open_v2()].
- The legacy interfaces of [sqlite3_open()] and
- [sqlite3_open16()] continue to be fully supported.</li>
- </ol></li>
- <li>The optional shared cache and memory management features that
- were introduced in version 3.3.0 can now be used across multiple
- threads within the same process. Formerly, these extensions only
- applied to database connections operating within a single thread.
- <ol type="a">
- <li>The [sqlite3_enable_shared_cache()] interface now applies to all
- threads within a process, not to just the one thread in which it
- was run.</li>
- <li>The [sqlite3_soft_heap_limit()] interface now applies to all threads
- within a process, not to just the one thread in which it was run.</li>
- <li>The [sqlite3_release_memory()] interface will now attempt to reduce
- the memory usages across all database connections in all threads, not
- just connections in the thread where the interface is called.</li>
- <li>The [sqlite3_thread_cleanup()] interface has become a no-op.</li>
- </ol></li>
- <li>Restrictions on the use of the same database connection by multiple
- threads have been dropped. It is now safe for
- multiple threads to use the same database connection at the same
- time.</li>
- <li>There is now a compile-time option that allows an application to
- define alternative malloc()/free() implementations without having
- to modify any core SQLite code.</li>
- <li>There is now a compile-time option that allows an application to
- define alternative mutex implementations without having
- to modify any core SQLite code.</li>
- </ol>
-}
-PARAGRAPH {
- Of these changes, only 1a and 2a through 2c are incompatibilities
- in any formal sense.
- But users who have previously made custom modifications to the
- SQLite source (for example to add a custom OS layer for embedded
- hardware) might find that these changes have a larger impact.
- On the other hand, an important goal of these changes is to make
- it much easier to customize SQLite for use on different operating
- systems.
-}
-
-HEADING 1 {The OS Interface Layer}
-
-PARAGRAPH {
- If your system defines a custom OS interface for SQLite or if you
- were using the undocumented <b>sqlite3_os_switch()</b>
- interface, then you will need to make modifications in order to
- upgrade to SQLite version 3.5.0. This may seem painful at first
- glance. But as you look more closely, you will probably discover
- that your changes are made smaller and easier to understand and manage
- by the new SQLite interface. It is likely that your changes will
- now also work seamlessly with the SQLite amalgamation. You will
- no longer need to make any changes to the code SQLite source code.
- All of your changes can be effected by application code and you can
- link against a standard, unmodified version of the SQLite amalgamation.
- Furthermore, the OS interface layer, which was formerly undocumented,
- is now an officially support interface for SQLite. So you have
- some assurance that this will be a one-time change and that your
- new backend will continue to work in future versions of SQLite.
-}
-
-HEADING 2 {The Virtual File System Object}
-
-PARAGRAPH {
- The new OS interface for SQLite is built around an object named
- [sqlite3_vfs]. The "vfs" standard for "Virtual File System".
- The sqlite3_vfs object is basically a structure containing pointers
- to functions that implement the primitive disk I/O operations that
- SQLite needs to perform in order to read and write databases.
- In this article, we will often refer a sqlite3_vfs objects as a "VFS".
-}
-
-PARAGRAPH {
- SQLite is able to use multiple VFSes at the same time. Each
- individual database connection is associated with just one VFS.
- But if you have multiple database connections, each connection
- can be associated with a different VFS.
-}
-
-PARAGRAPH {
- There is always a default VFS.
- The legacy interfaces [sqlite3_open()] and [sqlite3_open16()] always
- use the default VFS.
- The new interface for creating database connections,
- [sqlite3_open_v2()], allows you to specify which VFS you want to
- use by name.
-}
-
-HEADING 3 {Registering New VFS Objects}
-
-PARAGRAPH {
- Standard builds of SQLite for unix or windows come with a single
- VFS named "unix" or "win32", as appropriate. This one VFS is also
- the default. So if you are using the legacy open functions, everything
- will continue to operate as it has before. The change is that an application
- now has the flexibility of adding new VFS modules to implement a
- customized OS layer. The [sqlite3_vfs_register()] API can be used
- to tell SQLite about one or more application-defined VFS modules:
-}
-
-CODE {
-int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
-}
-
-PARAGRAPH {
- Applications can call sqlite3_vfs_register at any time, though of course
- a VFS needs to be registered before it can be used. The first argument
- is a pointer to a customized VFS object that the application has prepared.
- The second argument is true to make the new VFS the default VFS so that
- it will be used by the legacy [sqlite3_open()] and [sqlite3_open16()] APIs.
- If the new VFS is not the default, then you will probably have to use
- the new [sqlite3_open_v2()] API to use it. Note, however, that if
- a new VFS is the only VFS known to SQLite (if SQLite was compiled without
- its usual default VFS or if the pre-compiled default VFS was removed
- using [sqlite3_vfs_unregister()]) then the new VFS automatic becomes the
- default VFS regardless of the makeDflt argument to [sqlite3_vfs_register()].
-}
-
-PARAGRAPH {
- Standard builds include the default "unix" or "win32" VFSes.
- But if you use the -DOS_OTHER=1 compile-time option, then SQLite is
- built without a default VFS. In that case, the application must
- register at least one VFS prior to calling [sqlite3_open()].
- This is the approach that embedded applications should use.
- Rather than modifying the SQLite source to to insert an alternative
- OS layer as was done in prior releases of SQLite, instead compile
- an unmodified SQLite source file (preferably the amalgamation)
- with the -DOS_OTHER=1 option, then invoke [sqlite3_vfs_register()]
- to define the interface to the underlying filesystem prior to
- creating any database connections.
-}
-
-HEADING 3 {Additional Control Over VFS Objects}
-
-PARAGRAPH {
- The [sqlite3_vfs_unregister()] API is used to remove an existing
- VFS from the system.
-}
-
-CODE {
-int sqlite3_vfs_unregister(sqlite3_vfs*);
-}
-
-PARAGRAPH {
- The [sqlite3_vfs_find()] API is used to locate a particular VFS
- by name. Its prototype is as follows:
-}
-
-CODE {
-sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
-}
-
-PARAGRAPH {
- The argument is the symbolic name for the desired VFS. If the
- argument is a NULL pointer, then the default VFS is returned.
- The function returns a pointer to the [sqlite3_vfs] object that
- implements the VFS. Or it returns a NULL pointer if no object
- could be found that matched the search criteria.
-}
-
-HEADING 3 {Modifications Of Existing VFSes}
-
-PARAGRAPH {
- Once a VFS has been registered, it should never be modified. If
- a change in behavior is required, a new VFS should be registered.
- The application could, perhaps, use [sqlite3_vfs_find()] to locate
- the old VFS, make a copy of the old VFS into a new [sqlite3_vfs]
- object, make the desired modifications to the new VFS, unregister
- the old VFS, the register the new VFS in its place. Existing
- database connections would continue to use the old VFS even after
- it is unregistered, but new database connections would use the
- new VFS.
-}
-
-HEADING 3 {The VFS Object}
-
-PARAGRAPH {
- A VFS object is an instance of the following structure:
-}
-
-CODE {
-typedef struct sqlite3_vfs sqlite3_vfs;
-struct sqlite3_vfs {
- int iVersion; /* Structure version number */
- int szOsFile; /* Size of subclassed sqlite3_file */
- int mxPathname; /* Maximum file pathname length */
- sqlite3_vfs *pNext; /* Next registered VFS */
- const char *zName; /* Name of this virtual file system */
- void *pAppData; /* Pointer to application-specific data */
- int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
- int flags, int *pOutFlags);
- int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
- int (*xAccess)(sqlite3_vfs*, const char *zName, int flags);
- int (*xGetTempName)(sqlite3_vfs*, char *zOut);
- int (*xFullPathname)(sqlite3_vfs*, const char *zName, char *zOut);
- void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
- void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
- void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol);
- void (*xDlClose)(sqlite3_vfs*, void*);
- int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
- int (*xSleep)(sqlite3_vfs*, int microseconds);
- int (*xCurrentTime)(sqlite3_vfs*, double*);
- /* New fields may be appended in figure versions. The iVersion
- ** value will increment whenever this happens. */
-};
-}
-
-PARAGRAPH {
- To create a new VFS, an application fills in an instance of this
- structure with appropriate values and then calls [sqlite3_vfs_register()].
-}
-
-PARAGRAPH {
- The iVersion field of [sqlite3_vfs] should be 1 for SQLite version 3.5.0.
- This number may increase in future versions of SQLite if we have to
- modify the VFS object in some way. We hope that this never happens,
- but the provision is made in case it does.
-}
-
-PARAGRAPH {
- The szOsFile field is the size in bytes of the structure that defines
- an open file: the [sqlite3_file] object. This object will be described
- more fully below. The point here is that each VFS implementation can
- define its own [sqlite3_file] object containing whatever information
- the VFS implementation needs to store about an open file. SQLite needs
- to know how big this object is, however, in order to preallocate enough
- space to hold it.
-}
-
-PARAGRAPH {
- The mxPathname field is the maximum length of a file pathname that
- this VFS can use. SQLite sometimes has to preallocate buffers of
- this size, so it should be as small as reasonably possible. Some
- filesystems permit huge pathnames, but in practice pathnames rarely
- extend beyond 100 bytes or so. You do not have to put the longest
- pathname that the underlying filesystem can handle here. You only
- have to put the longest pathname that you want SQLite to be able to
- handle. A few hundred is a good value in most cases.
-}
-
-PARAGRAPH {
- The pNext field is used internally by SQLite. Specifically, SQLite
- uses this field to form a linked list of registered VFSes.
-}
-
-PARAGRAPH {
- The zName field is the symbolic name of the VFS. This is the name
- that the [sqlite3_vfs_find()] compares against when it is looking for
- a VFS.
-}
-
-PARAGRAPH {
- The pAppData pointer is unused by the SQLite core. The pointer is
- available to store auxiliary information that a VFS information might
- want to carry around.
-}
-
-PARAGRAPH {
- The remaining fields of the [sqlite3_vfs] object all store pointer
- to functions that implement primitive operations. We call these
- "methods". The first methods, xOpen, is used to open files on
- the underlying storage media. The result is an [sqlite3_file]
- object. There are additional methods, defined by the [sqlite3_file]
- object itself that are used to read and write and close the file.
- The additional methods are detailed below. The filename is in UTF-8.
- SQLite will guarantee that the zFilename string passed to
- xOpen() is a full pathname as generated by xFullPathname() and
- that the string will be valid and unchanged until xClose() is
- called. So the [sqlite3_file] can store a pointer to the
- filename if it needs to remember the filename for some reason.
- The flags argument to xOpen() is a copy of the flags argument
- to sqlite3_open_v2(). If sqlite3_open() or sqlite3_open16()
- is used, then flags is [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].
- If xOpen() opens a file read-only then it sets *pOutFlags to
- include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be
- set.
- SQLite will also add one of the following flags to the xOpen()
- call, depending on the object being opened:
- <ul>
- <li> [SQLITE_OPEN_MAIN_DB]
- <li> [SQLITE_OPEN_MAIN_JOURNAL]
- <li> [SQLITE_OPEN_TEMP_DB]
- <li> [SQLITE_OPEN_TEMP_JOURNAL]
- <li> [SQLITE_OPEN_TRANSIENT_DB]
- <li> [SQLITE_OPEN_SUBJOURNAL]
- <li> [SQLITE_OPEN_MASTER_JOURNAL]
- </ul>
- The file I/O implementation can use the object type flags to
- changes the way it deals with files. For example, an application
- that does not care about crash recovery or rollback, might make
- the open of a journal file a no-op. Writes to this journal are
- also a no-op. Any attempt to read the journal returns [SQLITE_IOERR].
- Or the implementation might recognize the a database file will
- be doing page-aligned sector reads and writes in a random order
- and set up its I/O subsystem accordingly.
- SQLite might also add one of the following flags to the xOpen
- method:
- <ul>
- <li> [SQLITE_OPEN_DELETEONCLOSE]
- <li> [SQLITE_OPEN_EXCLUSIVE]
- </ul>
- The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
- deleted when it is closed. This will always be set for TEMP
- databases and journals and for subjournals. The
- [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
- for exclusive access. This flag is set for all files except
- for the main database file.
- The [sqlite3_file] structure passed as the third argument to
- xOpen is allocated by the caller. xOpen just fills it in. The
- caller allocates a minimum of szOsFile bytes for the [sqlite3_file]
- structure.
-}
-
-PARAGRAPH {
- The differences between an [SQLITE_OPEN_TEMP_DB] database and an
- [SQLITE_OPEN_TRANSIENT_DB] database is this: The [SQLITE_OPEN_TEMP_DB]
- is used for explicitly declared and named TEMP tables (using the
- CREATE TEMP TABLE syntax) or for named tables in a temporary database
- that is created by opening a database with a filename that is an empty
- string. An [SQLITE_OPEN_TRANSIENT_DB] holds an database table that
- SQLite creates automatically in order to evaluate a subquery or
- ORDER BY or GROUP BY clause. Both TEMP_DB and TRANSIENT_DB databases
- are private and are deleted automatically. TEMP_DB databases last
- for the duration of the database connection. TRANSIENT_DB databases
- last only for the duration of a single SQL statement.
-}
-
-PARAGRAPH {
- The xDelete method is used delete a file. The name of the file is
- given in the second parameter. The filename will be in UTF-8.
- The VFS must convert the filename into whatever character representation
- the underlying operating system expects. If the syncDir parameter is
- true, then the xDelete method should not return until the change
- to the directory contents for the directory containing the
- deleted file have been synced to disk in order to insure that the
- file does not "reappear" if a power failure occurs soon after.
-}
-
-PARAGRAPH {
- The xAccess method is used to check for access permissions on a file.
- The filename will be UTF-8 encoded. The flags argument will be
- [SQLITE_ACCESS_EXISTS] to check for the existence of the file,
- [SQLITE_ACCESS_READWRITE] to check to see if the file is both readable
- and writable, or [SQLITE_ACCESS_READ] to check to see if the file is
- at least readable. The "file" named by the second parameter might
- be a directory or folder name.
-}
-
-PARAGRAPH {
- The xGetTempName method computes the name of a temporary file that
- SQLite can use. The name should be written into the buffer given
- by the second parameter. SQLite will size that buffer to hold
- at least mxPathname bytes. The generated filename should be in UTF-8.
- To avoid security problems, the generated temporary filename should
- contain enough randomness to prevent an attacker from guessing the
- temporary filename in advance.
-}
-
-PARAGRAPH {
- The xFullPathname method is used to convert a relative pathname
- into a full pathname. The resulting full pathname is written into
- the buffer provided by the third parameter. SQLite will size the
- output buffer to at least mxPathname bytes. Both the input and
- output names should be in UTF-8.
-}
-
-PARAGRAPH {
- The xDlOpen, xDlError, xDlSym, and xDlClose methods are all used for
- accessing shared libraries at run-time. These methods may be omitted
- (and their pointers set to zero) if the library is compiled with
- SQLITE_OMIT_LOAD_EXTENSION or if the [sqlite3_enable_load_extension()]
- interface is never used to enable dynamic extension loading. The
- xDlOpen method opens a shared library or DLL and returns a pointer to
- a handle. NULL is returned if the open fails. If the open fails,
- the xDlError method can be used to obtain a text error message.
- The message is written into the zErrMsg buffer of the third parameter
- which is at least nByte bytes in length. The xDlSym returns a pointer
- to a symbol in the shared library. The name of the symbol is given
- by the second parameter. UTF-8 encoding is assumed. If the symbol
- is not found a NULL pointer is returned. The xDlClose routine closes
- the shared library.
-}
-
-PARAGRAPH {
- The xRandomness method is used exactly once to initialize the
- pseudo-random number generator (PRNG) inside of SQLite. Only
- the xRandomness method on the default VFS is used. The xRandomness
- methods on other VFSes are never accessed by SQLite.
- The xRandomness routine requests that nByte bytes of randomness
- be written into zOut. The routine returns the actual number of
- bytes of randomness obtained. The quality of the randomness so obtained
- will determine the quality of the randomness generated by built-in
- SQLite functions such as random() and randomblob(). SQLite also
- uses its PRNG to generate temporary file names.. On some platforms
- (ex: windows) SQLite assumes that temporary file names are unique
- without actually testing for collisions, so it is important to have
- good-quality randomness even if the random() and randomblob()
- functions are never used.
-}
-
-PARAGRAPH {
- The xSleep method is used to suspend the calling thread for at
- least the number of microseconds given. This method is used to
- implement the [sqlite3_sleep()] and [sqlite3_busy_timeout()] APIs.
- In the case of [sqlite3_sleep()] the xSleep method of the default
- VFS is always used. If the underlying system does not have a
- microsecond resolution sleep capability, then the sleep time should
- be rounded up. xSleep returns this rounded-up value.
-}
-
-PARAGRAPH {
- The xCurrentTime method finds the current time and date and writes
- the result as double-precision floating point value into pointer
- provided by the second parameter. The time and date is in
- coordinated universal time (UTC) and is a fractional julian day number.
-}
-
-HEADING 3 {The Open File Object}
-
-PARAGRAPH {
- The result of opening a file is an instance of an [sqlite3_file] object.
- The [sqlite3_file] object is an abstract base class defined as follows:
-}
-
-CODE {
-typedef struct sqlite3_file sqlite3_file;
-struct sqlite3_file {
- const struct sqlite3_io_methods *pMethods;
-};
-}
-
-PARAGRAPH {
- Each VFS implementation will subclass the [sqlite3_file] by adding
- additional fields at the end to hold whatever information the VFS
- needs to know about an open file. It does not matter what information
- is stored as long as the total size of the structure does not exceed
- the szOsFile value recorded in the [sqlite3_vfs] object.
-}
-
-PARAGRAPH {
- The [sqlite3_io_methods] object is a structure that contains pointers
- to methods for reading, writing, and otherwise dealing with files.
- This object is defined as follows:
-}
-
-CODE {
-typedef struct sqlite3_io_methods sqlite3_io_methods;
-struct sqlite3_io_methods {
- int iVersion;
- int (*xClose)(sqlite3_file*);
- int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
- int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
- int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
- int (*xSync)(sqlite3_file*, int flags);
- int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
- int (*xLock)(sqlite3_file*, int);
- int (*xUnlock)(sqlite3_file*, int);
- int (*xCheckReservedLock)(sqlite3_file*);
- int (*xFileControl)(sqlite3_file*, int op, void *pArg);
- int (*xSectorSize)(sqlite3_file*);
- int (*xDeviceCharacteristics)(sqlite3_file*);
- /* Additional methods may be added in future releases */
-};
-}
-
-PARAGRAPH {
- The iVersion field of [sqlite3_io_methods] is provided as insurance
- against future enhancements. The iVersion value should always be
- 1 for SQLite version 3.5.
-}
-
-PARAGRAPH {
- The xClose method closes the file. The space for the [sqlite3_file]
- structure is deallocated by the caller. But if the [sqlite3_file]
- contains pointers to other allocated memory or resources, those
- allocations should be released by the xClose method.
-}
-
-PARAGRAPH {
- The xRead method reads iAmt bytes from the file beginning at a byte
- offset to iOfst. The data read is stored in the pointer of the
- second parameter. xRead returns the [SQLITE_OK] on success,
- [SQLITE_IOERR_SHORT_READ] if it was not able to read the full number
- of bytes because it reached end-of-file, or [SQLITE_IOERR_READ] for
- any other error.
-}
-
-PARAGRAPH {
- The xWrite method writes iAmt bytes of data from the second parameter
- into the file beginning at an offset of iOfst bytes. If the size of
- the file is less than iOfst bytes prior to the write, then xWrite should
- ensure that the file is extended with zeros up to iOfst bytes prior
- to beginning its write. xWrite continues to extends the file as
- necessary so that the size of the file is at least iAmt+iOfst bytes
- at the conclusion of the xWrite call. The xWrite method returns
- [SQLITE_OK] on success. If the write cannot complete because the
- underlying storage medium is full, then [SQLITE_FULL] is returned.
- [SQLITE_IOERR_WRITE] should be returned for any other error.
-}
-
-PARAGRAPH {
- The xTruncate method truncates a file to be nByte bytes in length.
- If the file is already nByte bytes or less in length then this
- method is a no-op. The xTruncate method returns [SQLITE_OK] on
- success and [SQLITE_IOERR_TRUNCATE] if anything goes wrong.
-}
-
-PARAGRAPH {
- The xSync method is used to force previously written data out of
- operating system cache and into non-volatile memory. The second
- parameter is usually [SQLITE_SYNC_NORMAL]. If the second parameter
- is [SQLITE_SYNC_FULL] then the xSync method should make sure that
- data has also been flushed through the disk controllers cache.
- The [SQLITE_SYNC_FULL] parameter is the equivalent of the F_FULLSYNC
- ioctl() on Mac OS X. The xSync method returns
- [SQLITE_OK] on success and [SQLITE_IOERR_FSYNC] if anything goes wrong.
-}
-
-PARAGRAPH {
- The xFileSize() method determines the current size of the file
- in bytes and writes that value into *pSize. It returns [SQLITE_OK]
- on success and [SQLITE_IOERR_FSTAT] if something goes wrong.
-}
-
-PARAGRAPH {
- The xLock and xUnlock methods are used to set and clear file locks.
- SQLite supports five levels of file locks, in order:
- <ul>
- <li> [SQLITE_LOCK_NONE]
- <li> [SQLITE_LOCK_SHARED]
- <li> [SQLITE_LOCK_RESERVED]
- <li> [SQLITE_LOCK_PENDING]
- <li> [SQLITE_LOCK_EXCLUSIVE]
- </ul>
- The underlying implementation can support some subset of these locking
- levels as long as it meets the other requirements of this paragraph.
- The locking level is specified as the second argument to both xLock
- and xUnlock. The xLock method increases the locking level to the
- specified locking level or higher. The xUnlock method decreases the
- locking level to no lower than the level specified.
- [SQLITE_LOCK_NONE] means that the file is unlocked. [SQLITE_LOCK_SHARED]
- gives permission to read the file. Multiple database connections can
- hold [SQLITE_LOCK_SHARED] at the same time.
- [SQLITE_LOCK_RESERVED] is like [SQLITE_LOCK_SHARED] in that its is permission
- to read the file. But only a single connection can hold a reserved lock
- at any point in time. The [SQLITE_LOCK_PENDING] is also permission to
- read the file. Other connections can continue to read the file as well,
- but no other connection is allowed to escalate a lock from none to shared.
- [SQLITE_LOCK_EXCLUSIVE] is permission to write on the file. Only a single
- connection can hold an exclusive lock and no other connection can hold
- any lock (other than "none") while one connection is hold an exclusive
- lock. The xLock returns [SQLITE_OK] on success, [SQLITE_BUSY] if it
- is unable to obtain the lock, or [SQLITE_IOERR_RDLOCK] if something else
- goes wrong. The xUnlock method returns [SQLITE_OK] on success and
- [SQLITE_IOERR_UNLOCK] for problems.
-}
-
-PARAGRAPH {
- The xCheckReservedLock method checks to see if another connection or
- another process is currently holding a reserved, pending, or exclusive
- lock on the file. It returns true or false.
-}
-
-PARAGRAPH {
- The xFileControl() method is a generic interface that allows custom
- VFS implementations to directly control an open file using the
- (new and experimental)
- [sqlite3_file_control()] interface. The second "op" argument
- is an integer opcode. The third
- argument is a generic pointer which is intended to be a pointer
- to a structure that may contain arguments or space in which to
- write return values. Potential uses for xFileControl() might be
- functions to enable blocking locks with timeouts, to change the
- locking strategy (for example to use dot-file locks), to inquire
- about the status of a lock, or to break stale locks. The SQLite
- core reserves opcodes less than 100 for its own use.
- A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
- Applications that define a custom xFileControl method should use opcodes
- greater than 100 to avoid conflicts.
-}
-
-PARAGRAPH {
- The xSectorSize returns the "sector size" of the underlying
- non-volatile media. A "sector" is defined as the smallest unit of
- storage that can be written without disturbing adjacent storage.
- On a disk drive the "sector size" has until recently been 512 bytes,
- though there is a push to increase this value to 4KiB. SQLite needs
- to know the sector size so that it can write a full sector at a
- time, and thus avoid corrupting adjacent storage space if a power
- lose occurs in the middle of a write.
-}
-
-PARAGRAPH {
- The xDeviceCharacteristics method returns an integer bit vector that
- defines any special properties that the underlying storage medium might
- have that SQLite can use to increase performance. The allowed return
- is the bit-wise OR of the following values:
- <ul>
- <li> [SQLITE_IOCAP_ATOMIC]
- <li> [SQLITE_IOCAP_ATOMIC512]
- <li> [SQLITE_IOCAP_ATOMIC1K]
- <li> [SQLITE_IOCAP_ATOMIC2K]
- <li> [SQLITE_IOCAP_ATOMIC4K]
- <li> [SQLITE_IOCAP_ATOMIC8K]
- <li> [SQLITE_IOCAP_ATOMIC16K]
- <li> [SQLITE_IOCAP_ATOMIC32K]
- <li> [SQLITE_IOCAP_ATOMIC64K]
- <li> [SQLITE_IOCAP_SAFE_APPEND]
- <li> [SQLITE_IOCAP_SEQUENTIAL]
- </ul>
- The [SQLITE_IOCAP_ATOMIC] bit means that all writes to this device are
- atomic in the sense that either the entire write occurs or none of it
- occurs. The other
- [SQLITE_IOCAP_ATOMIC | SQLITE_IOCAP_ATOMIC<i>nnn</i>] values indicate that
- writes of aligned blocks of the indicated size are atomic.
- [SQLITE_IOCAP_SAFE_APPEND] means that when extending a file with new
- data, the new data is written first and then the file size is updated.
- So if a power failure occurs, there is no chance that the file might have
- been extended with randomness. The [SQLITE_IOCAP_SEQUENTIAL] bit means
- that all writes occur in the order that they are issued and are not
- reordered by the underlying file system.
-}
-
-HEADING 3 {Checklist For Constructing A New VFS}
-
-PARAGRAPH {
- The preceding paragraphs contain a lot of information.
- To ease the task of constructing
- a new VFS for SQLite we offer the following implementation checklist:
-}
-
-PARAGRAPH {
- <ol>
- <li> Define an appropriate subclass of the [sqlite3_file] object.
- <li> Implement the methods required by the [sqlite3_io_methods] object.
- <li> Create a static and
- constant [sqlite3_io_methods] object containing pointers
- to the methods from the previous step.
- <li> Implement the xOpen method that opens a file and populates an
- [sqlite3_file] object, including setting pMethods to
- point to the [sqlite3_io_methods] object from the previous step.
- <li> Implement the other methods required by [sqlite3_vfs].
- <li> Define a static (but not constant) [sqlite3_vfs] structure that
- contains pointers to the xOpen method and the other methods and
- which contains the appropriate values for iVersion, szOsFile,
- mxPathname, zName, and pAppData.
- <li> Implement a procedure that calls [sqlite3_vfs_register()] and
- passes it a pointer to the [sqlite3_vfs] structure from the previous
- step. This procedure is probably the only exported symbol in the
- source file that implements your VFS.
- </ol>
-}
-
-PARAGRAPH {
- Within your application, call the procedure implemented in the last
- step above as part of your initialization process before any
- database connections are opened.
-}
-
-HEADING 1 {The Memory Allocation Subsystem}
-
-PARAGRAPH {
- Beginning with version 3.5, SQLite obtains all of the heap memory it
- needs using the routines [sqlite3_malloc()], [sqlite3_free()], and
- [sqlite3_realloc()]. These routines have existed in prior versions
- of SQLite, but SQLite has previously bypassed these routines and used
- its own memory allocator. This all changes in version 3.5.0.
-}
-
-PARAGRAPH {
- The SQLite source tree actually contains multiple versions of the
- memory allocator. The default high-speed version found in the
- "mem1.c" source file is used for most builds. But if the SQLITE_MEMDEBUG
- flag is enabled, a separate memory allocator the "mem2.c" source file
- is used instead. The mem2.c allocator implements lots of hooks to
- do error checking and to simulate memory allocation failures for testing
- purposes. Both of these allocators use the malloc()/free() implementation
- in the standard C library.
-}
-
-PARAGRAPH {
- Applications are not required to use either of these standard memory
- allocators. If SQLite is compiled with SQLITE_OMIT_MEMORY_ALLOCATION
- then no implementation for the [sqlite3_malloc()], [sqlite3_realloc()],
- and [sqlite3_free()] functions is provided. Instead, the application
- that links against SQLite must provide its own implementation of these
- functions. The application provided memory allocator is not required
- to use the malloc()/free() implementation in the standard C library.
- An embedded application might provide an alternative memory allocator
- that uses memory for a fixed memory pool set aside for the exclusive
- use of SQLite, for example.
-}
-
-PARAGRAPH {
- Applications that implement their own memory allocator must provide
- implementation for the usual three allocation functions
- [sqlite3_malloc()], [sqlite3_realloc()], and [sqlite3_free()].
- And they must also implement a fourth function:
-}
-
-CODE {
-int sqlite3_memory_alarm(
- void(*xCallback)(void *pArg, sqlite3_int64 used, int N),
- void *pArg,
- sqlite3_int64 iThreshold
-);
-}
-
-PARAGRAPH {
- The [sqlite3_memory_alarm] routine is used to register
- a callback on memory allocation events.
- This routine registers or clears a callbacks that fires when
- the amount of memory allocated exceeds iThreshold. Only
- a single callback can be registered at a time. Each call
- to [sqlite3_memory_alarm()] overwrites the previous callback.
- The callback is disabled by setting xCallback to a NULL
- pointer.
-}
-
-PARAGRAPH {
- The parameters to the callback are the pArg value, the
- amount of memory currently in use, and the size of the
- allocation that provoked the callback. The callback will
- presumably invoke [sqlite3_free()] to free up memory space.
- The callback may invoke [sqlite3_malloc()] or [sqlite3_realloc()]
- but if it does, no additional callbacks will be invoked by
- the recursive calls.
-}
-
-PARAGRAPH {
- The [sqlite3_soft_heap_limit()] interface works by registering
- a memory alarm at the soft heap limit and invoking
- [sqlite3_release_memory()] in the alarm callback. Application
- programs should not attempt to use the [sqlite3_memory_alarm()]
- interface because doing so will interfere with the
- [sqlite3_soft_heap_limit()] module. This interface is exposed
- only so that applications can provide their own
- alternative implementation when the SQLite core is
- compiled with SQLITE_OMIT_MEMORY_ALLOCATION.
-}
-
-PARAGRAPH {
- The built-in memory allocators in SQLite also provide the following
- additional interfaces:
-}
-
-CODE {
-sqlite3_int64 sqlite3_memory_used(void);
-sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
-}
-
-PARAGRAPH {
- These interfaces can be used by an application to monitor how
- much memory SQLite is using. The [sqlite3_memory_used()] routine
- returns the number of bytes of memory currently in use and the
- [sqlite3_memory_highwater()] returns the maximum instantaneous
- memory usage. Neither routine includes the overhead associated
- with the memory allocator. These routines are provided for use
- by the application. SQLite never invokes them itself. So if
- the application is providing its own memory allocation subsystem,
- it can omit these interfaces if desired.
-}
-
-HEADING 1 {The Mutex Subsystem}
-
-PARAGRAPH {
- SQLite has always been threadsafe in the sense that it is safe to
- use different SQLite database connections in different threads at the
- same time. The constraint was that the same database connection
- could not be used in two separate threads at once. SQLite version 3.5.0
- relaxes this constraint.
-}
-
-PARAGRAPH {
- In order to allow multiple threads to use the same database connection
- at the same time, SQLite must make extensive use of mutexes. And for
- this reason a new mutex subsystem as been added. The mutex subsystem
- as the following interface:
-}
-
-CODE {
-sqlite3_mutex *sqlite3_mutex_alloc(int);
-void sqlite3_mutex_free(sqlite3_mutex*);
-void sqlite3_mutex_enter(sqlite3_mutex*);
-int sqlite3_mutex_try(sqlite3_mutex*);
-void sqlite3_mutex_leave(sqlite3_mutex*);
-}
-
-PARAGRAPH {
- Though these routines exist for the use of the SQLite core,
- application code is free to use these routines as well, if desired.
- A mutex is an [sqlite3_mutex] object. The [sqlite3_mutex_alloc()]
- routine allocates a new mutex object and returns a pointer to it.
- The argument to [sqlite3_mutex_alloc()] should be
- [SQLITE_MUTEX_FAST] or [SQLITE_MUTEX_RECURSIVE] for non-recursive
- and recursive mutexes, respectively. If the underlying system does
- not provide non-recursive mutexes, then a recursive mutex can be
- substituted in that case. The argument to [sqlite3_mutex_alloc()]
- can also be a constant designating one of several static mutexes:
- <ul>
- <li> [SQLITE_MUTEX_STATIC_MASTER]
- <li> [SQLITE_MUTEX_STATIC_MEM]
- <li> [SQLITE_MUTEX_STATIC_MEM2]
- <li> [SQLITE_MUTEX_STATIC_PRNG]
- <li> [SQLITE_MUTEX_STATIC_LRU]
- </ul>
- These static mutexes are reserved for use internally by SQLite
- and should not be used by the application. The static mutexes
- are all non-recursive.
-}
-
-PARAGRAPH {
- The [sqlite3_mutex_free()] routine should be used to deallocate
- a non-static mutex. If a static mutex is passed to this routine
- then the behavior is undefined.
-}
-
-PARAGRAPH {
- The [sqlite3_mutex_enter()] attempts to enter the mutex and blocks
- if another threads is already there. [sqlite3_mutex_try()] attempts
- to enter and returns [SQLITE_OK] on success or [SQLITE_BUSY] if another
- thread is already there. [sqlite3_mutex_leave()] exits a mutex.
- The mutex is held until the number of exits matches the number of
- entrances. If [sqlite3_mutex_leave()] is called on a mutex that
- the thread is not currently holding, then the behavior is undefined.
- If any routine is called for a deallocated mutex, then the behavior
- is undefined.
-}
-
-PARAGRAPH {
- The SQLite source code provides multiple implementations of these
- APIs, suitable for varying environments. If SQLite is compiled with
- the SQLITE_THREADSAFE=0 flag then a no-op mutex implementation that
- is fast but does no real mutual exclusion is provided. That
- implementation is suitable for use in single-threaded applications
- or applications that only use SQLite in a single thread. Other
- real mutex implementations are provided based on the underlying
- operating system.
-}
-
-PARAGRAPH {
- Embedded applications may wish to provide their own mutex implementation.
- If SQLite is compiled with the -DSQLITE_MUTEX_APPDEF=1 compile-time flag
- then the SQLite core provides no mutex subsystem and a mutex subsystem
- that matches the interface described above must be provided by the
- application that links against SQLite.
-}
-
-HEADING 1 {Other Interface Changes}
-
-PARAGRAPH {
- Version 3.5.0 of SQLite changes the behavior of a few APIs in ways
- that are technically incompatible. However, these APIs are seldom
- used and even when they are used it is difficult to imagine a
- scenario where the change might break something. The changes
- actually makes these interface much more useful and powerful.
-}
-
-PARAGRAPH {
- Prior to version 3.5.0, the [sqlite3_enable_shared_cache()] API
- would enable and disable the shared cache feature for all connections
- within a single thread - the same thread from which the
- sqlite3_enable_shared_cache() routine was called. Database connections
- that used the shared cache were restricted to running in the same
- thread in which they were opened. Beginning with version 3.5.0,
- the sqlite3_enable_shared_cache() applies to all database connections
- in all threads within the process. Now database connections running
- in separate threads can share a cache. And database connections that
- use shared cache can migrate from one thread to another.
-}
-
-PARAGRAPH {
- Prior to version 3.5.0 the [sqlite3_soft_heap_limit()] set an upper
- bound on heap memory usage for all database connections within a
- single thread. Each thread could have its own heap limit. Beginning
- in version 3.5.0, there is a single heap limit for the entire process.
- This seems more restrictive (one limit as opposed to many) but in
- practice it is what most users want.
-}
-
-PARAGRAPH {
- Prior to version 3.5.0 the [sqlite3_release_memory()] function would
- try to reclaim memory from all database connections in the same thread
- as the sqlite3_release_memory() call. Beginning with version 3.5.0,
- the sqlite3_release_memory() function will attempt to reclaim memory
- from all database connections in all threads.
-}
-
-HEADING 1 {Summary}
-
-PARAGRAPH {
- The transition from SQLite version 3.4.2 to 3.5.0 is a major change.
- Every source code file in the SQLite core had to be modified, some
- extensively. And the change introduced some minor incompatibilities
- in the C interface. But we feel that the benefits of the transition
- from 3.4.2 to 3.5.0 far outweigh the pain of porting. The new
- VFS layer is now well-defined and stable and should simplify future
- customizations. The VFS layer, and the separable memory allocator
- and mutex subsystems allow a standard SQLite source code amalgamation
- to be used in an embedded project without change, greatly simplifying
- configuration management. And the resulting system is much more
- tolerant of highly threaded designs.
-}
+++ /dev/null
-#FIG 3.2
-Portrait
-Center
-Inches
-Letter
-100.00
-Single
--2
-1200 2
-2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
- 1 1 3.00 75.00 135.00
- 3675 8550 3675 9075
-2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
- 1 1 3.00 75.00 135.00
- 3675 7200 3675 7725
-2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
- 1 1 3.00 75.00 135.00
- 3675 5775 3675 6300
-2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
- 1 1 3.00 75.00 135.00
- 3675 3975 3675 4500
-2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
- 1 1 3.00 75.00 135.00
- 3675 2625 3675 3150
-2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
- 1 1 3.00 75.00 135.00
- 3675 1275 3675 1800
-2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
- 1 1 3.00 75.00 135.00
- 3675 9900 3675 10425
-2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
- 2550 10425 4875 10425 4875 11250 2550 11250 2550 10425
-2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
- 2550 9075 4875 9075 4875 9900 2550 9900 2550 9075
-2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
- 2550 7725 4875 7725 4875 8550 2550 8550 2550 7725
-2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
- 2550 6300 4875 6300 4875 7200 2550 7200 2550 6300
-2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
- 2550 4500 4875 4500 4875 5775 2550 5775 2550 4500
-2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
- 2550 3150 4875 3150 4875 3975 2550 3975 2550 3150
-2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
- 2550 1800 4875 1800 4875 2625 2550 2625 2550 1800
-2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
- 2550 450 4875 450 4875 1275 2550 1275 2550 450
-4 1 0 100 0 0 20 0.0000 4 195 1020 3675 750 Interface\001
-4 1 0 100 0 0 14 0.0000 4 195 2040 3675 1125 main.c table.c tclsqlite.c\001
-4 1 0 100 0 0 20 0.0000 4 195 1920 3675 6675 Virtual Machine\001
-4 1 0 100 0 0 14 0.0000 4 150 570 3675 7050 vdbe.c\001
-4 1 0 100 0 0 20 0.0000 4 195 1830 3675 4875 Code Generator\001
-4 1 0 100 0 0 14 0.0000 4 195 1860 3675 5175 build.c delete.c expr.c\001
-4 1 0 100 0 0 14 0.0000 4 195 2115 3675 5400 insert.c select.c update.c\001
-4 1 0 100 0 0 14 0.0000 4 150 705 3675 5625 where.c\001
-4 1 0 100 0 0 20 0.0000 4 195 735 3675 3450 Parser\001
-4 1 0 100 0 0 20 0.0000 4 195 1140 3675 2100 Tokenizer\001
-4 1 0 100 0 0 14 0.0000 4 150 870 3675 2475 tokenize.c\001
-4 1 0 100 0 0 20 0.0000 4 255 1350 3675 9375 Page Cache\001
-4 1 0 100 0 0 14 0.0000 4 150 630 3675 3825 parse.y\001
-4 1 0 100 0 0 14 0.0000 4 150 600 3675 8400 btree.c\001
-4 1 0 100 0 0 14 0.0000 4 150 645 3675 9750 pager.c\001
-4 1 0 100 0 0 20 0.0000 4 195 1620 3675 8025 B-tree Driver\001
-4 1 0 100 0 0 14 0.0000 4 105 345 3675 11100 os.c\001
-4 1 0 100 0 0 20 0.0000 4 195 1470 3675 10725 OS Interface\001
+++ /dev/null
-#
-# Run this Tcl script to generate the sqlite.html file.
-#
-set rcsid {$Id: arch.tcl,v 1.16 2004/10/10 17:24:54 drh Exp $}
-source common.tcl
-header {Architecture of SQLite}
-puts {
-<h2>The Architecture Of SQLite</h2>
-
-<h3>Introduction</h3>
-
-<table align="right" border="1" cellpadding="15" cellspacing="1">
-<tr><th>Block Diagram Of SQLite</th></tr>
-<tr><td><img src="arch2.gif"></td></tr>
-</table>
-<p>This document describes the architecture of the SQLite library.
-The information here is useful to those who want to understand or
-modify the inner workings of SQLite.
-</p>
-
-<p>
-A block diagram showing the main components of SQLite
-and how they interrelate is shown at the right. The text that
-follows will provide a quick overview of each of these components.
-</p>
-
-
-<p>
-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>, <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>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="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>sqlite3</b>.
-Those symbols that are intended for external use (in other words,
-those symbols which form the API for SQLite) begin
-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 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
-other way around -- having the parser call the tokenizer. The author
-of SQLite
-has done it both ways and finds things generally work out nicer for
-the tokenizer to call the parser. YACC has it backwards.</p>
-
-<h3>Parser</h3>
-
-<p>The parser is the piece that assigns meaning to tokens based on
-their context. The parser for SQLite is generated using the
-<a href="http://www.hwaci.com/sw/lemon/">Lemon</a> LALR(1) parser
-generator. Lemon does the same job as YACC/BISON, but it uses
-a different input syntax which is less error-prone.
-Lemon also generates a parser which is reentrant and thread-safe.
-And lemon defines the concept of a non-terminal destructor so
-that it does not leak memory when syntax errors are encountered.
-The source file that drives Lemon is found in <b>parse.y</b>.</p>
-
-<p>Because
-lemon is a program not normally found on development machines, the
-complete source code to lemon (just one C file) is included in the
-SQLite distribution in the "tool" subdirectory. Documentation on
-lemon is found in the "doc" subdirectory of the distribution.
-</p>
-
-<h3>Code Generator</h3>
-
-<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>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>
-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>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>.
-The <b>auth.c</b> file implements the functionality of
-<b>sqlite3_set_authorizer()</b>.</p>
-
-<h3>Virtual Machine</h3>
-
-<p>The program generated by the code generator is executed by
-the virtual machine. Additional information about the virtual
-machine is <a href="opcode.html">available separately</a>.
-To summarize, the virtual machine implements an abstract computing
-engine specifically designed to manipulate database files. The
-machine has a stack which is used for intermediate storage.
-Each instruction contains an opcode and
-up to three additional operands.</p>
-
-<p>The virtual machine itself is entirely contained in a single
-source file <b>vdbe.c</b>. The virtual machine also has
-its own header files: <b>vdbe.h</b> that defines an interface
-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. 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. 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>.
-</p>
-
-<h3>Page Cache</h3>
-
-<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 responsible for reading, writing, and
-caching these chunks.
-The page cache also provides the rollback and atomic commit abstraction
-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
-the requests are handled quickly, safely, and efficiently.</p>
-
-<p>The code to implement the page cache is contained in the single C
-source file <b>pager.c</b>. The interface to the page cache subsystem
-is defined by the header file <b>pager.h</b>.
-</p>
-
-<h3>OS Interface</h3>
-
-<p>
-In order to provide portability between POSIX and Win32 operating systems,
-SQLite uses an abstraction layer to interface with the operating system.
-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
+++ /dev/null
-#FIG 3.2
-Landscape
-Center
-Inches
-Letter
-100.00
-Single
--2
-1200 2
-0 32 #000000
-0 33 #868686
-0 34 #dfefd7
-0 35 #d7efef
-0 36 #efdbef
-0 37 #efdbd7
-0 38 #e7efcf
-0 39 #9e9e9e
-6 3225 3900 4650 6000
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 3225 5475 4575 5475 4575 5925 3225 5925 3225 5475
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 3300 5550 4650 5550 4650 6000 3300 6000 3300 5550
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 3225 4650 4575 4650 4575 5100 3225 5100 3225 4650
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 3300 4725 4650 4725 4650 5175 3300 5175 3300 4725
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 3225 3900 4575 3900 4575 4350 3225 4350 3225 3900
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 3300 3975 4650 3975 4650 4425 3300 4425 3300 3975
-2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
- 1 1 1.00 60.00 120.00
- 3900 4350 3900 4650
-2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
- 1 1 1.00 60.00 120.00
- 3900 5100 3900 5475
-4 1 0 50 0 2 12 0.0000 4 135 1050 3900 5775 OS Interface\001
-4 1 0 50 0 2 12 0.0000 4 135 615 3900 4200 B-Tree\001
-4 1 0 50 0 2 12 0.0000 4 180 495 3900 4950 Pager\001
--6
-6 5400 4725 6825 5250
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 5400 4725 6750 4725 6750 5175 5400 5175 5400 4725
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 5475 4800 6825 4800 6825 5250 5475 5250 5475 4800
-4 1 0 50 0 2 12 0.0000 4 135 630 6000 5025 Utilities\001
--6
-6 5400 5550 6825 6075
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 5400 5550 6750 5550 6750 6000 5400 6000 5400 5550
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 5475 5625 6825 5625 6825 6075 5475 6075 5475 5625
-4 1 0 50 0 2 12 0.0000 4 135 855 6000 5850 Test Code\001
--6
-6 5400 2775 6825 3750
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 5475 2850 6825 2850 6825 3750 5475 3750 5475 2850
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 5400 2775 6750 2775 6750 3675 5400 3675 5400 2775
-4 1 0 50 0 2 12 0.0000 4 135 420 6075 3150 Code\001
-4 1 0 50 0 2 12 0.0000 4 135 855 6075 3375 Generator\001
--6
-6 5400 1950 6825 2475
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 5400 1950 6750 1950 6750 2400 5400 2400 5400 1950
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 5475 2025 6825 2025 6825 2475 5475 2475 5475 2025
-4 1 0 50 0 2 12 0.0000 4 135 570 6075 2250 Parser\001
--6
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 5400 1050 6750 1050 6750 1500 5400 1500 5400 1050
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 5475 1125 6825 1125 6825 1575 5475 1575 5475 1125
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 3225 1050 4575 1050 4575 1500 3225 1500 3225 1050
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 3300 1125 4650 1125 4650 1575 3300 1575 3300 1125
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 3225 1800 4575 1800 4575 2250 3225 2250 3225 1800
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 3300 1875 4650 1875 4650 2325 3300 2325 3300 1875
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 3225 2550 4575 2550 4575 3000 3225 3000 3225 2550
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 3300 2625 4650 2625 4650 3075 3300 3075 3300 2625
-2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
- 1 1 1.00 60.00 120.00
- 3900 1500 3900 1800
-2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
- 1 1 1.00 60.00 120.00
- 3900 2250 3900 2550
-2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
- 1 1 1.00 60.00 120.00
- 3900 3000 3900 3900
-2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
- 1 1 1.00 60.00 120.00
- 4575 1950 5400 1350
-2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
- 1 1 1.00 60.00 120.00
- 5400 2925 4650 2325
-2 2 0 1 0 34 55 0 20 0.000 0 0 -1 0 0 5
- 2850 750 4875 750 4875 3375 2850 3375 2850 750
-2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
- 1 1 1.00 60.00 120.00
- 6075 1500 6075 1950
-2 3 0 1 0 35 55 0 20 0.000 0 0 -1 0 0 5
- 2850 3675 4875 3675 4875 6225 2850 6225 2850 3675
-2 2 0 1 0 37 55 0 20 0.000 0 0 -1 0 0 5
- 5175 750 7200 750 7200 4050 5175 4050 5175 750
-2 2 0 1 0 38 55 0 20 0.000 0 0 -1 0 0 5
- 5175 4425 7200 4425 7200 6225 5175 6225 5175 4425
-2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
- 1 1 1.00 60.00 120.00
- 6075 2475 6075 2775
-4 1 0 50 0 2 12 0.0000 4 135 855 6075 1350 Tokenizer\001
-4 1 0 50 0 1 12 1.5708 4 180 1020 7125 2250 SQL Compiler\001
-4 1 0 50 0 1 12 1.5708 4 135 345 3075 2025 Core\001
-4 1 0 50 0 2 12 0.0000 4 135 1290 3900 2850 Virtual Machine\001
-4 1 0 50 0 2 12 0.0000 4 165 1185 3900 1995 SQL Command\001
-4 1 0 50 0 2 12 0.0000 4 135 855 3900 2183 Processor\001
-4 1 0 50 0 2 14 0.0000 4 150 870 3900 1350 Interface\001
-4 1 0 50 0 1 12 1.5708 4 135 885 7125 5400 Accessories\001
-4 1 0 50 0 1 12 1.5708 4 135 645 3075 4875 Backend\001
+++ /dev/null
-#FIG 3.2
-Landscape
-Center
-Inches
-Letter
-100.00
-Single
--2
-1200 2
-0 32 #000000
-0 33 #868686
-0 34 #dfefd7
-0 35 #d7efef
-0 36 #efdbef
-0 37 #efdbd7
-0 38 #e7efcf
-0 39 #9e9e9e
-6 3225 3900 4650 6000
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 3225 5475 4575 5475 4575 5925 3225 5925 3225 5475
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 3300 5550 4650 5550 4650 6000 3300 6000 3300 5550
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 3225 4650 4575 4650 4575 5100 3225 5100 3225 4650
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 3300 4725 4650 4725 4650 5175 3300 5175 3300 4725
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 3225 3900 4575 3900 4575 4350 3225 4350 3225 3900
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 3300 3975 4650 3975 4650 4425 3300 4425 3300 3975
-2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
- 1 1 1.00 60.00 120.00
- 3900 4350 3900 4650
-2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
- 1 1 1.00 60.00 120.00
- 3900 5100 3900 5475
-4 1 0 50 0 2 12 0.0000 4 135 1050 3900 5775 OS Interface\001
-4 1 0 50 0 2 12 0.0000 4 135 615 3900 4200 B-Tree\001
-4 1 0 50 0 2 12 0.0000 4 180 495 3900 4950 Pager\001
--6
-6 5175 4275 7200 6150
-6 5400 4519 6825 5090
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 5400 4519 6750 4519 6750 5009 5400 5009 5400 4519
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 5475 4601 6825 4601 6825 5090 5475 5090 5475 4601
-4 1 0 50 0 2 12 0.0000 4 135 630 6000 4845 Utilities\001
--6
-6 5400 5416 6825 5987
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 5400 5416 6750 5416 6750 5906 5400 5906 5400 5416
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 5475 5498 6825 5498 6825 5987 5475 5987 5475 5498
-4 1 0 50 0 2 12 0.0000 4 135 855 6000 5742 Test Code\001
--6
-2 2 0 1 0 38 55 0 20 0.000 0 0 -1 0 0 5
- 5175 4275 7200 4275 7200 6150 5175 6150 5175 4275
-4 1 0 50 0 1 12 1.5708 4 135 885 7125 5253 Accessories\001
--6
-6 5400 2700 6825 3675
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 5475 2775 6825 2775 6825 3675 5475 3675 5475 2775
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 5400 2700 6750 2700 6750 3600 5400 3600 5400 2700
-4 1 0 50 0 2 12 0.0000 4 135 420 6075 3075 Code\001
-4 1 0 50 0 2 12 0.0000 4 135 855 6075 3300 Generator\001
--6
-6 5400 1875 6825 2400
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 5400 1875 6750 1875 6750 2325 5400 2325 5400 1875
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 5475 1950 6825 1950 6825 2400 5475 2400 5475 1950
-4 1 0 50 0 2 12 0.0000 4 135 570 6075 2175 Parser\001
--6
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 5400 1050 6750 1050 6750 1500 5400 1500 5400 1050
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 5475 1125 6825 1125 6825 1575 5475 1575 5475 1125
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 3225 1050 4575 1050 4575 1500 3225 1500 3225 1050
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 3300 1125 4650 1125 4650 1575 3300 1575 3300 1125
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 3225 1800 4575 1800 4575 2250 3225 2250 3225 1800
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 3300 1875 4650 1875 4650 2325 3300 2325 3300 1875
-2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
- 3225 2550 4575 2550 4575 3000 3225 3000 3225 2550
-2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
- 3300 2625 4650 2625 4650 3075 3300 3075 3300 2625
-2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
- 1 1 1.00 60.00 120.00
- 3900 1500 3900 1800
-2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
- 1 1 1.00 60.00 120.00
- 3900 2250 3900 2550
-2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
- 1 1 1.00 60.00 120.00
- 3900 3000 3900 3900
-2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
- 1 1 1.00 60.00 120.00
- 4575 1950 5400 1350
-2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
- 1 1 1.00 60.00 120.00
- 5400 2925 4650 2175
-2 2 0 1 0 34 55 0 20 0.000 0 0 -1 0 0 5
- 2850 750 4875 750 4875 3375 2850 3375 2850 750
-2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
- 1 1 1.00 60.00 120.00
- 6075 1500 6075 1800
-2 3 0 1 0 35 55 0 20 0.000 0 0 -1 0 0 5
- 2850 3675 4875 3675 4875 6150 2850 6150 2850 3675
-2 2 0 1 0 37 55 0 20 0.000 0 0 -1 0 0 5
- 5175 750 7200 750 7200 3975 5175 3975 5175 750
-2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
- 1 1 1.00 60.00 120.00
- 6075 2400 6075 2700
-4 1 0 50 0 2 12 0.0000 4 135 855 6075 1350 Tokenizer\001
-4 1 0 50 0 1 12 1.5708 4 180 1020 7125 2250 SQL Compiler\001
-4 1 0 50 0 1 12 1.5708 4 135 345 3075 2025 Core\001
-4 1 0 50 0 2 12 0.0000 4 135 1290 3900 2850 Virtual Machine\001
-4 1 0 50 0 2 12 0.0000 4 165 1185 3900 1995 SQL Command\001
-4 1 0 50 0 2 12 0.0000 4 135 855 3900 2183 Processor\001
-4 1 0 50 0 2 14 0.0000 4 150 870 3900 1350 Interface\001
-4 1 0 50 0 1 12 1.5708 4 135 645 3075 4875 Backend\001
+++ /dev/null
-#
-# Run this Tcl script to generate the audit.html file.
-#
-set rcsid {$Id: audit.tcl,v 1.1 2002/07/13 16:52:35 drh Exp $}
-
-puts {<html>
-<head>
- <title>SQLite Security Audit Procedure</title>
-</head>
-<body bgcolor=white>
-<h1 align=center>
-SQLite Security Audit Procedure
-</h1>}
-puts "<p align=center>
-(This page was last modified on [lrange $rcsid 3 4] UTC)
-</p>"
-
-puts {
-<p>
-A security audit for SQLite consists of two components. First, there is
-a check for common errors that often lead to security problems. Second,
-an attempt is made to construct a proof that SQLite has certain desirable
-security properties.
-</p>
-
-<h2>Part I: Things to check</h2>
-
-<p>
-Scan all source code and check for the following common errors:
-</p>
-
-<ol>
-<li><p>
-Verify that the destination buffer is large enough to hold its result
-in every call to the following routines:
-<ul>
-<li> <b>strcpy()</b> </li>
-<li> <b>strncpy()</b> </li>
-<li> <b>strcat()</b> </li>
-<li> <b>memcpy()</b> </li>
-<li> <b>memset()</b> </li>
-<li> <b>memmove()</b> </li>
-<li> <b>bcopy()</b> </li>
-<li> <b>sprintf()</b> </li>
-<li> <b>scanf()</b> </li>
-</ul>
-</p></li>
-<li><p>
-Verify that pointers returned by subroutines are not NULL before using
-the pointers. In particular, make sure the return values for the following
-routines are checked before they are used:
-<ul>
-<li> <b>malloc()</b> </li>
-<li> <b>realloc()</b> </li>
-<li> <b>sqliteMalloc()</b> </li>
-<li> <b>sqliteRealloc()</b> </li>
-<li> <b>sqliteStrDup()</b> </li>
-<li> <b>sqliteStrNDup()</b> </li>
-<li> <b>sqliteExpr()</b> </li>
-<li> <b>sqliteExprFunction()</b> </li>
-<li> <b>sqliteExprListAppend()</b> </li>
-<li> <b>sqliteResultSetOfSelect()</b> </li>
-<li> <b>sqliteIdListAppend()</b> </li>
-<li> <b>sqliteSrcListAppend()</b> </li>
-<li> <b>sqliteSelectNew()</b> </li>
-<li> <b>sqliteTableNameToTable()</b> </li>
-<li> <b>sqliteTableTokenToSrcList()</b> </li>
-<li> <b>sqliteWhereBegin()</b> </li>
-<li> <b>sqliteFindTable()</b> </li>
-<li> <b>sqliteFindIndex()</b> </li>
-<li> <b>sqliteTableNameFromToken()</b> </li>
-<li> <b>sqliteGetVdbe()</b> </li>
-<li> <b>sqlite_mprintf()</b> </li>
-<li> <b>sqliteExprDup()</b> </li>
-<li> <b>sqliteExprListDup()</b> </li>
-<li> <b>sqliteSrcListDup()</b> </li>
-<li> <b>sqliteIdListDup()</b> </li>
-<li> <b>sqliteSelectDup()</b> </li>
-<li> <b>sqliteFindFunction()</b> </li>
-<li> <b>sqliteTriggerSelectStep()</b> </li>
-<li> <b>sqliteTriggerInsertStep()</b> </li>
-<li> <b>sqliteTriggerUpdateStep()</b> </li>
-<li> <b>sqliteTriggerDeleteStep()</b> </li>
-</ul>
-</p></li>
-<li><p>
-On all functions and procedures, verify that pointer parameters are not NULL
-before dereferencing those parameters.
-</p></li>
-<li><p>
-Check to make sure that temporary files are opened safely: that the process
-will not overwrite an existing file when opening the temp file and that
-another process is unable to substitute a file for the temp file being
-opened.
-</p></li>
-</ol>
-
-
-
-<h2>Part II: Things to prove</h2>
-
-<p>
-Prove that SQLite exhibits the characteristics outlined below:
-</p>
-
-<ol>
-<li><p>
-The following are preconditions:</p>
-<p><ul>
-<li><b>Z</b> is an arbitrary-length NUL-terminated string.</li>
-<li>An existing SQLite database has been opened. The return value
- from the call to <b>sqlite_open()</b> is stored in the variable
- <b>db</b>.</li>
-<li>The database contains at least one table of the form:
-<blockquote><pre>
-CREATE TABLE t1(a CLOB);
-</pre></blockquote></li>
-<li>There are no user-defined functions other than the standard
- build-in functions.</li>
-</ul></p>
-<p>The following statement of C code is executed:</p>
-<blockquote><pre>
-sqlite_exec_printf(
- db,
- "INSERT INTO t1(a) VALUES('%q');",
- 0, 0, 0, Z
-);
-</pre></blockquote>
-<p>Prove the following are true for all possible values of string <b>Z</b>:</p>
-<ol type="a">
-<li><p>
-The call to <b>sqlite_exec_printf()</b> will
-return in a length of time that is a polynomial in <b>strlen(Z)</b>.
-It might return an error code but it will not crash.
-</p></li>
-<li><p>
-At most one new row will be inserted into table t1.
-</p></li>
-<li><p>
-No preexisting rows of t1 will be deleted or modified.
-</p></li>
-<li><p>
-No tables other than t1 will be altered in any way.
-</p></li>
-<li><p>
-No preexisting files on the host computers filesystem, other than
-the database file itself, will be deleted or modified.
-</p></li>
-<li><p>
-For some constants <b>K1</b> and <b>K2</b>,
-if at least <b>K1*strlen(Z) + K2</b> bytes of contiguous memory are
-available to <b>malloc()</b>, then the call to <b>sqlite_exec_printf()</b>
-will not return SQLITE_NOMEM.
-</p></li>
-</ol>
-</p></li>
-
-
-<li><p>
-The following are preconditions:
-<p><ul>
-<li><b>Z</b> is an arbitrary-length NUL-terminated string.</li>
-<li>An existing SQLite database has been opened. The return value
- from the call to <b>sqlite_open()</b> is stored in the variable
- <b>db</b>.</li>
-<li>There exists a callback function <b>cb()</b> that appends all
- information passed in through its parameters into a single
- data buffer called <b>Y</b>.</li>
-<li>There are no user-defined functions other than the standard
- build-in functions.</li>
-</ul></p>
-<p>The following statement of C code is executed:</p>
-<blockquote><pre>
-sqlite_exec(db, Z, cb, 0, 0);
-</pre></blockquote>
-<p>Prove the following are true for all possible values of string <b>Z</b>:</p>
-<ol type="a">
-<li><p>
-The call to <b>sqlite_exec()</b> will
-return in a length of time which is a polynomial in <b>strlen(Z)</b>.
-It might return an error code but it will not crash.
-</p></li>
-<li><p>
-After <b>sqlite_exec()</b> returns, the buffer <b>Y</b> will not contain
-any content from any preexisting file on the host computers file system,
-except for the database file.
-</p></li>
-<li><p>
-After the call to <b>sqlite_exec()</b> returns, the database file will
-still be well-formed. It might not contain the same data, but it will
-still be a properly constructed SQLite database file.
-</p></li>
-<li><p>
-No preexisting files on the host computers filesystem, other than
-the database file itself, will be deleted or modified.
-</p></li>
-<li><p>
-For some constants <b>K1</b> and <b>K2</b>,
-if at least <b>K1*strlen(Z) + K2</b> bytes of contiguous memory are
-available to <b>malloc()</b>, then the call to <b>sqlite_exec()</b>
-will not return SQLITE_NOMEM.
-</p></li>
-</ol>
-</p></li>
-
-</ol>
-}
-puts {
-<p><hr /></p>
-<p><a href="index.html"><img src="/goback.jpg" border=0 />
-Back to the SQLite Home Page</a>
-</p>
-
-</body></html>}
+++ /dev/null
-#
-# Run this Tcl script to generate the autoinc.html file.
-#
-set rcsid {$Id: }
-source common.tcl
-
-if {[llength $argv]>0} {
- set outputdir [lindex $argv 0]
-} else {
- set outputdir ""
-}
-
-header {SQLite Autoincrement}
-puts {
-<h1>SQLite Autoincrement</h1>
-
-<p>
-In SQLite, every row of every table has an integer ROWID.
-The ROWID for each row is unique among all rows in the same table.
-In SQLite version 2.8 the ROWID is a 32-bit signed integer.
-Version 3.0 of SQLite expanded the ROWID to be a 64-bit signed integer.
-</p>
-
-<p>
-You can access the ROWID of an SQLite table using one the special column
-names ROWID, _ROWID_, or OID.
-Except if you declare an ordinary table column to use one of those special
-names, then the use of that name will refer to the declared column not
-to the internal ROWID.
-</p>
-
-<p>
-If a table contains a column of type INTEGER PRIMARY KEY, then that
-column becomes an alias for the ROWID. You can then access the ROWID
-using any of four different names, the original three names described above
-or the name given to the INTEGER PRIMARY KEY column. All these names are
-aliases for one another and work equally well in any context.
-</p>
-
-<p>
-When a new row is inserted into an SQLite table, the ROWID can either
-be specified as part of the INSERT statement or it can be assigned
-automatically by the database engine. To specify a ROWID manually,
-just include it in the list of values to be inserted. For example:
-</p>
-
-<blockquote><pre>
-CREATE TABLE test1(a INT, b TEXT);
-INSERT INTO test1(rowid, a, b) VALUES(123, 5, 'hello');
-</pre></blockquote>
-
-<p>
-If no ROWID is specified on the insert, an appropriate ROWID is created
-automatically. The usual algorithm is to give the newly created row
-a ROWID that is one larger than the largest ROWID in the table prior
-to the insert. If the table is initially empty, then a ROWID of 1 is
-used. If the largest ROWID is equal to the largest possible integer
-(9223372036854775807 in SQLite version 3.0 and later) then the database
-engine starts picking candidate ROWIDs at random until it finds one
-that is not previously used.
-</p>
-
-<p>
-The normal ROWID selection algorithm described above
-will generate monotonically increasing
-unique ROWIDs as long as you never use the maximum ROWID value and you never
-delete the entry in the table with the largest ROWID.
-If you ever delete rows or if you ever create a row with the maximum possible
-ROWID, then ROWIDs from previously deleted rows might be reused when creating
-new rows and newly created ROWIDs might not be in strictly accending order.
-</p>
-
-
-<h2>The AUTOINCREMENT Keyword</h2>
-
-<p>
-If a column has the type INTEGER PRIMARY KEY AUTOINCREMENT then a slightly
-different ROWID selection algorithm is used.
-The ROWID chosen for the new row is one larger than the largest ROWID
-that has ever before existed in that same table. If the table has never
-before contained any data, then a ROWID of 1 is used. If the table
-has previously held a row with the largest possible ROWID, then new INSERTs
-are not allowed and any attempt to insert a new row will fail with an
-SQLITE_FULL error.
-</p>
-
-<p>
-SQLite keeps track of the largest ROWID that a table has ever held using
-the special SQLITE_SEQUENCE table. The SQLITE_SEQUENCE table is created
-and initialized automatically whenever a normal table that contains an
-AUTOINCREMENT column is created. The content of the SQLITE_SEQUENCE table
-can be modified using ordinary UPDATE, INSERT, and DELETE statements.
-But making modifications to this table will likely perturb the AUTOINCREMENT
-key generation algorithm. Make sure you know what you are doing before
-you undertake such changes.
-</p>
-
-<p>
-The behavior implemented by the AUTOINCREMENT keyword is subtly different
-from the default behavior. With AUTOINCREMENT, rows with automatically
-selected ROWIDs are guaranteed to have ROWIDs that have never been used
-before by the same table in the same database. And the automatically generated
-ROWIDs are guaranteed to be monotonically increasing. These are important
-properties in certain applications. But if your application does not
-need these properties, you should probably stay with the default behavior
-since the use of AUTOINCREMENT requires additional work to be done
-as each row is inserted and thus causes INSERTs to run a little slower.
-}
-footer $rcsid
+++ /dev/null
-#
-# Run this Tcl script to generate the sqlite.html file.
-#
-set rcsid {$Id: c_interface.tcl,v 1.43 2004/11/19 11:59:24 danielk1977 Exp $}
-source common.tcl
-header {The C language interface to the SQLite library}
-puts {
-<h2>The C language interface to the SQLite library</h2>
-
-<p>The SQLite library is designed to be very easy to use from
-a C or C++ program. This document gives an overview of the C/C++
-programming interface.</p>
-
-<h3>1.0 The Core API</h3>
-
-<p>The interface to the SQLite library consists of three core functions,
-one opaque data structure, and some constants used as return values.
-The core interface is as follows:</p>
-
-<blockquote><pre>
-typedef struct sqlite sqlite;
-#define SQLITE_OK 0 /* Successful result */
-
-sqlite *sqlite_open(const char *dbname, int mode, char **errmsg);
-
-void sqlite_close(sqlite *db);
-
-int sqlite_exec(
- sqlite *db,
- char *sql,
- int (*xCallback)(void*,int,char**,char**),
- void *pArg,
- char **errmsg
-);
-</pre></blockquote>
-
-<p>
-The above is all you really need to know in order to use SQLite
-in your C or C++ programs. There are other interface functions
-available (and described below) but we will begin by describing
-the core functions shown above.
-</p>
-
-<a name="sqlite_open">
-<h4>1.1 Opening a database</h4>
-
-<p>Use the <b>sqlite_open</b> function to open an existing SQLite
-database or to create a new SQLite database. The first argument
-is the database name. The second argument is intended to signal
-whether the database is going to be used for reading and writing
-or just for reading. But in the current implementation, the
-second argument to <b>sqlite_open</b> is ignored.
-The third argument is a pointer to a string pointer.
-If the third argument is not NULL and an error occurs
-while trying to open the database, then an error message will be
-written to memory obtained from malloc() and *errmsg will be made
-to point to this error message. The calling function is responsible
-for freeing the memory when it has finished with it.</p>
-
-<p>The name of an SQLite database is the name of a file that will
-contain the database. If the file does not exist, SQLite attempts
-to create and initialize it. If the file is read-only (due to
-permission bits or because it is located on read-only media like
-a CD-ROM) then SQLite opens the database for reading only. The
-entire SQL database is stored in a single file on the disk. But
-additional temporary files may be created during the execution of
-an SQL command in order to store the database rollback journal or
-temporary and intermediate results of a query.</p>
-
-<p>The return value of the <b>sqlite_open</b> function is a
-pointer to an opaque <b>sqlite</b> structure. This pointer will
-be the first argument to all subsequent SQLite function calls that
-deal with the same database. NULL is returned if the open fails
-for any reason.</p>
-
-<a name="sqlite_close">
-<h4>1.2 Closing the database</h4>
-
-<p>To close an SQLite database, call the <b>sqlite_close</b>
-function passing it the sqlite structure pointer that was obtained
-from a prior call to <b>sqlite_open</b>.
-If a transaction is active when the database is closed, the transaction
-is rolled back.</p>
-
-<a name="sqlite_exec">
-<h4>1.3 Executing SQL statements</h4>
-
-<p>The <b>sqlite_exec</b> function is used to process SQL statements
-and queries. This function requires 5 parameters as follows:</p>
-
-<ol>
-<li><p>A pointer to the sqlite structure obtained from a prior call
- to <b>sqlite_open</b>.</p></li>
-<li><p>A null-terminated string containing the text of one or more
- SQL statements and/or queries to be processed.</p></li>
-<li><p>A pointer to a callback function which is invoked once for each
- row in the result of a query. This argument may be NULL, in which
- case no callbacks will ever be invoked.</p></li>
-<li><p>A pointer that is forwarded to become the first argument
- to the callback function.</p></li>
-<li><p>A pointer to an error string. Error messages are written to space
- obtained from malloc() and the error string is made to point to
- the malloced space. The calling function is responsible for freeing
- this space when it has finished with it.
- This argument may be NULL, in which case error messages are not
- reported back to the calling function.</p></li>
-</ol>
-
-<p>
-The callback function is used to receive the results of a query. A
-prototype for the callback function is as follows:</p>
-
-<blockquote><pre>
-int Callback(void *pArg, int argc, char **argv, char **columnNames){
- return 0;
-}
-</pre></blockquote>
-
-<a name="callback_row_data">
-<p>The first argument to the callback is just a copy of the fourth argument
-to <b>sqlite_exec</b> This parameter can be used to pass arbitrary
-information through to the callback function from client code.
-The second argument is the number of columns in the query result.
-The third argument is an array of pointers to strings where each string
-is a single column of the result for that record. Note that the
-callback function reports a NULL value in the database as a NULL pointer,
-which is very different from an empty string. If the i-th parameter
-is an empty string, we will get:</p>
-<blockquote><pre>
-argv[i][0] == 0
-</pre></blockquote>
-<p>But if the i-th parameter is NULL we will get:</p>
-<blockquote><pre>
-argv[i] == 0
-</pre></blockquote>
-
-<p>The names of the columns are contained in first <i>argc</i>
-entries of the fourth argument.
-If the <a href="pragma.html#pragma_show_datatypes">SHOW_DATATYPES</a> pragma
-is on (it is off by default) then
-the second <i>argc</i> entries in the 4th argument are the datatypes
-for the corresponding columns.
-</p>
-
-<p>If the <a href="pragma.html#pragma_empty_result_callbacks">
-EMPTY_RESULT_CALLBACKS</a> pragma is set to ON and the result of
-a query is an empty set, then the callback is invoked once with the
-third parameter (argv) set to 0. In other words
-<blockquote><pre>
-argv == 0
-</pre></blockquote>
-The second parameter (argc)
-and the fourth parameter (columnNames) are still valid
-and can be used to determine the number and names of the result
-columns if there had been a result.
-The default behavior is not to invoke the callback at all if the
-result set is empty.</p>
-
-<a name="callback_returns_nonzero">
-<p>The callback function should normally return 0. If the callback
-function returns non-zero, the query is immediately aborted and
-<b>sqlite_exec</b> will return SQLITE_ABORT.</p>
-
-<h4>1.4 Error Codes</h4>
-
-<p>
-The <b>sqlite_exec</b> function normally returns SQLITE_OK. But
-if something goes wrong it can return a different value to indicate
-the type of error. Here is a complete list of the return codes:
-</p>
-
-<blockquote><pre>
-#define SQLITE_OK 0 /* Successful result */
-#define SQLITE_ERROR 1 /* SQL error or missing database */
-#define SQLITE_INTERNAL 2 /* An internal logic error in SQLite */
-#define SQLITE_PERM 3 /* Access permission denied */
-#define SQLITE_ABORT 4 /* Callback routine requested an abort */
-#define SQLITE_BUSY 5 /* The database file is locked */
-#define SQLITE_LOCKED 6 /* A table in the database is locked */
-#define SQLITE_NOMEM 7 /* A malloc() failed */
-#define SQLITE_READONLY 8 /* Attempt to write a readonly database */
-#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite_interrupt() */
-#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
-#define SQLITE_CORRUPT 11 /* The database disk image is malformed */
-#define SQLITE_NOTFOUND 12 /* (Internal Only) Table or record not found */
-#define SQLITE_FULL 13 /* Insertion failed because database is full */
-#define SQLITE_CANTOPEN 14 /* Unable to open the database file */
-#define SQLITE_PROTOCOL 15 /* Database lock protocol error */
-#define SQLITE_EMPTY 16 /* (Internal Only) Database table is empty */
-#define SQLITE_SCHEMA 17 /* The database schema changed */
-#define SQLITE_TOOBIG 18 /* Too much data for one row of a table */
-#define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */
-#define SQLITE_MISMATCH 20 /* Data type mismatch */
-#define SQLITE_MISUSE 21 /* Library used incorrectly */
-#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
-#define SQLITE_AUTH 23 /* Authorization denied */
-#define SQLITE_ROW 100 /* sqlite_step() has another row ready */
-#define SQLITE_DONE 101 /* sqlite_step() has finished executing */
-</pre></blockquote>
-
-<p>
-The meanings of these various return values are as follows:
-</p>
-
-<blockquote>
-<dl>
-<dt>SQLITE_OK</dt>
-<dd><p>This value is returned if everything worked and there were no errors.
-</p></dd>
-<dt>SQLITE_INTERNAL</dt>
-<dd><p>This value indicates that an internal consistency check within
-the SQLite library failed. This can only happen if there is a bug in
-the SQLite library. If you ever get an SQLITE_INTERNAL reply from
-an <b>sqlite_exec</b> call, please report the problem on the SQLite
-mailing list.
-</p></dd>
-<dt>SQLITE_ERROR</dt>
-<dd><p>This return value indicates that there was an error in the SQL
-that was passed into the <b>sqlite_exec</b>.
-</p></dd>
-<dt>SQLITE_PERM</dt>
-<dd><p>This return value says that the access permissions on the database
-file are such that the file cannot be opened.
-</p></dd>
-<dt>SQLITE_ABORT</dt>
-<dd><p>This value is returned if the callback function returns non-zero.
-</p></dd>
-<dt>SQLITE_BUSY</dt>
-<dd><p>This return code indicates that another program or thread has
-the database locked. SQLite allows two or more threads to read the
-database at the same time, but only one thread can have the database
-open for writing at the same time. Locking in SQLite is on the
-entire database.</p>
-</p></dd>
-<dt>SQLITE_LOCKED</dt>
-<dd><p>This return code is similar to SQLITE_BUSY in that it indicates
-that the database is locked. But the source of the lock is a recursive
-call to <b>sqlite_exec</b>. This return can only occur if you attempt
-to invoke sqlite_exec from within a callback routine of a query
-from a prior invocation of sqlite_exec. Recursive calls to
-sqlite_exec are allowed as long as they do
-not attempt to write the same table.
-</p></dd>
-<dt>SQLITE_NOMEM</dt>
-<dd><p>This value is returned if a call to <b>malloc</b> fails.
-</p></dd>
-<dt>SQLITE_READONLY</dt>
-<dd><p>This return code indicates that an attempt was made to write to
-a database file that is opened for reading only.
-</p></dd>
-<dt>SQLITE_INTERRUPT</dt>
-<dd><p>This value is returned if a call to <b>sqlite_interrupt</b>
-interrupts a database operation in progress.
-</p></dd>
-<dt>SQLITE_IOERR</dt>
-<dd><p>This value is returned if the operating system informs SQLite
-that it is unable to perform some disk I/O operation. This could mean
-that there is no more space left on the disk.
-</p></dd>
-<dt>SQLITE_CORRUPT</dt>
-<dd><p>This value is returned if SQLite detects that the database it is
-working on has become corrupted. Corruption might occur due to a rogue
-process writing to the database file or it might happen due to an
-perviously undetected logic error in of SQLite. This value is also
-returned if a disk I/O error occurs in such a way that SQLite is forced
-to leave the database file in a corrupted state. The latter should only
-happen due to a hardware or operating system malfunction.
-</p></dd>
-<dt>SQLITE_FULL</dt>
-<dd><p>This value is returned if an insertion failed because there is
-no space left on the disk, or the database is too big to hold any
-more information. The latter case should only occur for databases
-that are larger than 2GB in size.
-</p></dd>
-<dt>SQLITE_CANTOPEN</dt>
-<dd><p>This value is returned if the database file could not be opened
-for some reason.
-</p></dd>
-<dt>SQLITE_PROTOCOL</dt>
-<dd><p>This value is returned if some other process is messing with
-file locks and has violated the file locking protocol that SQLite uses
-on its rollback journal files.
-</p></dd>
-<dt>SQLITE_SCHEMA</dt>
-<dd><p>When the database first opened, SQLite reads the database schema
-into memory and uses that schema to parse new SQL statements. If another
-process changes the schema, the command currently being processed will
-abort because the virtual machine code generated assumed the old
-schema. This is the return code for such cases. Retrying the
-command usually will clear the problem.
-</p></dd>
-<dt>SQLITE_TOOBIG</dt>
-<dd><p>SQLite will not store more than about 1 megabyte of data in a single
-row of a single table. If you attempt to store more than 1 megabyte
-in a single row, this is the return code you get.
-</p></dd>
-<dt>SQLITE_CONSTRAINT</dt>
-<dd><p>This constant is returned if the SQL statement would have violated
-a database constraint.
-</p></dd>
-<dt>SQLITE_MISMATCH</dt>
-<dd><p>This error occurs when there is an attempt to insert non-integer
-data into a column labeled INTEGER PRIMARY KEY. For most columns, SQLite
-ignores the data type and allows any kind of data to be stored. But
-an INTEGER PRIMARY KEY column is only allowed to store integer data.
-</p></dd>
-<dt>SQLITE_MISUSE</dt>
-<dd><p>This error might occur if one or more of the SQLite API routines
-is used incorrectly. Examples of incorrect usage include calling
-<b>sqlite_exec</b> after the database has been closed using
-<b>sqlite_close</b> or
-calling <b>sqlite_exec</b> with the same
-database pointer simultaneously from two separate threads.
-</p></dd>
-<dt>SQLITE_NOLFS</dt>
-<dd><p>This error means that you have attempts to create or access a file
-database file that is larger that 2GB on a legacy Unix machine that
-lacks large file support.
-</p></dd>
-<dt>SQLITE_AUTH</dt>
-<dd><p>This error indicates that the authorizer callback
-has disallowed the SQL you are attempting to execute.
-</p></dd>
-<dt>SQLITE_ROW</dt>
-<dd><p>This is one of the return codes from the
-<b>sqlite_step</b> routine which is part of the non-callback API.
-It indicates that another row of result data is available.
-</p></dd>
-<dt>SQLITE_DONE</dt>
-<dd><p>This is one of the return codes from the
-<b>sqlite_step</b> routine which is part of the non-callback API.
-It indicates that the SQL statement has been completely executed and
-the <b>sqlite_finalize</b> routine is ready to be called.
-</p></dd>
-</dl>
-</blockquote>
-
-<h3>2.0 Accessing Data Without Using A Callback Function</h3>
-
-<p>
-The <b>sqlite_exec</b> routine described above used to be the only
-way to retrieve data from an SQLite database. But many programmers found
-it inconvenient to use a callback function to obtain results. So beginning
-with SQLite version 2.7.7, a second access interface is available that
-does not use callbacks.
-</p>
-
-<p>
-The new interface uses three separate functions to replace the single
-<b>sqlite_exec</b> function.
-</p>
-
-<blockquote><pre>
-typedef struct sqlite_vm sqlite_vm;
-
-int sqlite_compile(
- sqlite *db, /* The open database */
- const char *zSql, /* SQL statement to be compiled */
- const char **pzTail, /* OUT: uncompiled tail of zSql */
- sqlite_vm **ppVm, /* OUT: the virtual machine to execute zSql */
- char **pzErrmsg /* OUT: Error message. */
-);
-
-int sqlite_step(
- sqlite_vm *pVm, /* The virtual machine to execute */
- int *pN, /* OUT: Number of columns in result */
- const char ***pazValue, /* OUT: Column data */
- const char ***pazColName /* OUT: Column names and datatypes */
-);
-
-int sqlite_finalize(
- sqlite_vm *pVm, /* The virtual machine to be finalized */
- char **pzErrMsg /* OUT: Error message */
-);
-</pre></blockquote>
-
-<p>
-The strategy is to compile a single SQL statement using
-<b>sqlite_compile</b> then invoke <b>sqlite_step</b> multiple times,
-once for each row of output, and finally call <b>sqlite_finalize</b>
-to clean up after the SQL has finished execution.
-</p>
-
-<h4>2.1 Compiling An SQL Statement Into A Virtual Machine</h4>
-
-<p>
-The <b>sqlite_compile</b> "compiles" a single SQL statement (specified
-by the second parameter) and generates a virtual machine that is able
-to execute that statement.
-As with must interface routines, the first parameter must be a pointer
-to an sqlite structure that was obtained from a prior call to
-<b>sqlite_open</b>.
-
-<p>
-A pointer to the virtual machine is stored in a pointer which is passed
-in as the 4th parameter.
-Space to hold the virtual machine is dynamically allocated. To avoid
-a memory leak, the calling function must invoke
-<b>sqlite_finalize</b> on the virtual machine after it has finished
-with it.
-The 4th parameter may be set to NULL if an error is encountered during
-compilation.
-</p>
-
-<p>
-If any errors are encountered during compilation, an error message is
-written into memory obtained from <b>malloc</b> and the 5th parameter
-is made to point to that memory. If the 5th parameter is NULL, then
-no error message is generated. If the 5th parameter is not NULL, then
-the calling function should dispose of the memory containing the error
-message by calling <b>sqlite_freemem</b>.
-</p>
-
-<p>
-If the 2nd parameter actually contains two or more statements of SQL,
-only the first statement is compiled. (This is different from the
-behavior of <b>sqlite_exec</b> which executes all SQL statements
-in its input string.) The 3rd parameter to <b>sqlite_compile</b>
-is made to point to the first character beyond the end of the first
-statement of SQL in the input. If the 2nd parameter contains only
-a single SQL statement, then the 3rd parameter will be made to point
-to the '\000' terminator at the end of the 2nd parameter.
-</p>
-
-<p>
-On success, <b>sqlite_compile</b> returns SQLITE_OK.
-Otherwise and error code is returned.
-</p>
-
-<h4>2.2 Step-By-Step Execution Of An SQL Statement</h4>
-
-<p>
-After a virtual machine has been generated using <b>sqlite_compile</b>
-it is executed by one or more calls to <b>sqlite_step</b>. Each
-invocation of <b>sqlite_step</b>, except the last one,
-returns a single row of the result.
-The number of columns in the result is stored in the integer that
-the 2nd parameter points to.
-The pointer specified by the 3rd parameter is made to point
-to an array of pointers to column values.
-The pointer in the 4th parameter is made to point to an array
-of pointers to column names and datatypes.
-The 2nd through 4th parameters to <b>sqlite_step</b> convey the
-same information as the 2nd through 4th parameters of the
-<b>callback</b> routine when using
-the <b>sqlite_exec</b> interface. Except, with <b>sqlite_step</b>
-the column datatype information is always included in the in the
-4th parameter regardless of whether or not the
-<a href="pragma.html#pragma_show_datatypes">SHOW_DATATYPES</a> pragma
-is on or off.
-</p>
-
-<p>
-Each invocation of <b>sqlite_step</b> returns an integer code that
-indicates what happened during that step. This code may be
-SQLITE_BUSY, SQLITE_ROW, SQLITE_DONE, SQLITE_ERROR, or
-SQLITE_MISUSE.
-</p>
-
-<p>
-If the virtual machine is unable to open the database file because
-it is locked by another thread or process, <b>sqlite_step</b>
-will return SQLITE_BUSY. The calling function should do some other
-activity, or sleep, for a short amount of time to give the lock a
-chance to clear, then invoke <b>sqlite_step</b> again. This can
-be repeated as many times as desired.
-</p>
-
-<p>
-Whenever another row of result data is available,
-<b>sqlite_step</b> will return SQLITE_ROW. The row data is
-stored in an array of pointers to strings and the 2nd parameter
-is made to point to this array.
-</p>
-
-<p>
-When all processing is complete, <b>sqlite_step</b> will return
-either SQLITE_DONE or SQLITE_ERROR. SQLITE_DONE indicates that the
-statement completed successfully and SQLITE_ERROR indicates that there
-was a run-time error. (The details of the error are obtained from
-<b>sqlite_finalize</b>.) It is a misuse of the library to attempt
-to call <b>sqlite_step</b> again after it has returned SQLITE_DONE
-or SQLITE_ERROR.
-</p>
-
-<p>
-When <b>sqlite_step</b> returns SQLITE_DONE or SQLITE_ERROR,
-the *pN and *pazColName values are set to the number of columns
-in the result set and to the names of the columns, just as they
-are for an SQLITE_ROW return. This allows the calling code to
-find the number of result columns and the column names and datatypes
-even if the result set is empty. The *pazValue parameter is always
-set to NULL when the return codes is SQLITE_DONE or SQLITE_ERROR.
-If the SQL being executed is a statement that does not
-return a result (such as an INSERT or an UPDATE) then *pN will
-be set to zero and *pazColName will be set to NULL.
-</p>
-
-<p>
-If you abuse the library by trying to call <b>sqlite_step</b>
-inappropriately it will attempt return SQLITE_MISUSE.
-This can happen if you call sqlite_step() on the same virtual machine
-at the same
-time from two or more threads or if you call sqlite_step()
-again after it returned SQLITE_DONE or SQLITE_ERROR or if you
-pass in an invalid virtual machine pointer to sqlite_step().
-You should not depend on the SQLITE_MISUSE return code to indicate
-an error. It is possible that a misuse of the interface will go
-undetected and result in a program crash. The SQLITE_MISUSE is
-intended as a debugging aid only - to help you detect incorrect
-usage prior to a mishap. The misuse detection logic is not guaranteed
-to work in every case.
-</p>
-
-<h4>2.3 Deleting A Virtual Machine</h4>
-
-<p>
-Every virtual machine that <b>sqlite_compile</b> creates should
-eventually be handed to <b>sqlite_finalize</b>. The sqlite_finalize()
-procedure deallocates the memory and other resources that the virtual
-machine uses. Failure to call sqlite_finalize() will result in
-resource leaks in your program.
-</p>
-
-<p>
-The <b>sqlite_finalize</b> routine also returns the result code
-that indicates success or failure of the SQL operation that the
-virtual machine carried out.
-The value returned by sqlite_finalize() will be the same as would
-have been returned had the same SQL been executed by <b>sqlite_exec</b>.
-The error message returned will also be the same.
-</p>
-
-<p>
-It is acceptable to call <b>sqlite_finalize</b> on a virtual machine
-before <b>sqlite_step</b> has returned SQLITE_DONE. Doing so has
-the effect of interrupting the operation in progress. Partially completed
-changes will be rolled back and the database will be restored to its
-original state (unless an alternative recovery algorithm is selected using
-an ON CONFLICT clause in the SQL being executed.) The effect is the
-same as if a callback function of <b>sqlite_exec</b> had returned
-non-zero.
-</p>
-
-<p>
-It is also acceptable to call <b>sqlite_finalize</b> on a virtual machine
-that has never been passed to <b>sqlite_step</b> even once.
-</p>
-
-<h3>3.0 The Extended API</h3>
-
-<p>Only the three core routines described in section 1.0 are required to use
-SQLite. But there are many other functions that provide
-useful interfaces. These extended routines are as follows:
-</p>
-
-<blockquote><pre>
-int sqlite_last_insert_rowid(sqlite*);
-
-int sqlite_changes(sqlite*);
-
-int sqlite_get_table(
- sqlite*,
- char *sql,
- char ***result,
- int *nrow,
- int *ncolumn,
- char **errmsg
-);
-
-void sqlite_free_table(char**);
-
-void sqlite_interrupt(sqlite*);
-
-int sqlite_complete(const char *sql);
-
-void sqlite_busy_handler(sqlite*, int (*)(void*,const char*,int), void*);
-
-void sqlite_busy_timeout(sqlite*, int ms);
-
-const char sqlite_version[];
-
-const char sqlite_encoding[];
-
-int sqlite_exec_printf(
- sqlite*,
- char *sql,
- int (*)(void*,int,char**,char**),
- void*,
- char **errmsg,
- ...
-);
-
-int sqlite_exec_vprintf(
- sqlite*,
- char *sql,
- int (*)(void*,int,char**,char**),
- void*,
- char **errmsg,
- va_list
-);
-
-int sqlite_get_table_printf(
- sqlite*,
- char *sql,
- char ***result,
- int *nrow,
- int *ncolumn,
- char **errmsg,
- ...
-);
-
-int sqlite_get_table_vprintf(
- sqlite*,
- char *sql,
- char ***result,
- int *nrow,
- int *ncolumn,
- char **errmsg,
- va_list
-);
-
-char *sqlite_mprintf(const char *zFormat, ...);
-
-char *sqlite_vmprintf(const char *zFormat, va_list);
-
-void sqlite_freemem(char*);
-
-void sqlite_progress_handler(sqlite*, int, int (*)(void*), void*);
-
-</pre></blockquote>
-
-<p>All of the above definitions are included in the "sqlite.h"
-header file that comes in the source tree.</p>
-
-<h4>3.1 The ROWID of the most recent insert</h4>
-
-<p>Every row of an SQLite table has a unique integer key. If the
-table has a column labeled INTEGER PRIMARY KEY, then that column
-serves as the key. If there is no INTEGER PRIMARY KEY column then
-the key is a unique integer. The key for a row can be accessed in
-a SELECT statement or used in a WHERE or ORDER BY clause using any
-of the names "ROWID", "OID", or "_ROWID_".</p>
-
-<p>When you do an insert into a table that does not have an INTEGER PRIMARY
-KEY column, or if the table does have an INTEGER PRIMARY KEY but the value
-for that column is not specified in the VALUES clause of the insert, then
-the key is automatically generated. You can find the value of the key
-for the most recent INSERT statement using the
-<b>sqlite_last_insert_rowid</b> API function.</p>
-
-<h4>3.2 The number of rows that changed</h4>
-
-<p>The <b>sqlite_changes</b> API function returns the number of rows
-that have been inserted, deleted, or modified since the database was
-last quiescent. A "quiescent" database is one in which there are
-no outstanding calls to <b>sqlite_exec</b> and no VMs created by
-<b>sqlite_compile</b> that have not been finalized by <b>sqlite_finalize</b>.
-In common usage, <b>sqlite_changes</b> returns the number
-of rows inserted, deleted, or modified by the most recent <b>sqlite_exec</b>
-call or since the most recent <b>sqlite_compile</b>. But if you have
-nested calls to <b>sqlite_exec</b> (that is, if the callback routine
-of one <b>sqlite_exec</b> invokes another <b>sqlite_exec</b>) or if
-you invoke <b>sqlite_compile</b> to create a new VM while there is
-still another VM in existance, then
-the meaning of the number returned by <b>sqlite_changes</b> is more
-complex.
-The number reported includes any changes
-that were later undone by a ROLLBACK or ABORT. But rows that are
-deleted because of a DROP TABLE are <em>not</em> counted.</p>
-
-<p>SQLite implements the command "<b>DELETE FROM table</b>" (without
-a WHERE clause) by dropping the table then recreating it.
-This is much faster than deleting the elements of the table individually.
-But it also means that the value returned from <b>sqlite_changes</b>
-will be zero regardless of the number of elements that were originally
-in the table. If an accurate count of the number of elements deleted
-is necessary, use "<b>DELETE FROM table WHERE 1</b>" instead.</p>
-
-<h4>3.3 Querying into memory obtained from malloc()</h4>
-
-<p>The <b>sqlite_get_table</b> function is a wrapper around
-<b>sqlite_exec</b> that collects all the information from successive
-callbacks and writes it into memory obtained from malloc(). This
-is a convenience function that allows the application to get the
-entire result of a database query with a single function call.</p>
-
-<p>The main result from <b>sqlite_get_table</b> is an array of pointers
-to strings. There is one element in this array for each column of
-each row in the result. NULL results are represented by a NULL
-pointer. In addition to the regular data, there is an added row at the
-beginning of the array that contains the name of each column of the
-result.</p>
-
-<p>As an example, consider the following query:</p>
-
-<blockquote>
-SELECT employee_name, login, host FROM users WHERE login LIKE 'd%';
-</blockquote>
-
-<p>This query will return the name, login and host computer name
-for every employee whose login begins with the letter "d". If this
-query is submitted to <b>sqlite_get_table</b> the result might
-look like this:</p>
-
-<blockquote>
-nrow = 2<br>
-ncolumn = 3<br>
-result[0] = "employee_name"<br>
-result[1] = "login"<br>
-result[2] = "host"<br>
-result[3] = "dummy"<br>
-result[4] = "No such user"<br>
-result[5] = 0<br>
-result[6] = "D. Richard Hipp"<br>
-result[7] = "drh"<br>
-result[8] = "zadok"
-</blockquote>
-
-<p>Notice that the "host" value for the "dummy" record is NULL so
-the result[] array contains a NULL pointer at that slot.</p>
-
-<p>If the result set of a query is empty, then by default
-<b>sqlite_get_table</b> will set nrow to 0 and leave its
-result parameter is set to NULL. But if the EMPTY_RESULT_CALLBACKS
-pragma is ON then the result parameter is initialized to the names
-of the columns only. For example, consider this query which has
-an empty result set:</p>
-
-<blockquote>
-SELECT employee_name, login, host FROM users WHERE employee_name IS NULL;
-</blockquote>
-
-<p>
-The default behavior gives this results:
-</p>
-
-<blockquote>
-nrow = 0<br>
-ncolumn = 0<br>
-result = 0<br>
-</blockquote>
-
-<p>
-But if the EMPTY_RESULT_CALLBACKS pragma is ON, then the following
-is returned:
-</p>
-
-<blockquote>
-nrow = 0<br>
-ncolumn = 3<br>
-result[0] = "employee_name"<br>
-result[1] = "login"<br>
-result[2] = "host"<br>
-</blockquote>
-
-<p>Memory to hold the information returned by <b>sqlite_get_table</b>
-is obtained from malloc(). But the calling function should not try
-to free this information directly. Instead, pass the complete table
-to <b>sqlite_free_table</b> when the table is no longer needed.
-It is safe to call <b>sqlite_free_table</b> with a NULL pointer such
-as would be returned if the result set is empty.</p>
-
-<p>The <b>sqlite_get_table</b> routine returns the same integer
-result code as <b>sqlite_exec</b>.</p>
-
-<h4>3.4 Interrupting an SQLite operation</h4>
-
-<p>The <b>sqlite_interrupt</b> function can be called from a
-different thread or from a signal handler to cause the current database
-operation to exit at its first opportunity. When this happens,
-the <b>sqlite_exec</b> routine (or the equivalent) that started
-the database operation will return SQLITE_INTERRUPT.</p>
-
-<h4>3.5 Testing for a complete SQL statement</h4>
-
-<p>The next interface routine to SQLite is a convenience function used
-to test whether or not a string forms a complete SQL statement.
-If the <b>sqlite_complete</b> function returns true when its input
-is a string, then the argument forms a complete SQL statement.
-There are no guarantees that the syntax of that statement is correct,
-but we at least know the statement is complete. If <b>sqlite_complete</b>
-returns false, then more text is required to complete the SQL statement.</p>
-
-<p>For the purpose of the <b>sqlite_complete</b> function, an SQL
-statement is complete if it ends in a semicolon.</p>
-
-<p>The <b>sqlite</b> command-line utility uses the <b>sqlite_complete</b>
-function to know when it needs to call <b>sqlite_exec</b>. After each
-line of input is received, <b>sqlite</b> calls <b>sqlite_complete</b>
-on all input in its buffer. If <b>sqlite_complete</b> returns true,
-then <b>sqlite_exec</b> is called and the input buffer is reset. If
-<b>sqlite_complete</b> returns false, then the prompt is changed to
-the continuation prompt and another line of text is read and added to
-the input buffer.</p>
-
-<h4>3.6 Library version string</h4>
-
-<p>The SQLite library exports the string constant named
-<b>sqlite_version</b> which contains the version number of the
-library. The header file contains a macro SQLITE_VERSION
-with the same information. If desired, a program can compare
-the SQLITE_VERSION macro against the <b>sqlite_version</b>
-string constant to verify that the version number of the
-header file and the library match.</p>
-
-<h4>3.7 Library character encoding</h4>
-
-<p>By default, SQLite assumes that all data uses a fixed-size
-8-bit character (iso8859). But if you give the --enable-utf8 option
-to the configure script, then the library assumes UTF-8 variable
-sized characters. This makes a difference for the LIKE and GLOB
-operators and the LENGTH() and SUBSTR() functions. The static
-string <b>sqlite_encoding</b> will be set to either "UTF-8" or
-"iso8859" to indicate how the library was compiled. In addition,
-the <b>sqlite.h</b> header file will define one of the
-macros <b>SQLITE_UTF8</b> or <b>SQLITE_ISO8859</b>, as appropriate.</p>
-
-<p>Note that the character encoding mechanism used by SQLite cannot
-be changed at run-time. This is a compile-time option only. The
-<b>sqlite_encoding</b> character string just tells you how the library
-was compiled.</p>
-
-<h4>3.8 Changing the library's response to locked files</h4>
-
-<p>The <b>sqlite_busy_handler</b> procedure can be used to register
-a busy callback with an open SQLite database. The busy callback will
-be invoked whenever SQLite tries to access a database that is locked.
-The callback will typically do some other useful work, or perhaps sleep,
-in order to give the lock a chance to clear. If the callback returns
-non-zero, then SQLite tries again to access the database and the cycle
-repeats. If the callback returns zero, then SQLite aborts the current
-operation and returns SQLITE_BUSY.</p>
-
-<p>The arguments to <b>sqlite_busy_handler</b> are the opaque
-structure returned from <b>sqlite_open</b>, a pointer to the busy
-callback function, and a generic pointer that will be passed as
-the first argument to the busy callback. When SQLite invokes the
-busy callback, it sends it three arguments: the generic pointer
-that was passed in as the third argument to <b>sqlite_busy_handler</b>,
-the name of the database table or index that the library is trying
-to access, and the number of times that the library has attempted to
-access the database table or index.</p>
-
-<p>For the common case where we want the busy callback to sleep,
-the SQLite library provides a convenience routine <b>sqlite_busy_timeout</b>.
-The first argument to <b>sqlite_busy_timeout</b> is a pointer to
-an open SQLite database and the second argument is a number of milliseconds.
-After <b>sqlite_busy_timeout</b> has been executed, the SQLite library
-will wait for the lock to clear for at least the number of milliseconds
-specified before it returns SQLITE_BUSY. Specifying zero milliseconds for
-the timeout restores the default behavior.</p>
-
-<h4>3.9 Using the <tt>_printf()</tt> wrapper functions</h4>
-
-<p>The four utility functions</p>
-
-<p>
-<ul>
-<li><b>sqlite_exec_printf()</b></li>
-<li><b>sqlite_exec_vprintf()</b></li>
-<li><b>sqlite_get_table_printf()</b></li>
-<li><b>sqlite_get_table_vprintf()</b></li>
-</ul>
-</p>
-
-<p>implement the same query functionality as <b>sqlite_exec</b>
-and <b>sqlite_get_table</b>. But instead of taking a complete
-SQL statement as their second argument, the four <b>_printf</b>
-routines take a printf-style format string. The SQL statement to
-be executed is generated from this format string and from whatever
-additional arguments are attached to the end of the function call.</p>
-
-<p>There are two advantages to using the SQLite printf
-functions instead of <b>sprintf</b>. First of all, with the
-SQLite printf routines, there is never a danger of overflowing a
-static buffer as there is with <b>sprintf</b>. The SQLite
-printf routines automatically allocate (and later frees)
-as much memory as is
-necessary to hold the SQL statements generated.</p>
-
-<p>The second advantage the SQLite printf routines have over
-<b>sprintf</b> are two new formatting options specifically designed
-to support string literals in SQL. Within the format string,
-the %q formatting option works very much like %s in that it
-reads a null-terminated string from the argument list and inserts
-it into the result. But %q translates the inserted string by
-making two copies of every single-quote (') character in the
-substituted string. This has the effect of escaping the end-of-string
-meaning of single-quote within a string literal. The %Q formatting
-option works similar; it translates the single-quotes like %q and
-additionally encloses the resulting string in single-quotes.
-If the argument for the %Q formatting options is a NULL pointer,
-the resulting string is NULL without single quotes.
-</p>
-
-<p>Consider an example. Suppose you are trying to insert a string
-value into a database table where the string value was obtained from
-user input. Suppose the string to be inserted is stored in a variable
-named zString. The code to do the insertion might look like this:</p>
-
-<blockquote><pre>
-sqlite_exec_printf(db,
- "INSERT INTO table1 VALUES('%s')",
- 0, 0, 0, zString);
-</pre></blockquote>
-
-<p>If the zString variable holds text like "Hello", then this statement
-will work just fine. But suppose the user enters a string like
-"Hi y'all!". The SQL statement generated reads as follows:
-
-<blockquote><pre>
-INSERT INTO table1 VALUES('Hi y'all')
-</pre></blockquote>
-
-<p>This is not valid SQL because of the apostrophy in the word "y'all".
-But if the %q formatting option is used instead of %s, like this:</p>
-
-<blockquote><pre>
-sqlite_exec_printf(db,
- "INSERT INTO table1 VALUES('%q')",
- 0, 0, 0, zString);
-</pre></blockquote>
-
-<p>Then the generated SQL will look like the following:</p>
-
-<blockquote><pre>
-INSERT INTO table1 VALUES('Hi y''all')
-</pre></blockquote>
-
-<p>Here the apostrophy has been escaped and the SQL statement is well-formed.
-When generating SQL on-the-fly from data that might contain a
-single-quote character ('), it is always a good idea to use the
-SQLite printf routines and the %q formatting option instead of <b>sprintf</b>.
-</p>
-
-<p>If the %Q formatting option is used instead of %q, like this:</p>
-
-<blockquote><pre>
-sqlite_exec_printf(db,
- "INSERT INTO table1 VALUES(%Q)",
- 0, 0, 0, zString);
-</pre></blockquote>
-
-<p>Then the generated SQL will look like the following:</p>
-
-<blockquote><pre>
-INSERT INTO table1 VALUES('Hi y''all')
-</pre></blockquote>
-
-<p>If the value of the zString variable is NULL, the generated SQL
-will look like the following:</p>
-
-<blockquote><pre>
-INSERT INTO table1 VALUES(NULL)
-</pre></blockquote>
-
-<p>All of the _printf() routines above are built around the following
-two functions:</p>
-
-<blockquote><pre>
-char *sqlite_mprintf(const char *zFormat, ...);
-char *sqlite_vmprintf(const char *zFormat, va_list);
-</pre></blockquote>
-
-<p>The <b>sqlite_mprintf()</b> routine works like the the standard library
-<b>sprintf()</b> except that it writes its results into memory obtained
-from malloc() and returns a pointer to the malloced buffer.
-<b>sqlite_mprintf()</b> also understands the %q and %Q extensions described
-above. The <b>sqlite_vmprintf()</b> is a varargs version of the same
-routine. The string pointer that these routines return should be freed
-by passing it to <b>sqlite_freemem()</b>.
-</p>
-
-<h4>3.10 Performing background jobs during large queries</h3>
-
-<p>The <b>sqlite_progress_handler()</b> routine can be used to register a
-callback routine with an SQLite database to be invoked periodically during long
-running calls to <b>sqlite_exec()</b>, <b>sqlite_step()</b> and the various
-wrapper functions.
-</p>
-
-<p>The callback is invoked every N virtual machine operations, where N is
-supplied as the second argument to <b>sqlite_progress_handler()</b>. The third
-and fourth arguments to <b>sqlite_progress_handler()</b> are a pointer to the
-routine to be invoked and a void pointer to be passed as the first argument to
-it.
-</p>
-
-<p>The time taken to execute each virtual machine operation can vary based on
-many factors. A typical value for a 1 GHz PC is between half and three million
-per second but may be much higher or lower, depending on the query. As such it
-is difficult to schedule background operations based on virtual machine
-operations. Instead, it is recommended that a callback be scheduled relatively
-frequently (say every 1000 instructions) and external timer routines used to
-determine whether or not background jobs need to be run.
-</p>
-
-<a name="cfunc">
-<h3>4.0 Adding New SQL Functions</h3>
-
-<p>Beginning with version 2.4.0, SQLite allows the SQL language to be
-extended with new functions implemented as C code. The following interface
-is used:
-</p>
-
-<blockquote><pre>
-typedef struct sqlite_func sqlite_func;
-
-int sqlite_create_function(
- sqlite *db,
- const char *zName,
- int nArg,
- void (*xFunc)(sqlite_func*,int,const char**),
- void *pUserData
-);
-int sqlite_create_aggregate(
- sqlite *db,
- const char *zName,
- int nArg,
- void (*xStep)(sqlite_func*,int,const char**),
- void (*xFinalize)(sqlite_func*),
- void *pUserData
-);
-
-char *sqlite_set_result_string(sqlite_func*,const char*,int);
-void sqlite_set_result_int(sqlite_func*,int);
-void sqlite_set_result_double(sqlite_func*,double);
-void sqlite_set_result_error(sqlite_func*,const char*,int);
-
-void *sqlite_user_data(sqlite_func*);
-void *sqlite_aggregate_context(sqlite_func*, int nBytes);
-int sqlite_aggregate_count(sqlite_func*);
-</pre></blockquote>
-
-<p>
-The <b>sqlite_create_function()</b> interface is used to create
-regular functions and <b>sqlite_create_aggregate()</b> is used to
-create new aggregate functions. In both cases, the <b>db</b>
-parameter is an open SQLite database on which the functions should
-be registered, <b>zName</b> is the name of the new function,
-<b>nArg</b> is the number of arguments, and <b>pUserData</b> is
-a pointer which is passed through unchanged to the C implementation
-of the function. Both routines return 0 on success and non-zero
-if there are any errors.
-</p>
-
-<p>
-The length of a function name may not exceed 255 characters.
-Any attempt to create a function whose name exceeds 255 characters
-in length will result in an error.
-</p>
-
-<p>
-For regular functions, the <b>xFunc</b> callback is invoked once
-for each function call. The implementation of xFunc should call
-one of the <b>sqlite_set_result_...</b> interfaces to return its
-result. The <b>sqlite_user_data()</b> routine can be used to
-retrieve the <b>pUserData</b> pointer that was passed in when the
-function was registered.
-</p>
-
-<p>
-For aggregate functions, the <b>xStep</b> callback is invoked once
-for each row in the result and then <b>xFinalize</b> is invoked at the
-end to compute a final answer. The xStep routine can use the
-<b>sqlite_aggregate_context()</b> interface to allocate memory that
-will be unique to that particular instance of the SQL function.
-This memory will be automatically deleted after xFinalize is called.
-The <b>sqlite_aggregate_count()</b> routine can be used to find out
-how many rows of data were passed to the aggregate. The xFinalize
-callback should invoke one of the <b>sqlite_set_result_...</b>
-interfaces to set the final result of the aggregate.
-</p>
-
-<p>
-SQLite now implements all of its built-in functions using this
-interface. For additional information and examples on how to create
-new SQL functions, review the SQLite source code in the file
-<b>func.c</b>.
-</p>
-
-<h3>5.0 Multi-Threading And SQLite</h3>
-
-<p>
-If SQLite is compiled with the THREADSAFE preprocessor macro set to 1,
-then it is safe to use SQLite from two or more threads of the same process
-at the same time. But each thread should have its own <b>sqlite*</b>
-pointer returned from <b>sqlite_open</b>. It is never safe for two
-or more threads to access the same <b>sqlite*</b> pointer at the same time.
-</p>
-
-<p>
-In precompiled SQLite libraries available on the website, the Unix
-versions are compiled with THREADSAFE turned off but the windows
-versions are compiled with THREADSAFE turned on. If you need something
-different that this you will have to recompile.
-</p>
-
-<p>
-Under Unix, an <b>sqlite*</b> pointer should not be carried across a
-<b>fork()</b> system call into the child process. The child process
-should open its own copy of the database after the <b>fork()</b>.
-</p>
-
-<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>
-}
-footer $rcsid
+++ /dev/null
-set rcsid {$Id: capi3.tcl,v 1.10 2007/04/27 17:16:22 drh Exp $}
-source common.tcl
-header {C/C++ Interface For SQLite Version 3}
-
-proc AddHyperlinks {txt} {
- regsub -all {([^:alnum:>])(sqlite3_\w+)(\([^\)]*\))} $txt \
- {\1<a href="capi3ref.html#\2">\2</a>\3} t2
- puts $t2
-}
-
-AddHyperlinks {
-<h2>C/C++ Interface For SQLite Version 3</h2>
-
-<h3>1.0 Overview</h3>
-
-<p>
-SQLite version 3.0 is a new version of SQLite, derived from
-the SQLite 2.8.13 code base, but with an incompatible file format
-and API.
-SQLite version 3.0 was created to answer demand for the following features:
-</p>
-
-<ul>
-<li>Support for UTF-16.</li>
-<li>User-definable text collating sequences.</li>
-<li>The ability to store BLOBs in indexed columns.</li>
-</ul>
-
-<p>
-It was necessary to move to version 3.0 to implement these features because
-each requires incompatible changes to the database file format. Other
-incompatible changes, such as a cleanup of the API, were introduced at the
-same time under the theory that it is best to get your incompatible changes
-out of the way all at once.
-</p>
-
-<p>
-The API for version 3.0 is similar to the version 2.X API,
-but with some important changes. Most noticeably, the "<tt>sqlite_</tt>"
-prefix that occurs on the beginning of all API functions and data
-structures are changed to "<tt>sqlite3_</tt>".
-This avoids confusion between the two APIs and allows linking against both
-SQLite 2.X and SQLite 3.0 at the same time.
-</p>
-
-<p>
-There is no agreement on what the C datatype for a UTF-16
-string should be. Therefore, SQLite uses a generic type of void*
-to refer to UTF-16 strings. Client software can cast the void*
-to whatever datatype is appropriate for their system.
-</p>
-
-<h3>2.0 C/C++ Interface</h3>
-
-<p>
-The API for SQLite 3.0 includes 83 separate functions in addition
-to several data structures and #defines. (A complete
-<a href="capi3ref.html">API reference</a> is provided as a separate document.)
-Fortunately, the interface is not nearly as complex as its size implies.
-Simple programs can still make do with only 3 functions:
-<a href="capi3ref.html#sqlite3_open">sqlite3_open()</a>,
-<a href="capi3ref.html#sqlite3_exec">sqlite3_exec()</a>, and
-<a href="capi3ref.html#sqlite3_close">sqlite3_close()</a>.
-More control over the execution of the database engine is provided
-using
-<a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a>
-to compile an SQLite statement into byte code and
-<a href="capi3ref.html#sqlite3_prepare">sqlite3_step()</a>
-to execute that bytecode.
-A family of routines with names beginning with
-<a href="capi3ref.html#sqlite3_column_blob">sqlite3_column_</a>
-is used to extract information about the result set of a query.
-Many interface functions come in pairs, with both a UTF-8 and
-UTF-16 version. And there is a collection of routines
-used to implement user-defined SQL functions and user-defined
-text collating sequences.
-</p>
-
-
-<h4>2.1 Opening and closing a database</h4>
-
-<blockquote><pre>
- typedef struct sqlite3 sqlite3;
- int sqlite3_open(const char*, sqlite3**);
- int sqlite3_open16(const void*, sqlite3**);
- int sqlite3_close(sqlite3*);
- const char *sqlite3_errmsg(sqlite3*);
- const void *sqlite3_errmsg16(sqlite3*);
- int sqlite3_errcode(sqlite3*);
-</pre></blockquote>
-
-<p>
-The sqlite3_open() routine returns an integer error code rather than
-a pointer to the sqlite3 structure as the version 2 interface did.
-The difference between sqlite3_open()
-and sqlite3_open16() is that sqlite3_open16() takes UTF-16 (in host native
-byte order) for the name of the database file. If a new database file
-needs to be created, then sqlite3_open16() sets the internal text
-representation to UTF-16 whereas sqlite3_open() sets the text
-representation to UTF-8.
-</p>
-
-<p>
-The opening and/or creating of the database file is deferred until the
-file is actually needed. This allows options and parameters, such
-as the native text representation and default page size, to be
-set using PRAGMA statements.
-</p>
-
-<p>
-The sqlite3_errcode() routine returns a result code for the most
-recent major API call. sqlite3_errmsg() returns an English-language
-text error message for the most recent error. The error message is
-represented in UTF-8 and will be ephemeral - it could disappear on
-the next call to any SQLite API function. sqlite3_errmsg16() works like
-sqlite3_errmsg() except that it returns the error message represented
-as UTF-16 in host native byte order.
-</p>
-
-<p>
-The error codes for SQLite version 3 are unchanged from version 2.
-They are as follows:
-</p>
-
-<blockquote><pre>
-#define SQLITE_OK 0 /* Successful result */
-#define SQLITE_ERROR 1 /* SQL error or missing database */
-#define SQLITE_INTERNAL 2 /* An internal logic error in SQLite */
-#define SQLITE_PERM 3 /* Access permission denied */
-#define SQLITE_ABORT 4 /* Callback routine requested an abort */
-#define SQLITE_BUSY 5 /* The database file is locked */
-#define SQLITE_LOCKED 6 /* A table in the database is locked */
-#define SQLITE_NOMEM 7 /* A malloc() failed */
-#define SQLITE_READONLY 8 /* Attempt to write a readonly database */
-#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite_interrupt() */
-#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
-#define SQLITE_CORRUPT 11 /* The database disk image is malformed */
-#define SQLITE_NOTFOUND 12 /* (Internal Only) Table or record not found */
-#define SQLITE_FULL 13 /* Insertion failed because database is full */
-#define SQLITE_CANTOPEN 14 /* Unable to open the database file */
-#define SQLITE_PROTOCOL 15 /* Database lock protocol error */
-#define SQLITE_EMPTY 16 /* (Internal Only) Database table is empty */
-#define SQLITE_SCHEMA 17 /* The database schema changed */
-#define SQLITE_TOOBIG 18 /* Too much data for one row of a table */
-#define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */
-#define SQLITE_MISMATCH 20 /* Data type mismatch */
-#define SQLITE_MISUSE 21 /* Library used incorrectly */
-#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
-#define SQLITE_AUTH 23 /* Authorization denied */
-#define SQLITE_ROW 100 /* sqlite_step() has another row ready */
-#define SQLITE_DONE 101 /* sqlite_step() has finished executing */
-</pre></blockquote>
-
-<h4>2.2 Executing SQL statements</h4>
-
-<blockquote><pre>
- typedef int (*sqlite_callback)(void*,int,char**, char**);
- int sqlite3_exec(sqlite3*, const char *sql, sqlite_callback, void*, char**);
-</pre></blockquote>
-
-<p>
-The sqlite3_exec function works much as it did in SQLite version 2.
-Zero or more SQL statements specified in the second parameter are compiled
-and executed. Query results are returned to a callback routine.
-See the <a href="capi3ref.html#sqlite3_exec">API reference</a> for additional
-information.
-</p>
-
-<p>
-In SQLite version 3, the sqlite3_exec routine is just a wrapper around
-calls to the prepared statement interface.
-</p>
-
-<blockquote><pre>
- typedef struct sqlite3_stmt sqlite3_stmt;
- int sqlite3_prepare(sqlite3*, const char*, int, sqlite3_stmt**, const char**);
- int sqlite3_prepare16(sqlite3*, const void*, int, sqlite3_stmt**, const void**);
- int sqlite3_finalize(sqlite3_stmt*);
- int sqlite3_reset(sqlite3_stmt*);
-</pre></blockquote>
-
-<p>
-The sqlite3_prepare interface compiles a single SQL statement into byte code
-for later execution. This interface is now the preferred way of accessing
-the database.
-</p>
-
-<p>
-The SQL statement is a UTF-8 string for sqlite3_prepare().
-The sqlite3_prepare16() works the same way except
-that it expects a UTF-16 string as SQL input.
-Only the first SQL statement in the input string is compiled.
-The fourth parameter is filled in with a pointer to the next (uncompiled)
-SQLite statement in the input string, if any.
-The sqlite3_finalize() routine deallocates a prepared SQL statement.
-All prepared statements must be finalized before the database can be
-closed.
-The sqlite3_reset() routine resets a prepared SQL statement so that it
-can be executed again.
-</p>
-
-<p>
-The SQL statement may contain tokens of the form "?" or "?nnn" or ":aaa"
-where "nnn" is an integer and "aaa" is an identifier.
-Such tokens represent unspecified literal values (or "wildcards")
-to be filled in later by the
-<a href="capi3ref.html#sqlite3_bind_blob">sqlite3_bind</a> interface.
-Each wildcard has an associated number which is its sequence in the
-statement or the "nnn" in the case of a "?nnn" form.
-It is allowed for the same wildcard
-to occur more than once in the same SQL statement, in which case
-all instance of that wildcard will be filled in with the same value.
-Unbound wildcards have a value of NULL.
-</p>
-
-<blockquote><pre>
- int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
- int sqlite3_bind_double(sqlite3_stmt*, int, double);
- int sqlite3_bind_int(sqlite3_stmt*, int, int);
- int sqlite3_bind_int64(sqlite3_stmt*, int, long long int);
- int sqlite3_bind_null(sqlite3_stmt*, int);
- int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
- int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
- int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
-</pre></blockquote>
-
-<p>
-There is an assortment of sqlite3_bind routines used to assign values
-to wildcards in a prepared SQL statement. Unbound wildcards
-are interpreted as NULLs. Bindings are not reset by sqlite3_reset().
-But wildcards can be rebound to new values after an sqlite3_reset().
-</p>
-
-<p>
-After an SQL statement has been prepared (and optionally bound), it
-is executed using:
-</p>
-
-<blockquote><pre>
- int sqlite3_step(sqlite3_stmt*);
-</pre></blockquote>
-
-<p>
-The sqlite3_step() routine return SQLITE_ROW if it is returning a single
-row of the result set, or SQLITE_DONE if execution has completed, either
-normally or due to an error. It might also return SQLITE_BUSY if it is
-unable to open the database file. If the return value is SQLITE_ROW, then
-the following routines can be used to extract information about that row
-of the result set:
-</p>
-
-<blockquote><pre>
- const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
- int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
- int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
- int sqlite3_column_count(sqlite3_stmt*);
- const char *sqlite3_column_decltype(sqlite3_stmt *, int iCol);
- const void *sqlite3_column_decltype16(sqlite3_stmt *, int iCol);
- double sqlite3_column_double(sqlite3_stmt*, int iCol);
- int sqlite3_column_int(sqlite3_stmt*, int iCol);
- long long int sqlite3_column_int64(sqlite3_stmt*, int iCol);
- const char *sqlite3_column_name(sqlite3_stmt*, int iCol);
- const void *sqlite3_column_name16(sqlite3_stmt*, int iCol);
- const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
- const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
- int sqlite3_column_type(sqlite3_stmt*, int iCol);
-</pre></blockquote>
-
-<p>
-The
-<a href="capi3ref.html#sqlite3_column_count">sqlite3_column_count()</a>
-function returns the number of columns in
-the results set. sqlite3_column_count() can be called at any time after
-sqlite3_prepare().
-<a href="capi3ref.html#sqlite3_data_count">sqlite3_data_count()</a>
-works similarly to
-sqlite3_column_count() except that it only works following sqlite3_step().
-If the previous call to sqlite3_step() returned SQLITE_DONE or an error code,
-then sqlite3_data_count() will return 0 whereas sqlite3_column_count() will
-continue to return the number of columns in the result set.
-</p>
-
-<p>Returned data is examined using the other sqlite3_column_***() functions,
-all of which take a column number as their second parameter. Columns are
-zero-indexed from left to right. Note that this is different to parameters,
-which are indexed starting at one.
-</p>
-
-<p>
-The sqlite3_column_type() function returns the
-datatype for the value in the Nth column. The return value is one
-of these:
-</p>
-
-<blockquote><pre>
- #define SQLITE_INTEGER 1
- #define SQLITE_FLOAT 2
- #define SQLITE_TEXT 3
- #define SQLITE_BLOB 4
- #define SQLITE_NULL 5
-</pre></blockquote>
-
-<p>
-The sqlite3_column_decltype() routine returns text which is the
-declared type of the column in the CREATE TABLE statement. For an
-expression, the return type is an empty string. sqlite3_column_name()
-returns the name of the Nth column. sqlite3_column_bytes() returns
-the number of bytes in a column that has type BLOB or the number of bytes
-in a TEXT string with UTF-8 encoding. sqlite3_column_bytes16() returns
-the same value for BLOBs but for TEXT strings returns the number of bytes
-in a UTF-16 encoding.
-sqlite3_column_blob() return BLOB data.
-sqlite3_column_text() return TEXT data as UTF-8.
-sqlite3_column_text16() return TEXT data as UTF-16.
-sqlite3_column_int() return INTEGER data in the host machines native
-integer format.
-sqlite3_column_int64() returns 64-bit INTEGER data.
-Finally, sqlite3_column_double() return floating point data.
-</p>
-
-<p>
-It is not necessary to retrieve data in the format specify by
-sqlite3_column_type(). If a different format is requested, the data
-is converted automatically.
-</p>
-
-<p>
-Data format conversions can invalidate the pointer returned by
-prior calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
-sqlite3_column_text16(). Pointers might be invalided in the following
-cases:
-</p>
-<ul>
-<li><p>
-The initial content is a BLOB and sqlite3_column_text()
-or sqlite3_column_text16()
-is called. A zero-terminator might need to be added to the string.
-</p></li>
-<li><p>
-The initial content is UTF-8 text and sqlite3_column_bytes16() or
-sqlite3_column_text16() is called. The content must be converted to UTF-16.
-</p></li>
-<li><p>
-The initial content is UTF-16 text and sqlite3_column_bytes() or
-sqlite3_column_text() is called. The content must be converted to UTF-8.
-</p></li>
-</ul>
-<p>
-Note that conversions between UTF-16be and UTF-16le
-are always done in place and do
-not invalidate a prior pointer, though of course the content of the buffer
-that the prior pointer points to will have been modified. Other kinds
-of conversion are done in place when it is possible, but sometime it is
-not possible and in those cases prior pointers are invalidated.
-</p>
-
-<p>
-The safest and easiest to remember policy is this: assume that any
-result from
-<ul>
-<li>sqlite3_column_blob(),</li>
-<li>sqlite3_column_text(), or</li>
-<li>sqlite3_column_text16()</li>
-</ul>
-is invalided by subsequent calls to
-<ul>
-<li>sqlite3_column_bytes(),</li>
-<li>sqlite3_column_bytes16(),</li>
-<li>sqlite3_column_text(), or</li>
-<li>sqlite3_column_text16().</li>
-</ul>
-This means that you should always call sqlite3_column_bytes() or
-sqlite3_column_bytes16() <u>before</u> calling sqlite3_column_blob(),
-sqlite3_column_text(), or sqlite3_column_text16().
-</p>
-
-<h4>2.3 User-defined functions</h4>
-
-<p>
-User defined functions can be created using the following routine:
-</p>
-
-<blockquote><pre>
- typedef struct sqlite3_value sqlite3_value;
- int sqlite3_create_function(
- sqlite3 *,
- const char *zFunctionName,
- int nArg,
- int eTextRep,
- void*,
- void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
- void (*xStep)(sqlite3_context*,int,sqlite3_value**),
- void (*xFinal)(sqlite3_context*)
- );
- int sqlite3_create_function16(
- sqlite3*,
- const void *zFunctionName,
- int nArg,
- int eTextRep,
- void*,
- void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
- void (*xStep)(sqlite3_context*,int,sqlite3_value**),
- void (*xFinal)(sqlite3_context*)
- );
- #define SQLITE_UTF8 1
- #define SQLITE_UTF16 2
- #define SQLITE_UTF16BE 3
- #define SQLITE_UTF16LE 4
- #define SQLITE_ANY 5
-</pre></blockquote>
-
-<p>
-The nArg parameter specifies the number of arguments to the function.
-A value of 0 indicates that any number of arguments is allowed. The
-eTextRep parameter specifies what representation text values are expected
-to be in for arguments to this function. The value of this parameter should
-be one of the parameters defined above. SQLite version 3 allows multiple
-implementations of the same function using different text representations.
-The database engine chooses the function that minimization the number
-of text conversions required.
-</p>
-
-<p>
-Normal functions specify only xFunc and leave xStep and xFinal set to NULL.
-Aggregate functions specify xStep and xFinal and leave xFunc set to NULL.
-There is no separate sqlite3_create_aggregate() API.
-</p>
-
-<p>
-The function name is specified in UTF-8. A separate sqlite3_create_function16()
-API works the same as sqlite_create_function()
-except that the function name is specified in UTF-16 host byte order.
-</p>
-
-<p>
-Notice that the parameters to functions are now pointers to sqlite3_value
-structures instead of pointers to strings as in SQLite version 2.X.
-The following routines are used to extract useful information from these
-"values":
-</p>
-
-<blockquote><pre>
- const void *sqlite3_value_blob(sqlite3_value*);
- int sqlite3_value_bytes(sqlite3_value*);
- int sqlite3_value_bytes16(sqlite3_value*);
- double sqlite3_value_double(sqlite3_value*);
- int sqlite3_value_int(sqlite3_value*);
- long long int sqlite3_value_int64(sqlite3_value*);
- const unsigned char *sqlite3_value_text(sqlite3_value*);
- const void *sqlite3_value_text16(sqlite3_value*);
- int sqlite3_value_type(sqlite3_value*);
-</pre></blockquote>
-
-<p>
-Function implementations use the following APIs to acquire context and
-to report results:
-</p>
-
-<blockquote><pre>
- void *sqlite3_aggregate_context(sqlite3_context*, int nbyte);
- void *sqlite3_user_data(sqlite3_context*);
- void sqlite3_result_blob(sqlite3_context*, const void*, int n, void(*)(void*));
- void sqlite3_result_double(sqlite3_context*, double);
- void sqlite3_result_error(sqlite3_context*, const char*, int);
- void sqlite3_result_error16(sqlite3_context*, const void*, int);
- void sqlite3_result_int(sqlite3_context*, int);
- void sqlite3_result_int64(sqlite3_context*, long long int);
- void sqlite3_result_null(sqlite3_context*);
- void sqlite3_result_text(sqlite3_context*, const char*, int n, void(*)(void*));
- void sqlite3_result_text16(sqlite3_context*, const void*, int n, void(*)(void*));
- void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
- void *sqlite3_get_auxdata(sqlite3_context*, int);
- void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*));
-</pre></blockquote>
-
-<h4>2.4 User-defined collating sequences</h4>
-
-<p>
-The following routines are used to implement user-defined
-collating sequences:
-</p>
-
-<blockquote><pre>
- sqlite3_create_collation(sqlite3*, const char *zName, int eTextRep, void*,
- int(*xCompare)(void*,int,const void*,int,const void*));
- sqlite3_create_collation16(sqlite3*, const void *zName, int eTextRep, void*,
- int(*xCompare)(void*,int,const void*,int,const void*));
- sqlite3_collation_needed(sqlite3*, void*,
- void(*)(void*,sqlite3*,int eTextRep,const char*));
- sqlite3_collation_needed16(sqlite3*, void*,
- void(*)(void*,sqlite3*,int eTextRep,const void*));
-</pre></blockquote>
-
-<p>
-The sqlite3_create_collation() function specifies a collating sequence name
-and a comparison function to implement that collating sequence. The
-comparison function is only used for comparing text values. The eTextRep
-parameter is one of SQLITE_UTF8, SQLITE_UTF16LE, SQLITE_UTF16BE, or
-SQLITE_ANY to specify which text representation the comparison function works
-with. Separate comparison functions can exist for the same collating
-sequence for each of the UTF-8, UTF-16LE and UTF-16BE text representations.
-The sqlite3_create_collation16() works like sqlite3_create_collation() except
-that the collation name is specified in UTF-16 host byte order instead of
-in UTF-8.
-</p>
-
-<p>
-The sqlite3_collation_needed() routine registers a callback which the
-database engine will invoke if it encounters an unknown collating sequence.
-The callback can lookup an appropriate comparison function and invoke
-sqlite_3_create_collation() as needed. The fourth parameter to the callback
-is the name of the collating sequence in UTF-8. For sqlite3_collation_need16()
-the callback sends the collating sequence name in UTF-16 host byte order.
-</p>
-}
-footer $rcsid
+++ /dev/null
-set rcsid {$Id: capi3ref.tcl,v 1.60 2007/05/19 06:48:43 danielk1977 Exp $}
-source common.tcl
-header {C/C++ Interface For SQLite Version 3}
-puts {
-<h2 class=pdf_section>C/C++ Interface For SQLite Version 3</h2>
-}
-
-proc api {name prototype desc {notused x}} {
- global apilist specialname
- if {$name==""} {
- regsub -all {sqlite3_[a-z0-9_]+\(} $prototype \
- {[lappend name [string trimright & (]]} x1
- subst $x1
- } else {
- lappend specialname $name
- }
- lappend apilist [list $name $prototype $desc]
-}
-
-api {extended-result-codes} {
-#define SQLITE_IOERR_READ
-#define SQLITE_IOERR_SHORT_READ
-#define SQLITE_IOERR_WRITE
-#define SQLITE_IOERR_FSYNC
-#define SQLITE_IOERR_DIR_FSYNC
-#define SQLITE_IOERR_TRUNCATE
-#define SQLITE_IOERR_FSTAT
-#define SQLITE_IOERR_UNLOCK
-#define SQLITE_IOERR_RDLOCK
-...
-} {
-In its default configuration, SQLite API routines return one of 26 integer
-result codes described at result-codes. However, experience has shown that
-many of these result codes are too course-grained. They do not provide as
-much information about problems as users might like. In an effort to
-address this, newer versions of SQLite (version 3.3.8 and later) include
-support for additional result codes that provide more detailed information
-about errors. The extended result codes are enabled (or disabled) for
-each database
-connection using the sqlite3_extended_result_codes() API.
-
-Some of the available extended result codes are listed above.
-We expect the number of extended result codes will be expand
-over time. Software that uses extended result codes should expect
-to see new result codes in future releases of SQLite.
-
-The symbolic name for an extended result code always contains a related
-primary result code as a prefix. Primary result codes contain a single
-"_" character. Extended result codes contain two or more "_" characters.
-The numeric value of an extended result code can be converted to its
-corresponding primary result code by masking off the lower 8 bytes.
-
-A complete list of available extended result codes and
-details about the meaning of the various extended result codes can be
-found by consulting the C code, especially the sqlite3.h header
-file and its antecedent sqlite.h.in. Additional information
-is also available at the SQLite wiki:
-http://www.sqlite.org/cvstrac/wiki?p=ExtendedResultCodes
-}
-
-
-api {result-codes} {
-#define SQLITE_OK 0 /* Successful result */
-#define SQLITE_ERROR 1 /* SQL error or missing database */
-#define SQLITE_INTERNAL 2 /* An internal logic error in SQLite */
-#define SQLITE_PERM 3 /* Access permission denied */
-#define SQLITE_ABORT 4 /* Callback routine requested an abort */
-#define SQLITE_BUSY 5 /* The database file is locked */
-#define SQLITE_LOCKED 6 /* A table in the database is locked */
-#define SQLITE_NOMEM 7 /* A malloc() failed */
-#define SQLITE_READONLY 8 /* Attempt to write a readonly database */
-#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite_interrupt() */
-#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
-#define SQLITE_CORRUPT 11 /* The database disk image is malformed */
-#define SQLITE_NOTFOUND 12 /* (Internal Only) Table or record not found */
-#define SQLITE_FULL 13 /* Insertion failed because database is full */
-#define SQLITE_CANTOPEN 14 /* Unable to open the database file */
-#define SQLITE_PROTOCOL 15 /* Database lock protocol error */
-#define SQLITE_EMPTY 16 /* (Internal Only) Database table is empty */
-#define SQLITE_SCHEMA 17 /* The database schema changed */
-#define SQLITE_TOOBIG 18 /* Too much data for one row of a table */
-#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */
-#define SQLITE_MISMATCH 20 /* Data type mismatch */
-#define SQLITE_MISUSE 21 /* Library used incorrectly */
-#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
-#define SQLITE_AUTH 23 /* Authorization denied */
-#define SQLITE_ROW 100 /* sqlite_step() has another row ready */
-#define SQLITE_DONE 101 /* sqlite_step() has finished executing */
-} {
-Many SQLite functions return an integer result code from the set shown
-above in order to indicates success or failure.
-
-The result codes above are the only ones returned by SQLite in its
-default configuration. However, the sqlite3_extended_result_codes()
-API can be used to set a database connectoin to return more detailed
-result codes. See the documentation on sqlite3_extended_result_codes()
-or extended-result-codes for additional information.
-}
-
-api {} {
- int sqlite3_extended_result_codes(sqlite3*, int onoff);
-} {
-This routine enables or disabled extended-result-codes feature.
-By default, SQLite API routines return one of only 26 integer
-result codes described at result-codes. When extended result codes
-are enabled by this routine, the repetoire of result codes can be
-much larger and can (hopefully) provide more detailed information
-about the cause of an error.
-
-The second argument is a boolean value that turns extended result
-codes on and off. Extended result codes are off by default for
-backwards compatibility with older versions of SQLite.
-}
-
-api {} {
- const char *sqlite3_libversion(void);
-} {
- Return a pointer to a string which contains the version number of
- the library. The same string is available in the global
- variable named "sqlite3_version". This interface is provided since
- windows is unable to access global variables in DLLs.
-}
-
-api {} {
- void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
-} {
- Aggregate functions use this routine to allocate
- a structure for storing their state. The first time this routine
- is called for a particular aggregate, a new structure of size nBytes
- is allocated, zeroed, and returned. On subsequent calls (for the
- same aggregate instance) the same buffer is returned. The implementation
- of the aggregate can use the returned buffer to accumulate data.
-
- The buffer is freed automatically by SQLite when the query that
- invoked the aggregate function terminates.
-}
-
-api {} {
- int sqlite3_aggregate_count(sqlite3_context*);
-} {
- This function is deprecated. It continues to exist so as not to
- break any legacy code that might happen to use it. But it should not
- be used in any new code.
-
- In order to encourage people to not use this function, we are not going
- to tell you what it does.
-}
-
-api {} {
- int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
- int sqlite3_bind_double(sqlite3_stmt*, int, double);
- int sqlite3_bind_int(sqlite3_stmt*, int, int);
- int sqlite3_bind_int64(sqlite3_stmt*, int, long long int);
- int sqlite3_bind_null(sqlite3_stmt*, int);
- int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
- int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
- #define SQLITE_STATIC ((void(*)(void *))0)
- #define SQLITE_TRANSIENT ((void(*)(void *))-1)
-} {
- In the SQL strings input to sqlite3_prepare_v2() and sqlite3_prepare16_v2(),
- one or more literals can be replace by a parameter "?" or "?NNN"
- or ":AAA" or "@AAA" or "\$VVV" where NNN is an integer literal,
- AAA is an alphanumeric identifier and VVV is a variable name according
- to the syntax rules of the TCL programming language.
- The values of these parameters (also called "host parameter names")
- can be set using the sqlite3_bind_*() routines.
-
- The first argument to the sqlite3_bind_*() routines always is a pointer
- to the sqlite3_stmt structure returned from sqlite3_prepare_v2(). The second
- argument is the index of the parameter to be set. The first parameter has
- an index of 1. When the same named parameter is used more than once, second
- and subsequent
- occurrences have the same index as the first occurrence. The index for
- named parameters can be looked up using the
- sqlite3_bind_parameter_name() API if desired. The index for "?NNN"
- parametes is the value of NNN. The NNN value must be between 1 and 999.
-
-
- The third argument is the value to bind to the parameter.
-
- In those
- routines that have a fourth argument, its value is the number of bytes
- in the parameter. To be clear: the value is the number of bytes in the
- string, not the number of characters. The number
- of bytes does not include the zero-terminator at the end of strings.
- If the fourth parameter is negative, the length of the string is
- number of bytes up to the first zero terminator.
-
- The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
- sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
- text after SQLite has finished with it. If the fifth argument is the
- special value SQLITE_STATIC, then the library assumes that the information
- is in static, unmanaged space and does not need to be freed. If the
- fifth argument has the value SQLITE_TRANSIENT, then SQLite makes its
- own private copy of the data immediately, before the sqlite3_bind_*()
- routine returns.
-
- The sqlite3_bind_*() routines must be called after
- sqlite3_prepare_v2() or sqlite3_reset() and before sqlite3_step().
- Bindings are not cleared by the sqlite3_reset() routine.
- Unbound parameters are interpreted as NULL.
-
- These routines return SQLITE_OK on success or an error code if
- anything goes wrong. SQLITE_RANGE is returned if the parameter
- index is out of range. SQLITE_NOMEM is returned if malloc fails.
- SQLITE_MISUSE is returned if these routines are called on a virtual
- machine that is the wrong state or which has already been finalized.
-}
-
-api {} {
- int sqlite3_bind_parameter_count(sqlite3_stmt*);
-} {
- Return the number of parameters in the precompiled statement given as
- the argument.
-}
-
-api {} {
- const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int n);
-} {
- Return the name of the n-th parameter in the precompiled statement.
- Parameters of the form ":AAA" or "@AAA" or "\$VVV" have a name which is the
- string ":AAA" or "@AAA" or "\$VVV".
- In other words, the initial ":" or "$" or "@"
- is included as part of the name.
- Parameters of the form "?" or "?NNN" have no name.
-
- The first bound parameter has an index of 1, not 0.
-
- If the value n is out of range or if the n-th parameter is nameless,
- then NULL is returned. The returned string is always in the
- UTF-8 encoding even if the named parameter was originally specified
- as UTF-16 in sqlite3_prepare16_v2().
-}
-
-api {} {
- int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
-} {
- Return the index of the parameter with the given name.
- The name must match exactly.
- If there is no parameter with the given name, return 0.
- The string zName is always in the UTF-8 encoding.
-}
-
-api {} {
- int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
-} {
- This routine identifies a callback function that might be invoked
- whenever an attempt is made to open a database table
- that another thread or process has locked.
- If the busy callback is NULL, then SQLITE_BUSY is returned immediately
- upon encountering the lock.
- If the busy callback is not NULL, then the
- callback will be invoked with two arguments. The
- first argument to the handler is a copy of the void* pointer which
- is the third argument to this routine. The second argument to
- the handler is the number of times that the busy handler has
- been invoked for this locking event. If the
- busy callback returns 0, then no additional attempts are made to
- access the database and SQLITE_BUSY is returned.
- If the callback returns non-zero, then another attempt is made to open the
- database for reading and the cycle repeats.
-
- The presence of a busy handler does not guarantee that
- it will be invoked when there is lock contention.
- If SQLite determines that invoking the busy handler could result in
- a deadlock, it will return SQLITE_BUSY instead.
- Consider a scenario where one process is holding a read lock that
- it is trying to promote to a reserved lock and
- a second process is holding a reserved lock that it is trying
- to promote to an exclusive lock. The first process cannot proceed
- because it is blocked by the second and the second process cannot
- proceed because it is blocked by the first. If both processes
- invoke the busy handlers, neither will make any progress. Therefore,
- SQLite returns SQLITE_BUSY for the first process, hoping that this
- will induce the first process to release its read lock and allow
- the second process to proceed.
-
- The default busy callback is NULL.
-
- Sqlite is re-entrant, so the busy handler may start a new query.
- (It is not clear why anyone would every want to do this, but it
- is allowed, in theory.) But the busy handler may not close the
- database. Closing the database from a busy handler will delete
- data structures out from under the executing query and will
- probably result in a coredump.
-
- There can only be a single busy handler defined for each database
- connection. Setting a new busy handler clears any previous one.
- Note that calling sqlite3_busy_timeout() will also set or clear
- the busy handler.
-}
-
-api {} {
- int sqlite3_busy_timeout(sqlite3*, int ms);
-} {
- This routine sets a busy handler that sleeps for a while when a
- table is locked. The handler will sleep multiple times until
- at least "ms" milliseconds of sleeping have been done. After
- "ms" milliseconds of sleeping, the handler returns 0 which
- causes sqlite3_exec() to return SQLITE_BUSY.
-
- Calling this routine with an argument less than or equal to zero
- turns off all busy handlers.
-
- There can only be a single busy handler for a particular database
- connection. If another busy handler was defined
- (using sqlite3_busy_handler()) prior to calling
- this routine, that other busy handler is cleared.
-}
-
-api {} {
- int sqlite3_changes(sqlite3*);
-} {
- This function returns the number of database rows that were changed
- (or inserted or deleted) by the most recently completed
- INSERT, UPDATE, or DELETE
- statement. Only changes that are directly specified by the INSERT,
- UPDATE, or DELETE statement are counted. Auxiliary changes caused by
- triggers are not counted. Use the sqlite3_total_changes() function
- to find the total number of changes including changes caused by triggers.
-
- Within the body of a trigger, the sqlite3_changes() function does work
- to report the number of rows that were changed for the most recently
- completed INSERT, UPDATE, or DELETE statement within the trigger body.
-
- SQLite implements the command "DELETE FROM table" without a WHERE clause
- by dropping and recreating the table. (This is much faster than going
- through and deleting individual elements from the table.) Because of
- this optimization, the change count for "DELETE FROM table" will be
- zero regardless of the number of elements that were originally in the
- table. To get an accurate count of the number of rows deleted, use
- "DELETE FROM table WHERE 1" instead.
-}
-
-api {} {
- int sqlite3_total_changes(sqlite3*);
-} {
- This function returns the total number of database rows that have
- be modified, inserted, or deleted since the database connection was
- created using sqlite3_open(). All changes are counted, including
- changes by triggers and changes to TEMP and auxiliary databases.
- Except, changes to the SQLITE_MASTER table (caused by statements
- such as CREATE TABLE) are not counted. Nor are changes counted when
- an entire table is deleted using DROP TABLE.
-
- See also the sqlite3_changes() API.
-
- SQLite implements the command "DELETE FROM table" without a WHERE clause
- by dropping and recreating the table. (This is much faster than going
- through and deleting individual elements form the table.) Because of
- this optimization, the change count for "DELETE FROM table" will be
- zero regardless of the number of elements that were originally in the
- table. To get an accurate count of the number of rows deleted, use
- "DELETE FROM table WHERE 1" instead.
-}
-
-api {} {
- int sqlite3_close(sqlite3*);
-} {
- Call this function with a pointer to a structure that was previously
- returned from sqlite3_open() or sqlite3_open16()
- and the corresponding database will by closed.
-
- SQLITE_OK is returned if the close is successful. If there are
- prepared statements that have not been finalized, then SQLITE_BUSY
- is returned. SQLITE_ERROR might be returned if the argument is not
- a valid connection pointer returned by sqlite3_open() or if the connection
- pointer has been closed previously.
-}
-
-api {} {
-const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
-int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
-int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
-double sqlite3_column_double(sqlite3_stmt*, int iCol);
-int sqlite3_column_int(sqlite3_stmt*, int iCol);
-long long int sqlite3_column_int64(sqlite3_stmt*, int iCol);
-const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
-const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
-int sqlite3_column_type(sqlite3_stmt*, int iCol);
-#define SQLITE_INTEGER 1
-#define SQLITE_FLOAT 2
-#define SQLITE_TEXT 3
-#define SQLITE_BLOB 4
-#define SQLITE_NULL 5
-} {
- These routines return information about the information
- in a single column of the current result row of a query. In every
- case the first argument is a pointer to the SQL statement that is being
- executed (the sqlite_stmt* that was returned from sqlite3_prepare_v2()) and
- the second argument is the index of the column for which information
- should be returned. iCol is zero-indexed. The left-most column has an
- index of 0.
-
- If the SQL statement is not currently point to a valid row, or if the
- the column index is out of range, the result is undefined.
-
- The sqlite3_column_type() routine returns the initial data type
- of the result column. The returned value is one of SQLITE_INTEGER,
- SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB, or SQLITE_NULL. The value
- returned by sqlite3_column_type() is only meaningful if no type
- conversions have occurred as described below. After a type conversion,
- the value returned by sqlite3_column_type() is undefined. Future
- versions of SQLite may change the behavior of sqlite3_column_type()
- following a type conversion.
-
- If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
- routine returns the number of bytes in that BLOB or string.
- If the result is a UTF-16 string, then sqlite3_column_bytes() converts
- the string to UTF-8 and then returns the number of bytes.
- If the result is a numeric value then sqlite3_column_bytes() uses
- sqlite3_snprintf() to convert that value to a UTF-8 string and returns
- the number of bytes in that string.
- The value returned does
- not include the \\000 terminator at the end of the string.
-
- The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
- but leaves the result in UTF-16 instead of UTF-8.
- The \\u0000 terminator is not included in this count.
-
- These routines attempt to convert the value where appropriate. For
- example, if the internal representation is FLOAT and a text result
- is requested, sqlite3_snprintf() is used internally to do the conversion
- automatically. The following table details the conversions that
- are applied:
-
-<blockquote>
-<table border="1">
-<tr><th>Internal Type</th><th>Requested Type</th><th>Conversion</th></tr>
-<tr><td> NULL </td><td> INTEGER</td><td>Result is 0</td></tr>
-<tr><td> NULL </td><td> FLOAT </td><td> Result is 0.0</td></tr>
-<tr><td> NULL </td><td> TEXT </td><td> Result is NULL pointer</td></tr>
-<tr><td> NULL </td><td> BLOB </td><td> Result is NULL pointer</td></tr>
-<tr><td> INTEGER </td><td> FLOAT </td><td> Convert from integer to float</td></tr>
-<tr><td> INTEGER </td><td> TEXT </td><td> ASCII rendering of the integer</td></tr>
-<tr><td> INTEGER </td><td> BLOB </td><td> Same as for INTEGER->TEXT</td></tr>
-<tr><td> FLOAT </td><td> INTEGER</td><td>Convert from float to integer</td></tr>
-<tr><td> FLOAT </td><td> TEXT </td><td> ASCII rendering of the float</td></tr>
-<tr><td> FLOAT </td><td> BLOB </td><td> Same as FLOAT->TEXT</td></tr>
-<tr><td> TEXT </td><td> INTEGER</td><td>Use atoi()</td></tr>
-<tr><td> TEXT </td><td> FLOAT </td><td> Use atof()</td></tr>
-<tr><td> TEXT </td><td> BLOB </td><td> No change</td></tr>
-<tr><td> BLOB </td><td> INTEGER</td><td>Convert to TEXT then use atoi()</td></tr>
-<tr><td> BLOB </td><td> FLOAT </td><td> Convert to TEXT then use atof()</td></tr>
-<tr><td> BLOB </td><td> TEXT </td><td> Add a \\000 terminator if needed</td></tr>
-</table>
-</blockquote>
-
- Note that when type conversions occur, pointers returned by prior
- calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
- sqlite3_column_text16() may be invalidated.
- Type conversions and pointer invalidations might occur
- in the following cases:
-
- <ul>
- <li><p>
- The initial content is a BLOB and sqlite3_column_text()
- or sqlite3_column_text16()
- is called. A zero-terminator might need to be added to the string.
- </p></li>
- <li><p>
- The initial content is UTF-8 text and sqlite3_column_bytes16() or
- sqlite3_column_text16() is called. The content must be converted to UTF-16.
- </p></li>
- <li><p>
- The initial content is UTF-16 text and sqlite3_column_bytes() or
- sqlite3_column_text() is called. The content must be converted to UTF-8.
- </p></li>
- </ul>
-
- Conversions between UTF-16be and UTF-16le
- are always done in place and do
- not invalidate a prior pointer, though of course the content of the buffer
- that the prior pointer points to will have been modified. Other kinds
- of conversion are done in place when it is possible, but sometime it is
- not possible and in those cases prior pointers are invalidated.
-
- The safest and easiest to remember policy is to invoke these routines
- in one of the following ways:
-
- <ul>
- <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
- <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
- <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
- </ul>
-
- In other words, you should call sqlite3_column_text(), sqlite3_column_blob(),
- or sqlite3_column_text16() first to force the result into the desired
- format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to
- find the size of the result. Do not mix call to sqlite3_column_text() or
- sqlite3_column_blob() with calls to sqlite3_column_bytes16(). And do not
- mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes().
-}
-
-api {} {
-int sqlite3_column_count(sqlite3_stmt *pStmt);
-} {
- Return the number of columns in the result set returned by the prepared
- SQL statement. This routine returns 0 if pStmt is an SQL statement
- that does not return data (for example an UPDATE).
-
- See also sqlite3_data_count().
-}
-
-api {} {
-const char *sqlite3_column_decltype(sqlite3_stmt *, int i);
-const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
-} {
- The first argument is a prepared SQL statement. If this statement
- is a SELECT statement, the Nth column of the returned result set
- of the SELECT is a table column then the declared type of the table
- column is returned. If the Nth column of the result set is not a table
- column, then a NULL pointer is returned. The returned string is
- UTF-8 encoded for sqlite3_column_decltype() and UTF-16 encoded
- for sqlite3_column_decltype16(). For example, in the database schema:
-
- <blockquote><pre>
- CREATE TABLE t1(c1 INTEGER);
- </pre></blockquote>
-
- And the following statement compiled:
-
- <blockquote><pre>
- SELECT c1 + 1, c1 FROM t1;
- </pre></blockquote>
-
- Then this routine would return the string "INTEGER" for the second
- result column (i==1), and a NULL pointer for the first result column
- (i==0).
-
- If the following statements were compiled then this routine would
- return "INTEGER" for the first (only) result column.
-
- <blockquote><pre>
- SELECT (SELECT c1) FROM t1;
- SELECT (SELECT c1 FROM t1);
- SELECT c1 FROM (SELECT c1 FROM t1);
- SELECT * FROM (SELECT c1 FROM t1);
- SELECT * FROM (SELECT * FROM t1);
- </pre></blockquote>
-}
-
-api {} {
- int sqlite3_table_column_metadata(
- sqlite3 *db, /* Connection handle */
- const char *zDbName, /* Database name or NULL */
- const char *zTableName, /* Table name */
- const char *zColumnName, /* Column name */
- char const **pzDataType, /* OUTPUT: Declared data type */
- char const **pzCollSeq, /* OUTPUT: Collation sequence name */
- int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */
- int *pPrimaryKey, /* OUTPUT: True if column part of PK */
- int *pAutoinc /* OUTPUT: True if colums is auto-increment */
- );
-} {
- This routine is used to obtain meta information about a specific column of a
- specific database table accessible using the connection handle passed as the
- first function argument.
-
- The column is identified by the second, third and fourth parameters to
- this function. The second parameter is either the name of the database
- (i.e. "main", "temp" or an attached database) containing the specified
- table or NULL. If it is NULL, then all attached databases are searched
- for the table using the same algorithm as the database engine uses to
- resolve unqualified table references.
-
- The third and fourth parameters to this function are the table and column
- name of the desired column, respectively. Neither of these parameters
- may be NULL.
-
- Meta information is returned by writing to the memory locations passed as
- the 5th and subsequent parameters to this function. Any of these
- arguments may be NULL, in which case the corresponding element of meta
- information is ommitted.
-
-<pre>
- Parameter Output Type Description
- -----------------------------------
- 5th const char* Declared data type
- 6th const char* Name of the columns default collation sequence
- 7th int True if the column has a NOT NULL constraint
- 8th int True if the column is part of the PRIMARY KEY
- 9th int True if the column is AUTOINCREMENT
-</pre>
-
- The memory pointed to by the character pointers returned for the
- declaration type and collation sequence is valid only until the next
- call to any sqlite API function.
-
- This function may load one or more schemas from database files. If an
- error occurs during this process, or if the requested table or column
- cannot be found, an SQLITE error code is returned and an error message
- left in the database handle (to be retrieved using sqlite3_errmsg()).
- Specifying an SQL view instead of a table as the third argument is also
- considered an error.
-
- If the specified column is "rowid", "oid" or "_rowid_" and an
- INTEGER PRIMARY KEY column has been explicitly declared, then the output
- parameters are set for the explicitly declared column. If there is no
- explicitly declared IPK column, then the data-type is "INTEGER", the
- collation sequence "BINARY" and the primary-key flag is set. Both
- the not-null and auto-increment flags are clear.
-
- This API is only available if the library was compiled with the
- SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
-}
-
-api {} {
-const char *sqlite3_column_database_name(sqlite3_stmt *pStmt, int N);
-const void *sqlite3_column_database_name16(sqlite3_stmt *pStmt, int N);
-} {
-If the Nth column returned by statement pStmt is a column reference,
-these functions may be used to access the name of the database (either
-"main", "temp" or the name of an attached database) that contains
-the column. If the Nth column is not a column reference, NULL is
-returned.
-
-See the description of function sqlite3_column_decltype() for a
-description of exactly which expressions are considered column references.
-
-Function sqlite3_column_database_name() returns a pointer to a UTF-8
-encoded string. sqlite3_column_database_name16() returns a pointer
-to a UTF-16 encoded string.
-}
-
-api {} {
-const char *sqlite3_column_origin_name(sqlite3_stmt *pStmt, int N);
-const void *sqlite3_column_origin_name16(sqlite3_stmt *pStmt, int N);
-} {
-If the Nth column returned by statement pStmt is a column reference,
-these functions may be used to access the schema name of the referenced
-column in the database schema. If the Nth column is not a column
-reference, NULL is returned.
-
-See the description of function sqlite3_column_decltype() for a
-description of exactly which expressions are considered column references.
-
-Function sqlite3_column_origin_name() returns a pointer to a UTF-8
-encoded string. sqlite3_column_origin_name16() returns a pointer
-to a UTF-16 encoded string.
-}
-
-api {} {
-const char *sqlite3_column_table_name(sqlite3_stmt *pStmt, int N);
-const void *sqlite3_column_table_name16(sqlite3_stmt *pStmt, int N);
-} {
-If the Nth column returned by statement pStmt is a column reference,
-these functions may be used to access the name of the table that
-contains the column. If the Nth column is not a column reference,
-NULL is returned.
-
-See the description of function sqlite3_column_decltype() for a
-description of exactly which expressions are considered column references.
-
-Function sqlite3_column_table_name() returns a pointer to a UTF-8
-encoded string. sqlite3_column_table_name16() returns a pointer
-to a UTF-16 encoded string.
-}
-
-api {} {
-const char *sqlite3_column_name(sqlite3_stmt*,int);
-const void *sqlite3_column_name16(sqlite3_stmt*,int);
-} {
- The first argument is a prepared SQL statement. This function returns
- the column heading for the Nth column of that statement, where N is the
- second function argument. The string returned is UTF-8 for
- sqlite3_column_name() and UTF-16 for sqlite3_column_name16().
-}
-
-api {} {
-void *sqlite3_commit_hook(sqlite3*, int(*xCallback)(void*), void *pArg);
-} {
- <i>Experimental</i>
-
- Register a callback function to be invoked whenever a new transaction
- is committed. The pArg argument is passed through to the callback.
- callback. If the callback function returns non-zero, then the commit
- is converted into a rollback.
-
- If another function was previously registered, its pArg value is returned.
- Otherwise NULL is returned.
-
- Registering a NULL function disables the callback. Only a single commit
- hook callback can be registered at a time.
-}
-
-api {} {
-int sqlite3_complete(const char *sql);
-int sqlite3_complete16(const void *sql);
-} {
- These functions return true if the given input string comprises
- one or more complete SQL statements.
- The argument must be a nul-terminated UTF-8 string for sqlite3_complete()
- and a nul-terminated UTF-16 string for sqlite3_complete16().
-
- These routines do not check to see if the SQL statement is well-formed.
- They only check to see that the statement is terminated by a semicolon
- that is not part of a string literal and is not inside
- the body of a trigger.
-} {}
-
-api {} {
-int sqlite3_create_collation(
- sqlite3*,
- const char *zName,
- int pref16,
- void*,
- int(*xCompare)(void*,int,const void*,int,const void*)
-);
-int sqlite3_create_collation16(
- sqlite3*,
- const char *zName,
- int pref16,
- void*,
- int(*xCompare)(void*,int,const void*,int,const void*)
-);
-#define SQLITE_UTF8 1
-#define SQLITE_UTF16BE 2
-#define SQLITE_UTF16LE 3
-#define SQLITE_UTF16 4
-} {
- These two functions are used to add new collation sequences to the
- sqlite3 handle specified as the first argument.
-
- The name of the new collation sequence is specified as a UTF-8 string
- for sqlite3_create_collation() and a UTF-16 string for
- sqlite3_create_collation16(). In both cases the name is passed as the
- second function argument.
-
- The third argument must be one of the constants SQLITE_UTF8,
- SQLITE_UTF16LE or SQLITE_UTF16BE, indicating that the user-supplied
- routine expects to be passed pointers to strings encoded using UTF-8,
- UTF-16 little-endian or UTF-16 big-endian respectively. The
- SQLITE_UTF16 constant indicates that text strings are expected in
- UTF-16 in the native byte order of the host machine.
-
- A pointer to the user supplied routine must be passed as the fifth
- argument. If it is NULL, this is the same as deleting the collation
- sequence (so that SQLite cannot call it anymore). Each time the user
- supplied function is invoked, it is passed a copy of the void* passed as
- the fourth argument to sqlite3_create_collation() or
- sqlite3_create_collation16() as its first argument.
-
- The remaining arguments to the user-supplied routine are two strings,
- each represented by a [length, data] pair and encoded in the encoding
- that was passed as the third argument when the collation sequence was
- registered. The user routine should return negative, zero or positive if
- the first string is less than, equal to, or greater than the second
- string. i.e. (STRING1 - STRING2).
-}
-
-api {} {
-int sqlite3_collation_needed(
- sqlite3*,
- void*,
- void(*)(void*,sqlite3*,int eTextRep,const char*)
-);
-int sqlite3_collation_needed16(
- sqlite3*,
- void*,
- void(*)(void*,sqlite3*,int eTextRep,const void*)
-);
-} {
- To avoid having to register all collation sequences before a database
- can be used, a single callback function may be registered with the
- database handle to be called whenever an undefined collation sequence is
- required.
-
- If the function is registered using the sqlite3_collation_needed() API,
- then it is passed the names of undefined collation sequences as strings
- encoded in UTF-8. If sqlite3_collation_needed16() is used, the names
- are passed as UTF-16 in machine native byte order. A call to either
- function replaces any existing callback.
-
- When the user-function is invoked, the first argument passed is a copy
- of the second argument to sqlite3_collation_needed() or
- sqlite3_collation_needed16(). The second argument is the database
- handle. The third argument is one of SQLITE_UTF8, SQLITE_UTF16BE or
- SQLITE_UTF16LE, indicating the most desirable form of the collation
- sequence function required. The fourth argument is the name of the
- required collation sequence.
-
- The collation sequence is returned to SQLite by a collation-needed
- callback using the sqlite3_create_collation() or
- sqlite3_create_collation16() APIs, described above.
-}
-
-api {} {
-int sqlite3_create_function(
- sqlite3 *,
- const char *zFunctionName,
- int nArg,
- int eTextRep,
- void *pUserData,
- void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
- void (*xStep)(sqlite3_context*,int,sqlite3_value**),
- void (*xFinal)(sqlite3_context*)
-);
-int sqlite3_create_function16(
- sqlite3*,
- const void *zFunctionName,
- int nArg,
- int eTextRep,
- void *pUserData,
- void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
- void (*xStep)(sqlite3_context*,int,sqlite3_value**),
- void (*xFinal)(sqlite3_context*)
-);
-#define SQLITE_UTF8 1
-#define SQLITE_UTF16 2
-#define SQLITE_UTF16BE 3
-#define SQLITE_UTF16LE 4
-#define SQLITE_ANY 5
-} {
- These two functions are used to add SQL functions or aggregates
- implemented in C. The
- only difference between these two routines is that the second argument, the
- name of the (scalar) function or aggregate, is encoded in UTF-8 for
- sqlite3_create_function() and UTF-16 for sqlite3_create_function16().
- The length of the name is limited to 255 bytes, exclusive of the
- zero-terminator. Note that the name length limit is in bytes, not
- characters. Any attempt to create a function with a longer name
- will result in an SQLITE_ERROR error.
-
- The first argument is the database handle that the new function or
- aggregate is to be added to. If a single program uses more than one
- database handle internally, then user functions or aggregates must
- be added individually to each database handle with which they will be
- used.
-
- The third argument is the number of arguments that the function or
- aggregate takes. If this argument is -1 then the function or
- aggregate may take any number of arguments. The maximum number
- of arguments to a new SQL function is 127. A number larger than
- 127 for the third argument results in an SQLITE_ERROR error.
-
- The fourth argument, eTextRep, specifies what type of text arguments
- this function prefers to receive. Any function should be able to work
- work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be
- more efficient with one representation than another. Users are allowed
- to specify separate implementations for the same function which are called
- depending on the text representation of the arguments. The the implementation
- which provides the best match is used. If there is only a single
- implementation which does not care what text representation is used,
- then the fourth argument should be SQLITE_ANY.
-
- The fifth argument is an arbitrary pointer. The function implementations
- can gain access to this pointer using the sqlite_user_data() API.
-
- The sixth, seventh and eighth argumens, xFunc, xStep and xFinal, are
- pointers to user implemented C functions that implement the user
- function or aggregate. A scalar function requires an implementation of
- the xFunc callback only, NULL pointers should be passed as the xStep
- and xFinal arguments. An aggregate function requires an implementation
- of xStep and xFinal, and NULL should be passed for xFunc. To delete an
- existing user function or aggregate, pass NULL for all three function
- callbacks. Specifying an inconstant set of callback values, such as an
- xFunc and an xFinal, or an xStep but no xFinal, results in an SQLITE_ERROR
- return.
-}
-
-api {} {
-int sqlite3_data_count(sqlite3_stmt *pStmt);
-} {
- Return the number of values in the current row of the result set.
-
- After a call to sqlite3_step() that returns SQLITE_ROW, this routine
- will return the same value as the sqlite3_column_count() function.
- After sqlite3_step() has returned an SQLITE_DONE, SQLITE_BUSY or
- error code, or before sqlite3_step() has been called on a
- prepared SQL statement, this routine returns zero.
-}
-
-api {} {
-int sqlite3_errcode(sqlite3 *db);
-} {
- Return the error code for the most recent failed sqlite3_* API call associated
- with sqlite3 handle 'db'. If a prior API call failed but the most recent
- API call succeeded, the return value from this routine is undefined.
-
- Calls to many sqlite3_* functions set the error code and string returned
- by sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16()
- (overwriting the previous values). Note that calls to sqlite3_errcode(),
- sqlite3_errmsg() and sqlite3_errmsg16() themselves do not affect the
- results of future invocations. Calls to API routines that do not return
- an error code (examples: sqlite3_data_count() or sqlite3_mprintf()) do
- not change the error code returned by this routine.
-
- Assuming no other intervening sqlite3_* API calls are made, the error
- code returned by this function is associated with the same error as
- the strings returned by sqlite3_errmsg() and sqlite3_errmsg16().
-} {}
-
-api {} {
-const char *sqlite3_errmsg(sqlite3*);
-const void *sqlite3_errmsg16(sqlite3*);
-} {
- Return a pointer to a UTF-8 encoded string (sqlite3_errmsg)
- or a UTF-16 encoded string (sqlite3_errmsg16) describing in English the
- error condition for the most recent sqlite3_* API call. The returned
- string is always terminated by an 0x00 byte.
-
- The string "not an error" is returned when the most recent API call was
- successful.
-}
-
-api {} {
-int sqlite3_exec(
- sqlite3*, /* An open database */
- const char *sql, /* SQL to be executed */
- sqlite_callback, /* Callback function */
- void *, /* 1st argument to callback function */
- char **errmsg /* Error msg written here */
-);
-} {
- A function to executes one or more statements of SQL.
-
- If one or more of the SQL statements are queries, then
- the callback function specified by the 3rd argument is
- invoked once for each row of the query result. This callback
- should normally return 0. If the callback returns a non-zero
- value then the query is aborted, all subsequent SQL statements
- are skipped and the sqlite3_exec() function returns the SQLITE_ABORT.
-
- The 1st argument is an arbitrary pointer that is passed
- to the callback function as its first argument.
-
- The 2nd argument to the callback function is the number of
- columns in the query result. The 3rd argument to the callback
- is an array of strings holding the values for each column.
- The 4th argument to the callback is an array of strings holding
- the names of each column.
-
- The callback function may be NULL, even for queries. A NULL
- callback is not an error. It just means that no callback
- will be invoked.
-
- If an error occurs while parsing or evaluating the SQL (but
- not while executing the callback) then an appropriate error
- message is written into memory obtained from malloc() and
- *errmsg is made to point to that message. The calling function
- is responsible for freeing the memory that holds the error
- message. Use sqlite3_free() for this. If errmsg==NULL,
- then no error message is ever written.
-
- The return value is is SQLITE_OK if there are no errors and
- some other return code if there is an error. The particular
- return value depends on the type of error.
-
- If the query could not be executed because a database file is
- locked or busy, then this function returns SQLITE_BUSY. (This
- behavior can be modified somewhat using the sqlite3_busy_handler()
- and sqlite3_busy_timeout() functions.)
-} {}
-
-api {} {
-int sqlite3_finalize(sqlite3_stmt *pStmt);
-} {
- The sqlite3_finalize() function is called to delete a prepared
- SQL statement obtained by a previous call to sqlite3_prepare(),
- sqlite3_prepare_v2(), sqlite3_prepare16(), or sqlite3_prepare16_v2().
- If the statement was executed successfully, or
- not executed at all, then SQLITE_OK is returned. If execution of the
- statement failed then an error code is returned.
-
- After sqlite_finalize() has been called, the statement handle is
- invalidated. Passing it to any other SQLite function may cause a
- crash.
-
- All prepared statements must finalized before sqlite3_close() is
- called or else the close will fail with a return code of SQLITE_BUSY.
-
- This routine can be called at any point during the execution of the
- virtual machine. If the virtual machine has not completed execution
- when this routine is called, that is like encountering an error or
- an interrupt. (See sqlite3_interrupt().) Incomplete updates may be
- rolled back and transactions canceled, depending on the circumstances,
- and the result code returned will be SQLITE_ABORT.
-}
-
-api {} {
-void *sqlite3_malloc(int);
-void *sqlite3_realloc(void*, int);
-void sqlite3_free(void*);
-} {
- These routines provide access to the memory allocator used by SQLite.
- Depending on how SQLite has been compiled and the OS-layer backend,
- the memory allocator used by SQLite might be the standard system
- malloc()/realloc()/free(), or it might be something different. With
- certain compile-time flags, SQLite will add wrapper logic around the
- memory allocator to add memory leak and buffer overrun detection. The
- OS layer might substitute a completely different memory allocator.
- Use these APIs to be sure you are always using the correct memory
- allocator.
-
- The sqlite3_free() API, not the standard free() from the system library,
- should always be used to free the memory buffer returned by
- sqlite3_mprintf() or sqlite3_vmprintf() and to free the error message
- string returned by sqlite3_exec(). Using free() instead of sqlite3_free()
- might accidentally work on some systems and build configurations but
- will fail on others.
-
- Compatibility Note: Prior to version 3.4.0, the sqlite3_free API
- was prototyped to take a <tt>char*</tt> parameter rather than
- <tt>void*</tt>. Like this:
-<blockquote><pre>
-void sqlite3_free(char*);
-</pre></blockquote>
- The change to using <tt>void*</tt> might cause warnings when
- compiling older code against
- newer libraries, but everything should still work correctly.
-}
-
-api {} {
-int sqlite3_get_table(
- sqlite3*, /* An open database */
- const char *sql, /* SQL to be executed */
- char ***resultp, /* Result written to a char *[] that this points to */
- int *nrow, /* Number of result rows written here */
- int *ncolumn, /* Number of result columns written here */
- char **errmsg /* Error msg written here */
-);
-void sqlite3_free_table(char **result);
-} {
- This next routine is really just a wrapper around sqlite3_exec().
- Instead of invoking a user-supplied callback for each row of the
- result, this routine remembers each row of the result in memory
- obtained from malloc(), then returns all of the result after the
- query has finished.
-
- As an example, suppose the query result where this table:
-
- <pre>
- Name | Age
- -----------------------
- Alice | 43
- Bob | 28
- Cindy | 21
- </pre>
-
- If the 3rd argument were &azResult then after the function returns
- azResult will contain the following data:
-
- <pre>
- azResult[0] = "Name";
- azResult[1] = "Age";
- azResult[2] = "Alice";
- azResult[3] = "43";
- azResult[4] = "Bob";
- azResult[5] = "28";
- azResult[6] = "Cindy";
- azResult[7] = "21";
- </pre>
-
- Notice that there is an extra row of data containing the column
- headers. But the *nrow return value is still 3. *ncolumn is
- set to 2. In general, the number of values inserted into azResult
- will be ((*nrow) + 1)*(*ncolumn).
-
- After the calling function has finished using the result, it should
- pass the result data pointer to sqlite3_free_table() in order to
- release the memory that was malloc-ed. Because of the way the
- malloc() happens, the calling function must not try to call
- malloc() directly. Only sqlite3_free_table() is able to release
- the memory properly and safely.
-
- The return value of this routine is the same as from sqlite3_exec().
-}
-
-api {sqlite3_interrupt} {
- void sqlite3_interrupt(sqlite3*);
-} {
- This function causes any pending database operation to abort and
- return at its earliest opportunity. This routine is typically
- called in response to a user action such as pressing "Cancel"
- or Ctrl-C where the user wants a long query operation to halt
- immediately.
-} {}
-
-api {} {
-long long int sqlite3_last_insert_rowid(sqlite3*);
-} {
- Each entry in an SQLite table has a unique integer key called the "rowid".
- The rowid is always available as an undeclared column
- named ROWID, OID, or _ROWID_.
- If the table has a column of type INTEGER PRIMARY KEY then that column
- is another an alias for the rowid.
-
- This routine
- returns the rowid of the most recent INSERT into the database
- from the database connection given in the first argument. If
- no inserts have ever occurred on this database connection, zero
- is returned.
-
- If an INSERT occurs within a trigger, then the rowid of the
- inserted row is returned by this routine as long as the trigger
- is running. But once the trigger terminates, the value returned
- by this routine reverts to the last value inserted before the
- trigger fired.
-} {}
-
-api {} {
-char *sqlite3_mprintf(const char*,...);
-char *sqlite3_vmprintf(const char*, va_list);
-} {
- These routines are variants of the "sprintf()" from the
- standard C library. The resulting string is written into memory
- obtained from malloc() so that there is never a possibility of buffer
- overflow. These routines also implement some additional formatting
- options that are useful for constructing SQL statements.
-
- The strings returned by these routines should be freed by calling
- sqlite3_free().
-
- All of the usual printf formatting options apply. In addition, there
- is a "%q" option. %q works like %s in that it substitutes a null-terminated
- string from the argument list. But %q also doubles every '\\'' character.
- %q is designed for use inside a string literal. By doubling each '\\''
- character it escapes that character and allows it to be inserted into
- the string.
-
- For example, so some string variable contains text as follows:
-
- <blockquote><pre>
- char *zText = "It's a happy day!";
- </pre></blockquote>
-
- One can use this text in an SQL statement as follows:
-
- <blockquote><pre>
- sqlite3_exec_printf(db, "INSERT INTO table VALUES('%q')",
- callback1, 0, 0, zText);
- </pre></blockquote>
-
- Because the %q format string is used, the '\\'' character in zText
- is escaped and the SQL generated is as follows:
-
- <blockquote><pre>
- INSERT INTO table1 VALUES('It''s a happy day!')
- </pre></blockquote>
-
- This is correct. Had we used %s instead of %q, the generated SQL
- would have looked like this:
-
- <blockquote><pre>
- INSERT INTO table1 VALUES('It's a happy day!');
- </pre></blockquote>
-
- This second example is an SQL syntax error. As a general rule you
- should always use %q instead of %s when inserting text into a string
- literal.
-} {}
-
-api {} {
-char *sqlite3_snprintf(int bufSize, char *buf, const char *zFormat, ...);
-} {
- This routine works like "sprintf()", writing a formatted string into
- the buf[]. However, no more than bufSize characters will be written
- into buf[]. This routine returns a pointer to buf[]. If bufSize is
- greater than zero, then buf[] is guaranteed to be zero-terminated.
-
- This routine uses the same extended formatting options as
- sqlite3_mprintf() and sqlite3_vmprintf().
-
- Note these differences with the snprintf() function found in many
- standard libraries: (1) sqlite3_snprintf() returns a pointer to the
- buffer rather than the number of characters written. (It would,
- arguably, be more useful to return the number of characters written,
- but we discovered that after the interface had been published and
- are unwilling to break backwards compatibility.) (2) The order
- of the bufSize and buf parameter is reversed from snprintf().
- And (3) sqlite3_snprintf() always writes a zero-terminator if bufSize
- is positive.
-
- Please do not use the return value of this routine. We may
- decide to make the minor compatibility break and change this routine
- to return the number of characters written rather than a pointer to
- the buffer in a future minor version increment.
-}
-
-api {} {
-int sqlite3_open(
- const char *filename, /* Database filename (UTF-8) */
- sqlite3 **ppDb /* OUT: SQLite db handle */
-);
-int sqlite3_open16(
- const void *filename, /* Database filename (UTF-16) */
- sqlite3 **ppDb /* OUT: SQLite db handle */
-);
-} {
- Open the sqlite database file "filename". The "filename" is UTF-8
- encoded for sqlite3_open() and UTF-16 encoded in the native byte order
- for sqlite3_open16(). An sqlite3* handle is returned in *ppDb, even
- if an error occurs. If the database is opened (or created) successfully,
- then SQLITE_OK is returned. Otherwise an error code is returned. The
- sqlite3_errmsg() or sqlite3_errmsg16() routines can be used to obtain
- an English language description of the error.
-
- If the database file does not exist, then a new database will be created
- as needed.
- The encoding for the database will be UTF-8 if sqlite3_open() is called and
- UTF-16 if sqlite3_open16 is used.
-
- Whether or not an error occurs when it is opened, resources associated
- with the sqlite3* handle should be released by passing it to
- sqlite3_close() when it is no longer required.
-
- The returned sqlite3* can only be used in the same thread in which it
- was created. It is an error to call sqlite3_open() in one thread then
- pass the resulting database handle off to another thread to use. This
- restriction is due to goofy design decisions (bugs?) in the way some
- threading implementations interact with file locks.
-
- Note to windows users: The encoding used for the filename argument
- of sqlite3_open() must be UTF-8, not whatever codepage is currently
- defined. Filenames containing international characters must be converted
- to UTF-8 prior to passing them into sqlite3_open().
-}
-
-api {} {
-int sqlite3_prepare_v2(
- sqlite3 *db, /* Database handle */
- const char *zSql, /* SQL statement, UTF-8 encoded */
- int nBytes, /* Length of zSql in bytes. */
- sqlite3_stmt **ppStmt, /* OUT: Statement handle */
- const char **pzTail /* OUT: Pointer to unused portion of zSql */
-);
-int sqlite3_prepare16_v2(
- sqlite3 *db, /* Database handle */
- const void *zSql, /* SQL statement, UTF-16 encoded */
- int nBytes, /* Length of zSql in bytes. */
- sqlite3_stmt **ppStmt, /* OUT: Statement handle */
- const void **pzTail /* OUT: Pointer to unused portion of zSql */
-);
-
-/* Legacy Interfaces */
-int sqlite3_prepare(
- sqlite3 *db, /* Database handle */
- const char *zSql, /* SQL statement, UTF-8 encoded */
- int nBytes, /* Length of zSql in bytes. */
- sqlite3_stmt **ppStmt, /* OUT: Statement handle */
- const char **pzTail /* OUT: Pointer to unused portion of zSql */
-);
-int sqlite3_prepare16(
- sqlite3 *db, /* Database handle */
- const void *zSql, /* SQL statement, UTF-16 encoded */
- int nBytes, /* Length of zSql in bytes. */
- sqlite3_stmt **ppStmt, /* OUT: Statement handle */
- const void **pzTail /* OUT: Pointer to unused portion of zSql */
-);
-} {
- To execute an SQL query, it must first be compiled into a byte-code
- program using one of these routines.
-
- The first argument "db" is an SQLite database handle. The second
- argument "zSql" is the statement to be compiled, encoded as either
- UTF-8 or UTF-16. The sqlite3_prepare_v2()
- interfaces uses UTF-8 and sqlite3_prepare16_v2()
- use UTF-16. If the next argument, "nBytes", is less
- than zero, then zSql is read up to the first nul terminator. If
- "nBytes" is not less than zero, then it is the length of the string zSql
- in bytes (not characters).
-
- *pzTail is made to point to the first byte past the end of the first
- SQL statement in zSql. This routine only compiles the first statement
- in zSql, so *pzTail is left pointing to what remains uncompiled.
-
- *ppStmt is left pointing to a compiled SQL statement that can be
- executed using sqlite3_step(). Or if there is an error, *ppStmt may be
- set to NULL. If the input text contained no SQL (if the input is and
- empty string or a comment) then *ppStmt is set to NULL. The calling
- procedure is responsible for deleting this compiled SQL statement
- using sqlite3_finalize() after it has finished with it.
-
- On success, SQLITE_OK is returned. Otherwise an error code is returned.
-
- The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
- recommended for all new programs. The two older interfaces are retained
- for backwards compatibility, but their use is discouraged.
- In the "v2" interfaces, the prepared statement
- that is returned (the sqlite3_stmt object) contains a copy of the original
- SQL. This causes the sqlite3_step() interface to behave a differently in
- two ways:
-
- <ol>
- <li>
- If the database schema changes, instead of returning SQLITE_SCHEMA as it
- always used to do, sqlite3_step() will automatically recompile the SQL
- statement and try to run it again. If the schema has changed in a way
- that makes the statement no longer valid, sqlite3_step() will still
- return SQLITE_SCHEMA. But unlike the legacy behavior, SQLITE_SCHEMA is
- now a fatal error. Calling sqlite3_prepare_v2() again will not make the
- error go away. Note: use sqlite3_errmsg() to find the text of the parsing
- error that results in an SQLITE_SCHEMA return.
- </li>
-
- <li>
- When an error occurs,
- sqlite3_step() will return one of the detailed result-codes
- like SQLITE_IOERR or SQLITE_FULL or SQLITE_SCHEMA directly. The
- legacy behavior was that sqlite3_step() would only return a generic
- SQLITE_ERROR code and you would have to make a second call to
- sqlite3_reset() in order to find the underlying cause of the problem.
- With the "v2" prepare interfaces, the underlying reason for the error is
- returned directly.
- </li>
- </ol>
-}
-
-api {} {
-void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
-} {
- <i>Experimental</i>
-
- This routine configures a callback function - the progress callback - that
- is invoked periodically during long running calls to sqlite3_exec(),
- sqlite3_step() and sqlite3_get_table().
- An example use for this API is to keep
- a GUI updated during a large query.
-
- The progress callback is invoked once for every N virtual machine opcodes,
- where N is the second argument to this function. The progress callback
- itself is identified by the third argument to this function. The fourth
- argument to this function is a void pointer passed to the progress callback
- function each time it is invoked.
-
- If a call to sqlite3_exec(), sqlite3_step() or sqlite3_get_table() results
- in less than N opcodes being executed, then the progress callback is not
- invoked.
-
- To remove the progress callback altogether, pass NULL as the third
- argument to this function.
-
- If the progress callback returns a result other than 0, then the current
- query is immediately terminated and any database changes rolled back. If the
- query was part of a larger transaction, then the transaction is not rolled
- back and remains active. The sqlite3_exec() call returns SQLITE_ABORT.
-
-}
-
-api {} {
-int sqlite3_reset(sqlite3_stmt *pStmt);
-} {
- The sqlite3_reset() function is called to reset a prepared SQL
- statement obtained by a previous call to
- sqlite3_prepare_v2() or
- sqlite3_prepare16_v2() back to it's initial state, ready to be re-executed.
- Any SQL statement variables that had values bound to them using
- the sqlite3_bind_*() API retain their values.
-}
-
-api {} {
-void sqlite3_result_blob(sqlite3_context*, const void*, int n, void(*)(void*));
-void sqlite3_result_double(sqlite3_context*, double);
-void sqlite3_result_error(sqlite3_context*, const char*, int);
-void sqlite3_result_error16(sqlite3_context*, const void*, int);
-void sqlite3_result_int(sqlite3_context*, int);
-void sqlite3_result_int64(sqlite3_context*, long long int);
-void sqlite3_result_null(sqlite3_context*);
-void sqlite3_result_text(sqlite3_context*, const char*, int n, void(*)(void*));
-void sqlite3_result_text16(sqlite3_context*, const void*, int n, void(*)(void*));
-void sqlite3_result_text16be(sqlite3_context*, const void*, int n, void(*)(void*));
-void sqlite3_result_text16le(sqlite3_context*, const void*, int n, void(*)(void*));
-void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
-} {
- User-defined functions invoke these routines in order to
- set their return value. The sqlite3_result_value() routine is used
- to return an exact copy of one of the arguments to the function.
-
- The operation of these routines is very similar to the operation of
- sqlite3_bind_blob() and its cousins. Refer to the documentation there
- for additional information.
-}
-
-api {} {
-int sqlite3_set_authorizer(
- sqlite3*,
- int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
- void *pUserData
-);
-#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
-#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
-#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
-#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
-#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
-#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
-#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
-#define SQLITE_CREATE_VIEW 8 /* View Name NULL */
-#define SQLITE_DELETE 9 /* Table Name NULL */
-#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
-#define SQLITE_DROP_TABLE 11 /* Table Name NULL */
-#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
-#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
-#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
-#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
-#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
-#define SQLITE_DROP_VIEW 17 /* View Name NULL */
-#define SQLITE_INSERT 18 /* Table Name NULL */
-#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
-#define SQLITE_READ 20 /* Table Name Column Name */
-#define SQLITE_SELECT 21 /* NULL NULL */
-#define SQLITE_TRANSACTION 22 /* NULL NULL */
-#define SQLITE_UPDATE 23 /* Table Name Column Name */
-#define SQLITE_ATTACH 24 /* Filename NULL */
-#define SQLITE_DETACH 25 /* Database Name NULL */
-#define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */
-#define SQLITE_REINDEX 27 /* Index Name NULL */
-#define SQLITE_ANALYZE 28 /* Table Name NULL */
-#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
-#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
-#define SQLITE_FUNCTION 31 /* Function Name NULL */
-
-#define SQLITE_DENY 1 /* Abort the SQL statement with an error */
-#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
-} {
- This routine registers a callback with the SQLite library. The
- callback is invoked by sqlite3_prepare_v2() to authorize various
- operations against the database. The callback should
- return SQLITE_OK if access is allowed, SQLITE_DENY if the entire
- SQL statement should be aborted with an error and SQLITE_IGNORE
- if the operation should be treated as a no-op.
-
- Each database connection have at most one authorizer registered
- at a time one time. Each call
- to sqlite3_set_authorizer() overrides the previous authorizer.
- Setting the callback to NULL disables the authorizer.
-
- The second argument to the access authorization function will be one
- of the defined constants shown. These values signify what kind of operation
- is to be authorized. The 3rd and 4th arguments to the authorization
- function will be arguments or NULL depending on which of the
- codes is used as the second argument. For example, if the the
- 2nd argument code is SQLITE_READ then the 3rd argument will be the name
- of the table that is being read from and the 4th argument will be the
- name of the column that is being read from. Or if the 2nd argument
- is SQLITE_FUNCTION then the 3rd argument will be the name of the
- function that is being invoked and the 4th argument will be NULL.
-
- The 5th argument is the name
- of the database ("main", "temp", etc.) where applicable. The 6th argument
- is the name of the inner-most trigger or view that is responsible for
- the access attempt or NULL if this access attempt is directly from
- input SQL code.
-
- The return value of the authorization callback function should be one of the
- constants SQLITE_OK, SQLITE_DENY, or SQLITE_IGNORE. A return of
- SQLITE_OK means that the operation is permitted and that
- sqlite3_prepare_v2() can proceed as normal.
- A return of SQLITE_DENY means that the sqlite3_prepare_v2()
- should fail with an error. A return of SQLITE_IGNORE causes the
- sqlite3_prepare_v2() to continue as normal but the requested
- operation is silently converted into a no-op. A return of SQLITE_IGNORE
- in response to an SQLITE_READ or SQLITE_FUNCTION causes the column
- being read or the function being invoked to return a NULL.
-
- The intent of this routine is to allow applications to safely execute
- user-entered SQL. An appropriate callback can deny the user-entered
- SQL access certain operations (ex: anything that changes the database)
- or to deny access to certain tables or columns within the database.
-
- SQLite is not reentrant through the authorization callback function.
- The authorization callback function should not attempt to invoke
- any other SQLite APIs for the same database connection. If the
- authorization callback function invokes some other SQLite API, an
- SQLITE_MISUSE error or a segmentation fault may result.
-}
-
-api {} {
-int sqlite3_step(sqlite3_stmt*);
-} {
- After an SQL query has been prepared with a call to either
- sqlite3_prepare_v2() or sqlite3_prepare16_v2() or to one of
- the legacy interfaces sqlite3_prepare() or sqlite3_prepare16(),
- then this function must be
- called one or more times to execute the statement.
-
- The details of the behavior of this sqlite3_step() interface depend
- on whether the statement was prepared using the newer "v2" interface
- sqlite3_prepare_v2() and sqlite3_prepare16_v2() or the older legacy
- interface sqlite3_prepare() and sqlite3_prepare16(). The use of the
- new "v2" interface is recommended for new applications but the legacy
- interface will continue to be supported.
-
- In the lagacy interface, the return value will be either SQLITE_BUSY,
- SQLITE_DONE, SQLITE_ROW, SQLITE_ERROR, or SQLITE_MISUSE. With the "v2"
- interface, any of the other SQLite result-codes might be returned as
- well.
-
- SQLITE_BUSY means that the database engine attempted to open
- a locked database and there is no busy callback registered.
- Call sqlite3_step() again to retry the open.
-
- SQLITE_DONE means that the statement has finished executing
- successfully. sqlite3_step() should not be called again on this virtual
- machine without first calling sqlite3_reset() to reset the virtual
- machine back to its initial state.
-
- If the SQL statement being executed returns any data, then
- SQLITE_ROW is returned each time a new row of data is ready
- for processing by the caller. The values may be accessed using
- the sqlite3_column_int(), sqlite3_column_text(), and similar functions.
- sqlite3_step() is called again to retrieve the next row of data.
-
- SQLITE_ERROR means that a run-time error (such as a constraint
- violation) has occurred. sqlite3_step() should not be called again on
- the VM. More information may be found by calling sqlite3_errmsg().
- A more specific error code (example: SQLITE_INTERRUPT, SQLITE_SCHEMA,
- SQLITE_CORRUPT, and so forth) can be obtained by calling
- sqlite3_reset() on the prepared statement. In the "v2" interface,
- the more specific error code is returned directly by sqlite3_step().
-
- SQLITE_MISUSE means that the this routine was called inappropriately.
- Perhaps it was called on a virtual machine that had already been
- finalized or on one that had previously returned SQLITE_ERROR or
- SQLITE_DONE. Or it could be the case that a database connection
- is being used by a different thread than the one it was created it.
-
- <b>Goofy Interface Alert:</b>
- In the legacy interface,
- the sqlite3_step() API always returns a generic error code,
- SQLITE_ERROR, following any error other than SQLITE_BUSY and SQLITE_MISUSE.
- You must call sqlite3_reset() (or sqlite3_finalize()) in order to find
- one of the specific result-codes that better describes the error.
- We admit that this is a goofy design. The problem has been fixed
- with the "v2" interface. If you prepare all of your SQL statements
- using either sqlite3_prepare_v2() or sqlite3_prepare16_v2() instead
- of the legacy sqlite3_prepare() and sqlite3_prepare16(), then the
- more specific result-codes are returned directly by sqlite3_step().
- The use of the "v2" interface is recommended.
-}
-
-api {} {
-void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
-} {
- Register a function that is called each time an SQL statement is evaluated.
- The callback function is invoked on the first call to sqlite3_step() after
- calls to sqlite3_prepare_v2() or sqlite3_reset().
- This function can be used (for example) to generate
- a log file of all SQL executed against a database. This can be
- useful when debugging an application that uses SQLite.
-}
-
-api {} {
-void *sqlite3_user_data(sqlite3_context*);
-} {
- The pUserData argument to the sqlite3_create_function() and
- sqlite3_create_function16() routines used to register user functions
- is available to the implementation of the function using this
- call.
-}
-
-api {} {
-const void *sqlite3_value_blob(sqlite3_value*);
-int sqlite3_value_bytes(sqlite3_value*);
-int sqlite3_value_bytes16(sqlite3_value*);
-double sqlite3_value_double(sqlite3_value*);
-int sqlite3_value_int(sqlite3_value*);
-long long int sqlite3_value_int64(sqlite3_value*);
-const unsigned char *sqlite3_value_text(sqlite3_value*);
-const void *sqlite3_value_text16(sqlite3_value*);
-const void *sqlite3_value_text16be(sqlite3_value*);
-const void *sqlite3_value_text16le(sqlite3_value*);
-int sqlite3_value_type(sqlite3_value*);
-} {
- This group of routines returns information about arguments to
- a user-defined function. Function implementations use these routines
- to access their arguments. These routines are the same as the
- sqlite3_column_... routines except that these routines take a single
- sqlite3_value* pointer instead of an sqlite3_stmt* and an integer
- column number.
-
- See the documentation under sqlite3_column_blob for additional
- information.
-
- Please pay particular attention to the fact that the pointer that
- is returned from sqlite3_value_blob(), sqlite3_value_text(), or
- sqlite3_value_text16() can be invalidated by a subsequent call to
- sqlite3_value_bytes(), sqlite3_value_bytes16(), sqlite_value_text(),
- or sqlite3_value_text16().
-}
-
-api {} {
- int sqlite3_sleep(int);
-} {
- Sleep for a little while. The second parameter is the number of
- miliseconds to sleep for.
-
- If the operating system does not support sleep requests with
- milisecond time resolution, then the time will be rounded up to
- the nearest second. The number of miliseconds of sleep actually
- requested from the operating system is returned.
-}
-
-api {} {
- int sqlite3_expired(sqlite3_stmt*);
-} {
- Return TRUE (non-zero) if the statement supplied as an argument needs
- to be recompiled. A statement needs to be recompiled whenever the
- execution environment changes in a way that would alter the program
- that sqlite3_prepare() generates. For example, if new functions or
- collating sequences are registered or if an authorizer function is
- added or changed.
-}
-
-api {} {
- int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
-} {
- Move all bindings from the first prepared statement over to the second.
- This routine is useful, for example, if the first prepared statement
- fails with an SQLITE_SCHEMA error. The same SQL can be prepared into
- the second prepared statement then all of the bindings transfered over
- to the second statement before the first statement is finalized.
-}
-
-api {} {
- int sqlite3_global_recover();
-} {
- This function used to be involved in recovering from out-of-memory
- errors. But as of SQLite version 3.3.0, out-of-memory recovery is
- automatic and this routine now does nothing. THe interface is retained
- to avoid link errors with legacy code.
-}
-
-api {} {
- int sqlite3_get_autocommit(sqlite3*);
-} {
- Test to see whether or not the database connection is in autocommit
- mode. Return TRUE if it is and FALSE if not. Autocommit mode is on
- by default. Autocommit is disabled by a BEGIN statement and reenabled
- by the next COMMIT or ROLLBACK.
-}
-
-api {} {
- int sqlite3_clear_bindings(sqlite3_stmt*);
-} {
- Set all the parameters in the compiled SQL statement back to NULL.
-}
-
-api {} {
- sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
-} {
- Return the sqlite3* database handle to which the prepared statement given
- in the argument belongs. This is the same database handle that was
- the first argument to the sqlite3_prepare() that was used to create
- the statement in the first place.
-}
-
-api {} {
- void *sqlite3_update_hook(
- sqlite3*,
- void(*)(void *,int ,char const *,char const *,sqlite_int64),
- void*
- );
-} {
- Register a callback function with the database connection identified by the
- first argument to be invoked whenever a row is updated, inserted or deleted.
- Any callback set by a previous call to this function for the same
- database connection is overridden.
-
- The second argument is a pointer to the function to invoke when a
- row is updated, inserted or deleted. The first argument to the callback is
- a copy of the third argument to sqlite3_update_hook. The second callback
- argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending
- on the operation that caused the callback to be invoked. The third and
- fourth arguments to the callback contain pointers to the database and
- table name containing the affected row. The final callback parameter is
- the rowid of the row. In the case of an update, this is the rowid after
- the update takes place.
-
- The update hook is not invoked when internal system tables are
- modified (i.e. sqlite_master and sqlite_sequence).
-
- If another function was previously registered, its pArg value is returned.
- Otherwise NULL is returned.
-
- See also: sqlite3_commit_hook(), sqlite3_rollback_hook()
-}
-
-api {} {
- void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
-} {
- Register a callback to be invoked whenever a transaction is rolled
- back.
-
- The new callback function overrides any existing rollback-hook
- callback. If there was an existing callback, then it's pArg value
- (the third argument to sqlite3_rollback_hook() when it was registered)
- is returned. Otherwise, NULL is returned.
-
- For the purposes of this API, a transaction is said to have been
- rolled back if an explicit "ROLLBACK" statement is executed, or
- an error or constraint causes an implicit rollback to occur. The
- callback is not invoked if a transaction is automatically rolled
- back because the database connection is closed.
-}
-
-api {} {
- int sqlite3_enable_shared_cache(int);
-} {
- This routine enables or disables the sharing of the database cache
- and schema data structures between connections to the same database.
- Sharing is enabled if the argument is true and disabled if the argument
- is false.
-
- Cache sharing is enabled and disabled on a thread-by-thread basis.
- Each call to this routine enables or disables cache sharing only for
- connections created in the same thread in which this routine is called.
- There is no mechanism for sharing cache between database connections
- running in different threads.
-
- Sharing must be disabled prior to shutting down a thread or else
- the thread will leak memory. Call this routine with an argument of
- 0 to turn off sharing. Or use the sqlite3_thread_cleanup() API.
-
- This routine must not be called when any database connections
- are active in the current thread. Enabling or disabling shared
- cache while there are active database connections will result
- in memory corruption.
-
- When the shared cache is enabled, the
- following routines must always be called from the same thread:
- sqlite3_open(), sqlite3_prepare_v2(), sqlite3_step(), sqlite3_reset(),
- sqlite3_finalize(), and sqlite3_close().
- This is due to the fact that the shared cache makes use of
- thread-specific storage so that it will be available for sharing
- with other connections.
-
- Virtual tables cannot be used with a shared cache. When shared
- cache is enabled, the sqlite3_create_module() API used to register
- virtual tables will always return an error.
-
- This routine returns SQLITE_OK if shared cache was
- enabled or disabled successfully. An error code is returned
- otherwise.
-
- Shared cache is disabled by default for backward compatibility.
-}
-
-api {} {
- void sqlite3_thread_cleanup(void);
-} {
- This routine makes sure that all thread local storage used by SQLite
- in the current thread has been deallocated. A thread can call this
- routine prior to terminating in order to make sure there are no memory
- leaks.
-
- This routine is not strictly necessary. If cache sharing has been
- disabled using sqlite3_enable_shared_cache() and if all database
- connections have been closed and if SQLITE_ENABLE_MEMORY_MANAGMENT is
- on and all memory has been freed, then the thread local storage will
- already have been automatically deallocated. This routine is provided
- as a convenience to the program who just wants to make sure that there
- are no leaks.
-}
-
-api {} {
- int sqlite3_release_memory(int N);
-} {
- This routine attempts to free at least N bytes of memory from the caches
- of database connecions that were created in the same thread from which this
- routine is called. The value returned is the number of bytes actually
- freed.
-
- This routine is only available if memory management has been enabled
- by compiling with the SQLITE_ENABLE_MEMORY_MANAGMENT macro.
-}
-
-api {} {
- void sqlite3_soft_heap_limit(int N);
-} {
- This routine sets the soft heap limit for the current thread to N.
- If the total heap usage by SQLite in the current thread exceeds N,
- then sqlite3_release_memory() is called to try to reduce the memory usage
- below the soft limit.
-
- Prior to shutting down a thread sqlite3_soft_heap_limit() must be set to
- zero (the default) or else the thread will leak memory. Alternatively, use
- the sqlite3_thread_cleanup() API.
-
- A negative or zero value for N means that there is no soft heap limit and
- sqlite3_release_memory() will only be called when memory is exhaused.
- The default value for the soft heap limit is zero.
-
- SQLite makes a best effort to honor the soft heap limit. But if it
- is unable to reduce memory usage below the soft limit, execution will
- continue without error or notification. This is why the limit is
- called a "soft" limit. It is advisory only.
-
- This routine is only available if memory management has been enabled
- by compiling with the SQLITE_ENABLE_MEMORY_MANAGMENT macro.
-}
-
-api {} {
- void sqlite3_thread_cleanup(void);
-} {
- This routine ensures that a thread that has used SQLite in the past
- has released any thread-local storage it might have allocated.
- When the rest of the API is used properly, the cleanup of
- thread-local storage should be completely automatic. You should
- never really need to invoke this API. But it is provided to you
- as a precaution and as a potential work-around for future
- thread-releated memory-leaks.
-}
-
-set n 0
-set i 0
-foreach item $apilist {
- set namelist [lindex $item 0]
- foreach name $namelist {
- set n_to_name($n) $name
- set n_to_idx($n) $i
- set name_to_idx($name) $i
- incr n
- }
- incr i
-}
-set i 0
-foreach name [lsort [array names name_to_idx]] {
- set sname($i) $name
- incr i
-}
-#parray n_to_name
-#parray n_to_idx
-#parray name_to_idx
-#parray sname
-incr n -1
-puts "<DIV class=pdf_ignore>"
-puts {<table width="100%" cellpadding="5"><tr>}
-set nrow [expr {($n+2)/3}]
-set i 0
-for {set j 0} {$j<3} {incr j} {
- if {$j>0} {puts {<td width="10"></td>}}
- puts {<td valign="top">}
- set limit [expr {$i+$nrow}]
- puts {<ul>}
- while {$i<$limit && $i<$n} {
- set name $sname($i)
- if {[regexp {^sqlite} $name]} {set display $name} {set display <i>$name</i>}
- puts "<li><a href=\"#$name\">$display</a></li>"
- incr i
- }
- puts {</ul></td>}
-}
-puts "</table>"
-puts "<!-- $n entries. $nrow rows in 3 columns -->"
-puts "</DIV>"
-
-proc resolve_name {ignore_list name} {
- global name_to_idx
- if {![info exists name_to_idx($name)] || [lsearch $ignore_list $name]>=0} {
- return $name
- } else {
- return "<a href=\"#$name\">$name</a>"
- }
-}
-
-foreach name [lsort [array names name_to_idx]] {
- set i $name_to_idx($name)
- if {[info exists done($i)]} continue
- set done($i) 1
- foreach {namelist prototype desc} [lindex $apilist $i] break
- foreach name $namelist {
- puts "<a name=\"$name\"></a>"
- }
- puts "<p><hr></p>"
- puts "<blockquote><pre>"
- regsub "^( *\n)+" $prototype {} p2
- regsub "(\n *)+\$" $p2 {} p3
- puts $p3
- puts "</pre></blockquote>"
- regsub -all {\[} $desc {\[} desc
- regsub -all {sqlite3_[a-z0-9_]+} $desc "\[resolve_name $name &\]" d2
- foreach x $specialname {
- regsub -all $x $d2 "\[resolve_name $name &\]" d2
- }
- regsub -all "\n( *\n)+" [subst $d2] "</p>\n\n<p>" d3
- puts "<p>$d3</p>"
-}
-
-puts "<DIV class=pdf_ignore>"
-footer $rcsid
-puts "</DIV>"
+++ /dev/null
-#
-# Run this script to generated a changes.html output file
-#
-source common.tcl
-header {SQLite changes}
-puts {
-<p>
-This page provides a high-level summary of changes to SQLite.
-For more detail, refer the the checkin logs generated by
-CVS at
-<a href="http://www.sqlite.org/cvstrac/timeline">
-http://www.sqlite.org/cvstrac/timeline</a>.
-</p>
-
-<DL>
-}
-
-
-proc chng {date desc} {
- if {[regexp {\(([0-9.]+)\)} $date all vers]} {
- set label [string map {. _} $vers]
- puts "<A NAME=\"version_$label\">"
- }
- puts "<DT><B>$date</B></DT>"
- regsub -all {[Tt]icket #(\d+)} $desc \
- {<a href="http://www.sqlite.org/cvstrac/tktview?tn=\1">\0</a>} desc
- puts "<DD><P><UL>$desc</UL></P>"
- puts "</DD>"
-}
-
-chng {2007 Nov 05 (3.5.2)} {
-<li>Dropped support for the SQLITE_OMIT_MEMORY_ALLOCATION compile-time
-option.
-<li>Always open files using FILE_FLAG_RANDOM_ACCESS under windows.
-<li>The 3rd parameter of the built-in SUBSTR() function is now optional.
-<li>Bug fix: do not invoke the authorizer when reparsing the schema after
-a schema change.
-<li>Added the experimental malloc-free memory allocator in mem3.c.
-<li>Virtual machine stores 64-bit integer and floating point constants
-in binary instead of text for a performance boost.
-<li>Fix a race condition in test_async.c.
-<li>Added the ".timer" command to the CLI
-}
-
-chng {2007 Oct 04 (3.5.1)} {
-<li><i><b>Nota Bene:</b> We are not using terms "alpha" or "beta" on this
- release because the code is stable and because if we use those terms,
- nobody will upgrade. However, we still reserve the right to make
- incompatible changes to the new VFS interface in future releases.</i></li>
-
-<li>Fix a bug in the handling of SQLITE_FULL errors that could lead
- to database corruption. Ticket #2686.
-<li>The test_async.c drive now does full file locking and works correctly
- when used simultaneously by multiple processes on the same database.
-<li>The CLI ignores whitespace (including comments) at the end of lines
-<li>Make sure the query optimizer checks dependences on all terms of
- a compound SELECT statement. Ticket #2640.
-<li>Add demonstration code showing how to build a VFS for a raw
- mass storage without a filesystem.
-<li>Added an output buffer size parameter to the xGetTempname() method
- of the VFS layer.
-<li>Sticky SQLITE_FULL or SQLITE_IOERR errors in the pager are reset
- when a new transaction is started.
-}
-
-
-chng {2007 Sep 04 (3.5.0) alpha} {
-<li>Redesign the OS interface layer. See
- <a href="34to35.html">34to35.html</a> for details.
- <font color="red">*** Potentially incompatible change ***</font>
-<li>The <a href="capi3ref.html#sqlite3_release_memory">
- sqlite3_release_memory()</a>,
- <a href="capi3ref.html#sqlite3_soft_heap_limit">
- sqlite3_soft_heap_limit()</a>,
- and <a href="capi3ref.html#sqlite3_enable_shared_cache">
- sqlite3_enable_shared_cache()</a> interfaces now work cross all
- threads in the process, not just the single thread in which they
- are invoked.
- <font color="red">*** Potentially incompatible change ***</font>
-<li>Added the
- <a href="capi3ref.html#sqlite3_open_v2">sqlite3_open_v2()</a>
- interface.
-<li>Reimplemented the memory allocation subsystem and made it
- replacable at compile-time.
-<li>Created a new mutex subsystem and made it replacable at
- compile-time.
-<li>The same database connection may now be used simultaneously by
- separate threads.
-}
-
-
-chng {2007 August 13 (3.4.2)} {
-<li>Fix a database corruption bug that might occur if a ROLLBACK command
-is executed in <a href="pragma.html#pragma_auto_vacuum">auto-vacuum mode</a>
-and a very small <a href="capi3ref.html#sqlite3_soft_heap_limit">
-soft_heap_limit</a> is set.
-<a href="http://www.sqlite.org/cvstrac/tktview?tn=2565">Ticket #2565</a>.
-
-<li>Add the ability to run a full regression test with a small
-<a href="capi3ref.html#sqlite3_soft_heap_limit">soft_heap_limit</a>.
-
-<li>Fix other minor problems with using small soft heap limits.
-
-<li>Work-around for
-<a href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=32575">GCC bug 32575</a>.
-
-<li>Improved error detection of misused aggregate functions.
-
-<li>Improvements to the amalgamation generator script so that all symbols
-are prefixed with either SQLITE_PRIVATE or SQLITE_API.
-}
-
-chng {2007 July 20 (3.4.1)} {
-<li>Fix a bug in <a href="lang_vacuum.html">VACUUM</a> that can lead to
- <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption">
- database corruption</a> if two
- processes are connected to the database at the same time and one
- VACUUMs then the other then modifies the database.</li>
-<li>The expression "+column" is now considered the same as "column"
- when computing the collating sequence to use on the expression.</li>
-<li>In the <a href="tclsqlite.html">TCL language interface</a>,
- "@variable" instead of "$variable" always binds as a blob.</li>
-<li>Added <a href="pragma.html#pragma_freelist_count">PRAGMA freelist_count</a>
- for determining the current size of the freelist.</li>
-<li>The <a href="pragma.html#pragma_auto_vacuum">
- PRAGMA auto_vacuum=incremental</a> setting is now persistent.</li>
-<li>Add FD_CLOEXEC to all open files under unix.</li>
-<li>Fix a bug in the <a href="optoverview.html#minmax">
- min()/max() optimization</a> when applied to
- descending indices.</li>
-<li>Make sure the TCL language interface works correctly with 64-bit
- integers on 64-bit machines.</li>
-<li>Allow the value -9223372036854775808 as an integer literal in SQL
- statements.</li>
-<li>Add the capability of "hidden" columns in virtual tables.</li>
-<li>Use the macro SQLITE_PRIVATE (defaulting to "static") on all
- internal functions in the amalgamation.</li>
-<li>Add pluggable tokenizers and <a href="http://www.icu-project.org/">ICU</a>
- tokenization support to FTS2</li>
-<li>Other minor bug fixes and documentation enhancements</li>
-}
-
-chng {2007 June 18 (3.4.0)} {
-<li>Fix a bug that can lead to database corruption if an SQLITE_BUSY error
- occurs in the middle of an explicit transaction and that transaction
- is later committed.
- <a href="http://www.sqlite.org/cvstrac/tktview?tn=2409">Ticket #2409.</a>
- See the
- <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">
- CorruptionFollowingBusyError</a> wiki page for details.</i>
-<li>Fix a bug that can lead to database corruption if autovacuum mode is
- on and a malloc() failure follows a CREATE TABLE or CREATE INDEX statement
- which itself follows a cache overflow inside a transaction. See
- <a href="http://www.sqlite.org/cvstrac/tktview?tn=2418">ticket #2418</a>.
- </li>
-<li>Added explicit <a href="limits.html">upper bounds</a> on the sizes and
- quantities of things SQLite can process. This change might cause
- compatibility problems for
- applications that use SQLite in the extreme, which is why the current
- release is 3.4.0 instead of 3.3.18.</li>
-<li>Added support for <a href="capi3ref.html#sqlite3_blob_open">
- Incremental BLOB I/O</a>.</li>
-<li>Added the <a href="capi3ref.html#sqlite3_bind_zeroblob">zeroblob API</a>
- and the <a href="lang_expr.html#zeroblob">zeroblob()</a> SQL function.</li>
-<li>Added support for <a href="pragma.html#pragma_incremental_vacuum">
- Incremental Vacuum</a>.</li>
-<li>Added the SQLITE_MIXED_ENDIAN_64BIT_FLOAT compile-time option to suppport
- ARM7 processors with goofy endianness.</li>
-<li>Removed all instances of sprintf() and strcpy() from the core library.</li>
-<li>Added support for <a href="http://www.icu-project.org/">
- International Components for Unicode (ICU)</a> to the full-text search
- extensions.
-</ul><p>
-<ul type="circle">
-<li>In the windows OS driver, reacquire a SHARED lock if an attempt to
- acquire an EXCLUSIVE lock fails. Ticket #2354</li>
-<li>Fix the REPLACE() function so that it returns NULL if the second argument
- is an empty string. Ticket #2324.</li>
-<li>Document the hazards of type coversions in
- <a href="capi3ref.html#sqlite3_column_blob">sqlite3_column_blob()</a>
- and related APIs. Fix unnecessary type conversions. Ticket #2321.</li>
-<li>Internationalization of the TRIM() function. Ticket #2323</li>
-<li>Use memmove() instead of memcpy() when moving between memory regions
- that might overlap. Ticket #2334</li>
-<li>Fix an optimizer bug involving subqueries in a compound SELECT that has
- both an ORDER BY and a LIMIT clause. Ticket #2339.</li>
-<li>Make sure the <a href="capi3ref.html#sqlite3_snprintf">sqlite3_snprintf()
- </a> interface does not zero-terminate the buffer if the buffer size is
- less than 1. Ticket #2341</li>
-<li>Fix the built-in printf logic so that it prints "NaN" not "Inf" for
- floating-point NaNs. Ticket #2345</li>
-<li>When converting BLOB to TEXT, use the text encoding of the main database.
- Ticket #2349</li>
-<li>Keep the full precision of integers (if possible) when casting to
- NUMERIC. Ticket #2364</li>
-<li>Fix a bug in the handling of UTF16 codepoint 0xE000</li>
-<li>Consider explicit collate clauses when matching WHERE constraints
- to indices in the query optimizer. Ticket #2391</li>
-<li>Fix the query optimizer to correctly handle constant expressions in
- the ON clause of a LEFT JOIN. Ticket #2403</li>
-<li>Fix the query optimizer to handle rowid comparisions to NULL
- correctly. Ticket #2404</li>
-<li>Fix many potental segfaults that could be caused by malicious SQL
- statements.</li>
-}
-
-chng {2007 April 25 (3.3.17)} {
-<li>When the "write_version" value of the database header is larger than
- what the library understands, make the database read-only instead of
- unreadable.</li>
-<li>Other minor bug fixes</li>
-}
-
-chng {2007 April 18 (3.3.16)} {
-<li>Fix a bug that caused VACUUM to fail if NULLs appeared in a
- UNIQUE column.</li>
-<li>Reinstate performance improvements that were added in 3.3.14
- but regressed in 3.3.15.</li>
-<li>Fix problems with the handling of ORDER BY expressions on
- compound SELECT statements in subqueries.</li>
-<li>Fix a potential segfault when destroying locks on WinCE in
- a multi-threaded environment.</li>
-<li>Documentation updates.</li>
-}
-
-chng {2007 April 9 (3.3.15)} {
-<li>Fix a bug introduced in 3.3.14 that caused a rollback of
- CREATE TEMP TABLE to leave the database connection wedged.</li>
-<li>Fix a bug that caused an extra NULL row to be returned when
- a descending query was interrupted by a change to the database.</li>
-<li>The FOR EACH STATEMENT clause on a trigger now causes a syntax
- error. It used to be silently ignored.</li>
-<li>Fix an obscure and relatively harmless problem that might have caused
- a resource leak following an I/O error.</li>
-<li>Many improvements to the test suite. Test coverage now exceeded 98%</li>
-}
-
-chng {2007 April 2 (3.3.14)} {
-<li>Fix a <a href="http://www.sqlite.org/cvstrac/tktview?tn=2273">bug</a>
- in 3.3.13 that could cause a segfault when the IN operator
- is used one one term of a two-column index and the right-hand side of
- the IN operator contains a NULL.</li>
-<li>Added a new OS interface method for determining the sector size
- of underlying media: sqlite3OsSectorSize().</li>
-<li>A new algorithm for statements of the form
- INSERT INTO <i>table1</i> SELECT * FROM <i>table2</i>
- is faster and reduces fragmentation. VACUUM uses statements of
- this form and thus runs faster and defragments better.</li>
-<li>Performance enhancements through reductions in disk I/O:
-<ul>
-<li>Do not read the last page of an overflow chain when
- deleting the row - just add that page to the freelist.</li>
-<li>Do not store pages being deleted in the
- rollback journal.</li>
-<li>Do not read in the (meaningless) content of
- pages extracted from the freelist.</li>
-<li>Do not flush the page cache (and thus avoiding
- a cache refill) unless another process changes the underlying
- database file.</li>
-<li>Truncate rather than delete the rollback journal when committing
- a transaction in exclusive access mode, or when committing the TEMP
- database.</li>
-</ul></li>
-<li>Added support for exclusive access mode using
- <a href="pragma.html#pragma_locking_mode">
- "PRAGMA locking_mode=EXCLUSIVE"</a></li>
-<li>Use heap space instead of stack space for large buffers in the
- pager - useful on embedded platforms with stack-space
- limitations.</li>
-<li>Add a makefile target "sqlite3.c" that builds an amalgamation containing
- the core SQLite library C code in a single file.</li>
-<li>Get the library working correctly when compiled
- with GCC option "-fstrict-aliasing".</li>
-<li>Removed the vestigal SQLITE_PROTOCOL error.</li>
-<li>Improvements to test coverage, other minor bugs fixed,
- memory leaks plugged,
- code refactored and/or recommented in places for easier reading.</li>
-}
-
-chng {2007 February 13 (3.3.13)} {
-<li>Add a "fragmentation" measurement in the output of sqlite3_analyzer.</li>
-<li>Add the COLLATE operator used to explicitly set the collating sequence
-used by an expression. This feature is considered experimental pending
-additional testing.</li>
-<li>Allow up to 64 tables in a join - the old limit was 32.</li>
-<li>Added two new experimental functions:
-<a href="lang_expr.html#randomblobFunc">randomBlob()</a> and
-<a href="lang_expr.html#hexFunc">hex()</a>.
-Their intended use is to facilitate generating
-<a href="http://en.wikipedia.org/wiki/UUID">UUIDs</a>.
-</li>
-<li>Fix a problem where
-<a href="pragma.html#pragma_count_changes">PRAGMA count_changes</a> was
-causing incorrect results for updates on tables with triggers</li>
-<li>Fix a bug in the ORDER BY clause optimizer for joins where the
-left-most table in the join is constrained by a UNIQUE index.</li>
-<li>Fixed a bug in the "copy" method of the TCL interface.</li>
-<li>Bug fixes in fts1 and fts2 modules.</li>
-}
-
-chng {2007 January 27 (3.3.12)} {
-<li>Fix another bug in the IS NULL optimization that was added in
-version 3.3.9.</li>
-<li>Fix a assertion fault that occurred on deeply nested views.</li>
-<li>Limit the amount of output that
-<a href="pragma.html#pragma_integrity_check">PRAGMA integrity_check</a>
-generates.</li>
-<li>Minor syntactic changes to support a wider variety of compilers.</li>
-}
-
-chng {2007 January 22 (3.3.11)} {
-<li>Fix another bug in the implementation of the new
-<a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a> API.
-We'll get it right eventually...</li>
-<li>Fix a bug in the IS NULL optimization that was added in version 3.3.9 -
-the bug was causing incorrect results on certain LEFT JOINs that included
-in the WHERE clause an IS NULL constraint for the right table of the
-LEFT JOIN.</li>
-<li>Make AreFileApisANSI() a no-op macro in winCE since winCE does not
-support this function.</li>
-}
-
-chng {2007 January 9 (3.3.10)} {
-<li>Fix bugs in the implementation of the new
-<a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a> API
-that can lead to segfaults.</li>
-<li>Fix 1-second round-off errors in the
-<a href="http://www.sqlite.org/cvstrac/wiki?p=DateAndTimeFunctions">
-strftime()</a> function</li>
-<li>Enhance the windows OS layer to provide detailed error codes</li>
-<li>Work around a win2k problem so that SQLite can use single-character
-database file names</li>
-<li>The
-<a href="pragma.html#pragma_user_version">user_version</a> and
-<a href="pragma.html#pragma_schema_version">schema_version</a> pragmas
-correctly set their column names in the result set</li>
-<li>Documentation updates</li>
-}
-
-chng {2007 January 4 (3.3.9)} {
-<li>Fix bugs in pager.c that could lead to database corruption if two
-processes both try to recover a hot journal at the same instant</li>
-<li>Added the <a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a>
-API.</li>
-<li>Fixed the ".dump" command in the command-line shell to show
-indices, triggers and views again.</li>
-<li>Change the table_info pragma so that it returns NULL for the default
-value if there is no default value</li>
-<li>Support for non-ASCII characters in win95 filenames</li>
-<li>Query optimizer enhancements:
-<ul>
-<li>Optimizer does a better job of using indices to satisfy ORDER BY
-clauses that sort on the integer primary key</li>
-<li>Use an index to satisfy an IS NULL operator in the WHERE clause</li>
-<li>Fix a bug that was causing the optimizer to miss an OR optimization
-opportunity</li>
-<li>The optimizer has more freedom to reorder tables in the FROM clause
-even in there are LEFT joins.</li>
-</ul>
-<li>Extension loading supported added to winCE</li>
-<li>Allow constraint names on the DEFAULT clause in a table definition</li>
-<li>Added the ".bail" command to the command-line shell</li>
-<li>Make CSV (comma separate value) output from the command-line shell
-more closely aligned to accepted practice</li>
-<li>Experimental FTS2 module added</li>
-<li>Use sqlite3_mprintf() instead of strdup() to avoid libc dependencies</li>
-<li>VACUUM uses a temporary file in the official TEMP folder, not in the
-same directory as the original database</li>
-<li>The prefix on temporary filenames on windows is changed from "sqlite"
-to "etilqs".</li>
-}
-
-chng {2006 October 9 (3.3.8)} {
-<li>Support for full text search using the
-<a href="http://www.sqlite.org/cvstrac/wiki?p=FullTextIndex">FTS1 module</a>
-(beta)</li>
-<li>Added OS-X locking patches (beta - disabled by default)</li>
-<li>Introduce extended error codes and add error codes for various
-kinds of I/O errors.</li>
-<li>Added support for IF EXISTS on CREATE/DROP TRIGGER/VIEW</li>
-<li>Fix the regression test suite so that it works with Tcl8.5</li>
-<li>Enhance sqlite3_set_authorizer() to provide notification of calls to
- SQL functions.</li>
-<li>Added experimental API: sqlite3_auto_extension()</li>
-<li>Various minor bug fixes</li>
-}
-
-chng {2006 August 12 (3.3.7)} {
-<li>Added support for
-<a href="http://www.sqlite.org/cvstrac/wiki?p=VirtualTables">virtual tables</a>
-(beta)</li>
-<li>Added support for
-<a href="http://www.sqlite.org/cvstrac/wiki?p=LoadableExtensions">
-dynamically loaded extensions</a> (beta)</li>
-<li>The
-<a href="capi3ref.html#sqlite3_interrupt">sqlite3_interrupt()</a>
-routine can be called for a different thread</li>
-<li>Added the <a href="lang_expr.html#match">MATCH</a> operator.</li>
-<li>The default file format is now 1.
-}
-
-chng {2006 June 6 (3.3.6)} {
-<li>Plays better with virus scanners on windows</li>
-<li>Faster :memory: databases</li>
-<li>Fix an obscure segfault in UTF-8 to UTF-16 conversions</li>
-<li>Added driver for OS/2</li>
-<li>Correct column meta-information returned for aggregate queries</li>
-<li>Enhanced output from EXPLAIN QUERY PLAN</li>
-<li>LIMIT 0 now works on subqueries</li>
-<li>Bug fixes and performance enhancements in the query optimizer</li>
-<li>Correctly handle NULL filenames in ATTACH and DETACH</li>
-<li>Inproved syntax error messages in the parser</li>
-<li>Fix type coercion rules for the IN operator</li>
-}
-
-chng {2006 April 5 (3.3.5)} {
-<li>CHECK constraints use conflict resolution algorithms correctly.</li>
-<li>The SUM() function throws an error on integer overflow.</li>
-<li>Choose the column names in a compound query from the left-most SELECT
- instead of the right-most.</li>
-<li>The sqlite3_create_collation() function
- honors the SQLITE_UTF16_ALIGNED flag.</li>
-<li>SQLITE_SECURE_DELETE compile-time option causes deletes to overwrite
- old data with zeros.</li>
-<li>Detect integer overflow in abs().</li>
-<li>The random() function provides 64 bits of randomness instead of
- only 32 bits.</li>
-<li>Parser detects and reports automaton stack overflow.</li>
-<li>Change the round() function to return REAL instead of TEXT.</li>
-<li>Allow WHERE clause terms on the left table of a LEFT OUTER JOIN to
- contain aggregate subqueries.</li>
-<li>Skip over leading spaces in text to numeric conversions.</li>
-<li>Various minor bug and documentation typo fixes and
- performance enhancements.</li>
-}
-
-chng {2006 February 11 (3.3.4)} {
-<li>Fix a blunder in the Unix mutex implementation that can lead to
-deadlock on multithreaded systems.</li>
-<li>Fix an alignment problem on 64-bit machines</li>
-<li>Added the fullfsync pragma.</li>
-<li>Fix an optimizer bug that could have caused some unusual LEFT OUTER JOINs
-to give incorrect results.</li>
-<li>The SUM function detects integer overflow and converts to accumulating
-an approximate result using floating point numbers</li>
-<li>Host parameter names can begin with '@' for compatibility with SQL Server.
-</li>
-<li>Other miscellaneous bug fixes</li>
-}
-
-chng {2006 January 31 (3.3.3)} {
-<li>Removed support for an ON CONFLICT clause on CREATE INDEX - it never
-worked correctly so this should not present any backward compatibility
-problems.</li>
-<li>Authorizer callback now notified of ALTER TABLE ADD COLUMN commands</li>
-<li>After any changes to the TEMP database schema, all prepared statements
-are invalidated and must be recreated using a new call to
-sqlite3_prepare()</li>
-<li>Other minor bug fixes in preparation for the first stable release
-of version 3.3</li>
-}
-
-chng {2006 January 24 (3.3.2 beta)} {
-<li>Bug fixes and speed improvements. Improved test coverage.</li>
-<li>Changes to the OS-layer interface: mutexes must now be recursive.</li>
-<li>Discontinue the use of thread-specific data for out-of-memory
-exception handling</li>
-}
-
-chng {2006 January 16 (3.3.1 alpha)} {
-<li>Countless bug fixes</li>
-<li>Speed improvements</li>
-<li>Database connections can now be used by multiple threads, not just
-the thread in which they were created.</li>
-}
-
-chng {2006 January 10 (3.3.0 alpha)} {
-<li>CHECK constraints</li>
-<li>IF EXISTS and IF NOT EXISTS clauses on CREATE/DROP TABLE/INDEX.</li>
-<li>DESC indices</li>
-<li>More efficient encoding of boolean values resulting in smaller database
-files</li>
-<li>More aggressive SQLITE_OMIT_FLOATING_POINT</li>
-<li>Separate INTEGER and REAL affinity</li>
-<li>Added a virtual function layer for the OS interface</li>
-<li>"exists" method added to the TCL interface</li>
-<li>Improved response to out-of-memory errors</li>
-<li>Database cache can be optionally shared between connections
-in the same thread</li>
-<li>Optional READ UNCOMMITTED isolation (instead of the default
-isolation level of SERIALIZABLE) and table level locking when
-database connections share a common cache.</li>
-}
-
-chng {2005 December 19 (3.2.8)} {
-<li>Fix an obscure bug that can cause database corruption under the
-following unusual circumstances: A large INSERT or UPDATE statement which
-is part of an even larger transaction fails due to a uniqueness contraint
-but the containing transaction commits.</li>
-}
-
-chng {2005 December 19 (2.8.17)} {
-<li>Fix an obscure bug that can cause database corruption under the
-following unusual circumstances: A large INSERT or UPDATE statement which
-is part of an even larger transaction fails due to a uniqueness contraint
-but the containing transaction commits.</li>
-}
-
-chng {2005 September 24 (3.2.7)} {
-<li>GROUP BY now considers NULLs to be equal again, as it should
-</li>
-<li>Now compiles on Solaris and OpenBSD and other Unix variants
-that lack the fdatasync() function</li>
-<li>Now compiles on MSVC++6 again</li>
-<li>Fix uninitialized variables causing malfunctions for various obscure
-queries</li>
-<li>Correctly compute a LEFT OUTER JOINs that is constrained on the
-left table only</li>
-}
-
-chng {2005 September 17 (3.2.6)} {
-<li>Fix a bug that can cause database corruption if a VACUUM (or
- autovacuum) fails and is rolled back on a database that is
- larger than 1GiB</li>
-<li>LIKE optiization now works for columns with COLLATE NOCASE</li>
-<li>ORDER BY and GROUP BY now use bounded memory</li>
-<li>Added support for COUNT(DISTINCT expr)</li>
-<li>Change the way SUM() handles NULL values in order to comply with
- the SQL standard</li>
-<li>Use fdatasync() instead of fsync() where possible in order to speed
- up commits slightly</li>
-<li>Use of the CROSS keyword in a join turns off the table reordering
- optimization</li>
-<li>Added the experimental and undocumented EXPLAIN QUERY PLAN capability</li>
-<li>Use the unicode API in windows</li>
-}
-
-chng {2005 August 27 (3.2.5)} {
-<li>Fix a bug effecting DELETE and UPDATE statements that changed
-more than 40960 rows.</li>
-<li>Change the makefile so that it no longer requires GNUmake extensions</li>
-<li>Fix the --enable-threadsafe option on the configure script</li>
-<li>Fix a code generator bug that occurs when the left-hand side of an IN
-operator is constant and the right-hand side is a SELECT statement</li>
-<li>The PRAGMA synchronous=off statement now disables syncing of the
-master journal file in addition to the normal rollback journals</li>
-}
-
-chng {2005 August 24 (3.2.4)} {
-<li>Fix a bug introduced in the previous release
-that can cause a segfault while generating code
-for complex WHERE clauses.</li>
-<li>Allow floating point literals to begin or end with a decimal point.</li>
-}
-
-chng {2005 August 21 (3.2.3)} {
-<li>Added support for the CAST operator</li>
-<li>Tcl interface allows BLOB values to be transferred to user-defined
-functions</li>
-<li>Added the "transaction" method to the Tcl interface</li>
-<li>Allow the DEFAULT value of a column to call functions that have constant
-operands</li>
-<li>Added the ANALYZE command for gathering statistics on indices and
-using those statistics when picking an index in the optimizer</li>
-<li>Remove the limit (formerly 100) on the number of terms in the
-WHERE clause</li>
-<li>The right-hand side of the IN operator can now be a list of expressions
-instead of just a list of constants</li>
-<li>Rework the optimizer so that it is able to make better use of indices</li>
-<li>The order of tables in a join is adjusted automatically to make
-better use of indices</li>
-<li>The IN operator is now a candidate for optimization even if the left-hand
-side is not the left-most term of the index. Multiple IN operators can be
-used with the same index.</li>
-<li>WHERE clause expressions using BETWEEN and OR are now candidates
-for optimization</li>
-<li>Added the "case_sensitive_like" pragma and the SQLITE_CASE_SENSITIVE_LIKE
-compile-time option to set its default value to "on".</li>
-<li>Use indices to help with GLOB expressions and LIKE expressions too
-when the case_sensitive_like pragma is enabled</li>
-<li>Added support for grave-accent quoting for compatibility with MySQL</li>
-<li>Improved test coverage</li>
-<li>Dozens of minor bug fixes</li>
-}
-
-chng {2005 June 13 (3.2.2)} {
-<li>Added the sqlite3_db_handle() API</li>
-<li>Added the sqlite3_get_autocommit() API</li>
-<li>Added a REGEXP operator to the parser. There is no function to back
-up this operator in the standard build but users can add their own using
-sqlite3_create_function()</li>
-<li>Speed improvements and library footprint reductions.</li>
-<li>Fix byte alignment problems on 64-bit architectures.</li>
-<li>Many, many minor bug fixes and documentation updates.</li>
-}
-
-chng {2005 March 29 (3.2.1)} {
-<li>Fix a memory allocation error in the new ADD COLUMN comment.</li>
-<li>Documentation updates</li>
-}
-
-chng {2005 March 21 (3.2.0)} {
-<li>Added support for ALTER TABLE ADD COLUMN.</li>
-<li>Added support for the "T" separator in ISO-8601 date/time strings.</li>
-<li>Improved support for Cygwin.</li>
-<li>Numerous bug fixes and documentation updates.</li>
-}
-
-chng {2005 March 16 (3.1.6)} {
-<li>Fix a bug that could cause database corruption when inserting
- record into tables with around 125 columns.</li>
-<li>sqlite3_step() is now much more likely to invoke the busy handler
- and less likely to return SQLITE_BUSY.</li>
-<li>Fix memory leaks that used to occur after a malloc() failure.</li>
-}
-
-chng {2005 March 11 (3.1.5)} {
-<li>The ioctl on OS-X to control syncing to disk is F_FULLFSYNC,
- not F_FULLSYNC. The previous release had it wrong.</li>
-}
-
-chng {2005 March 10 (3.1.4)} {
-<li>Fix a bug in autovacuum that could cause database corruption if
-a CREATE UNIQUE INDEX fails because of a constraint violation.
-This problem only occurs if the new autovacuum feature introduced in
-version 3.1 is turned on.</li>
-<li>The F_FULLSYNC ioctl (currently only supported on OS-X) is disabled
-if the synchronous pragma is set to something other than "full".</li>
-<li>Add additional forward compatibility to the future version 3.2 database
-file format.</li>
-<li>Fix a bug in WHERE clauses of the form (rowid<'2')</li>
-<li>New SQLITE_OMIT_... compile-time options added</li>
-<li>Updates to the man page</li>
-<li>Remove the use of strcasecmp() from the shell</li>
-<li>Windows DLL exports symbols Tclsqlite_Init and Sqlite_Init</li>
-}
-
-chng {2005 February 19 (3.1.3)} {
-<li>Fix a problem with VACUUM on databases from which tables containing
-AUTOINCREMENT have been dropped.</li>
-<li>Add forward compatibility to the future version 3.2 database file
-format.</li>
-<li>Documentation updates</li>
-}
-
-chng {2005 February 15 (3.1.2)} {
-<li>Fix a bug that can lead to database corruption if there are two
-open connections to the same database and one connection does a VACUUM
-and the second makes some change to the database.</li>
-<li>Allow "?" parameters in the LIMIT clause.</li>
-<li>Fix VACUUM so that it works with AUTOINCREMENT.</li>
-<li>Fix a race condition in AUTOVACUUM that can lead to corrupt databases</li>
-<li>Add a numeric version number to the sqlite3.h include file.</li>
-<li>Other minor bug fixes and performance enhancements.</li>
-}
-
-chng {2005 February 15 (2.8.16)} {
-<li>Fix a bug that can lead to database corruption if there are two
-open connections to the same database and one connection does a VACUUM
-and the second makes some change to the database.</li>
-<li>Correctly handle quoted names in CREATE INDEX statements.</li>
-<li>Fix a naming conflict between sqlite.h and sqlite3.h.</li>
-<li>Avoid excess heap usage when copying expressions.</li>
-<li>Other minor bug fixes.</li>
-}
-
-chng {2005 February 1 (3.1.1 BETA)} {
-<li>Automatic caching of prepared statements in the TCL interface</li>
-<li>ATTACH and DETACH as well as some other operations cause existing
- prepared statements to expire.</li>
-<li>Numerious minor bug fixes</li>
-}
-
-chng {2005 January 21 (3.1.0 ALPHA)} {
-<li>Autovacuum support added</li>
-<li>CURRENT_TIME, CURRENT_DATE, and CURRENT_TIMESTAMP added</li>
-<li>Support for the EXISTS clause added.</li>
-<li>Support for correlated subqueries added.</li>
-<li>Added the ESCAPE clause on the LIKE operator.</li>
-<li>Support for ALTER TABLE ... RENAME TABLE ... added</li>
-<li>AUTOINCREMENT keyword supported on INTEGER PRIMARY KEY</li>
-<li>Many SQLITE_OMIT_ macros inserts to omit features at compile-time
- and reduce the library footprint.</li>
-<li>The REINDEX command was added.</li>
-<li>The engine no longer consults the main table if it can get
- all the information it needs from an index.</li>
-<li>Many nuisance bugs fixed.</li>
-}
-
-chng {2004 October 11 (3.0.8)} {
-<li>Add support for DEFERRED, IMMEDIATE, and EXCLUSIVE transactions.</li>
-<li>Allow new user-defined functions to be created when there are
-already one or more precompiled SQL statements.<li>
-<li>Fix portability problems for Mingw/MSYS.</li>
-<li>Fix a byte alignment problem on 64-bit Sparc machines.</li>
-<li>Fix the ".import" command of the shell so that it ignores \r
-characters at the end of lines.</li>
-<li>The "csv" mode option in the shell puts strings inside double-quotes.</li>
-<li>Fix typos in documentation.</li>
-<li>Convert array constants in the code to have type "const".</li>
-<li>Numerous code optimizations, specially optimizations designed to
-make the code footprint smaller.</li>
-}
-
-chng {2004 September 18 (3.0.7)} {
-<li>The BTree module allocates large buffers using malloc() instead of
- off of the stack, in order to play better on machines with limited
- stack space.</li>
-<li>Fixed naming conflicts so that versions 2.8 and 3.0 can be
- linked and used together in the same ANSI-C source file.</li>
-<li>New interface: sqlite3_bind_parameter_index()</li>
-<li>Add support for wildcard parameters of the form: "?nnn"</li>
-<li>Fix problems found on 64-bit systems.</li>
-<li>Removed encode.c file (containing unused routines) from the
- version 3.0 source tree.</li>
-<li>The sqlite3_trace() callbacks occur before each statement
- is executed, not when the statement is compiled.</li>
-<li>Makefile updates and miscellaneous bug fixes.</li>
-}
-
-chng {2004 September 02 (3.0.6 beta)} {
-<li>Better detection and handling of corrupt database files.</li>
-<li>The sqlite3_step() interface returns SQLITE_BUSY if it is unable
- to commit a change because of a lock</li>
-<li>Combine the implementations of LIKE and GLOB into a single
- pattern-matching subroutine.</li>
-<li>Miscellaneous code size optimizations and bug fixes</li>
-}
-
-chng {2004 August 29 (3.0.5 beta)} {
-<li>Support for ":AAA" style bind parameter names.</li>
-<li>Added the new sqlite3_bind_parameter_name() interface.</li>
-<li>Support for TCL variable names embedded in SQL statements in the
- TCL bindings.</li>
-<li>The TCL bindings transfer data without necessarily doing a conversion
- to a string.</li>
-<li>The database for TEMP tables is not created until it is needed.</li>
-<li>Add the ability to specify an alternative temporary file directory
- using the "sqlite_temp_directory" global variable.</li>
-<li>A compile-time option (SQLITE_BUSY_RESERVED_LOCK) causes the busy
- handler to be called when there is contention for a RESERVED lock.</li>
-<li>Various bug fixes and optimizations</li>
-}
-
-chng {2004 August 8 (3.0.4 beta)} {
-<li>CREATE TABLE and DROP TABLE now work correctly as prepared statements.</li>
-<li>Fix a bug in VACUUM and UNIQUE indices.</li>
-<li>Add the ".import" command to the command-line shell.</li>
-<li>Fix a bug that could cause index corruption when an attempt to
- delete rows of a table is blocked by a pending query.</li>
-<li>Library size optimizations.</li>
-<li>Other minor bug fixes.</li>
-}
-
-chng {2004 July 22 (2.8.15)} {
-<li>This is a maintenance release only. Various minor bugs have been
-fixed and some portability enhancements are added.</li>
-}
-
-chng {2004 July 22 (3.0.3 beta)} {
-<li>The second beta release for SQLite 3.0.</li>
-<li>Add support for "PRAGMA page_size" to adjust the page size of
-the database.</li>
-<li>Various bug fixes and documentation updates.</li>
-}
-
-chng {2004 June 30 (3.0.2 beta)} {
-<li>The first beta release for SQLite 3.0.</li>
-}
-
-chng {2004 June 22 (3.0.1 alpha)} {
-<li><font color="red"><b>
- *** Alpha Release - Research And Testing Use Only ***</b></font>
-<li>Lots of bug fixes.</li>
-}
-
-chng {2004 June 18 (3.0.0 alpha)} {
-<li><font color="red"><b>
- *** Alpha Release - Research And Testing Use Only ***</b></font>
-<li>Support for internationalization including UTF-8, UTF-16, and
- user defined collating sequences.</li>
-<li>New file format that is 25% to 35% smaller for typical use.</li>
-<li>Improved concurrency.</li>
-<li>Atomic commits for ATTACHed databases.</li>
-<li>Remove cruft from the APIs.</li>
-<li>BLOB support.</li>
-<li>64-bit rowids.</li>
-<li><a href="version3.html">More information</a>.
-}
-
-chng {2004 June 9 (2.8.14)} {
-<li>Fix the min() and max() optimizer so that it works when the FROM
- clause consists of a subquery.</li>
-<li>Ignore extra whitespace at the end of of "." commands in the shell.</li>
-<li>Bundle sqlite_encode_binary() and sqlite_decode_binary() with the
- library.</li>
-<li>The TEMP_STORE and DEFAULT_TEMP_STORE pragmas now work.</li>
-<li>Code changes to compile cleanly using OpenWatcom.</li>
-<li>Fix VDBE stack overflow problems with INSTEAD OF triggers and
- NULLs in IN operators.</li>
-<li>Add the global variable sqlite_temp_directory which if set defines the
- directory in which temporary files are stored.</li>
-<li>sqlite_interrupt() plays well with VACUUM.</li>
-<li>Other minor bug fixes.</li>
-}
-
-chng {2004 March 8 (2.8.13)} {
-<li>Refactor parts of the code in order to make the code footprint
- smaller. The code is now also a little bit faster.</li>
-<li>sqlite_exec() is now implemented as a wrapper around sqlite_compile()
- and sqlite_step().</li>
-<li>The built-in min() and max() functions now honor the difference between
- NUMERIC and TEXT datatypes. Formerly, min() and max() always assumed
- their arguments were of type NUMERIC.</li>
-<li>New HH:MM:SS modifier to the built-in date/time functions.</li>
-<li>Experimental sqlite_last_statement_changes() API added. Fixed the
- the last_insert_rowid() function so that it works correctly with
- triggers.</li>
-<li>Add functions prototypes for the database encryption API.</li>
-<li>Fix several nuisance bugs.</li>
-}
-
-chng {2004 February 8 (2.8.12)} {
-<li>Fix a bug that will might corrupt the rollback journal if a power failure
- or external program halt occurs in the middle of a COMMIT. The corrupt
- journal can lead to database corruption when it is rolled back.</li>
-<li>Reduce the size and increase the speed of various modules, especially
- the virtual machine.</li>
-<li>Allow "<expr> IN <table>" as a shorthand for
- "<expr> IN (SELECT * FROM <table>".</li>
-<li>Optimizations to the sqlite_mprintf() routine.</li>
-<li>Make sure the MIN() and MAX() optimizations work within subqueries.</li>
-}
-
-chng {2004 January 14 (2.8.11)} {
-<li>Fix a bug in how the IN operator handles NULLs in subqueries. The bug
- was introduced by the previous release.</li>
-}
-
-chng {2004 January 13 (2.8.10)} {
-<li>Fix a potential database corruption problem on Unix caused by the fact
- that all posix advisory locks are cleared whenever you close() a file.
- The work around it to embargo all close() calls while locks are
- outstanding.</li>
-<li>Performance enhancements on some corner cases of COUNT(*).</li>
-<li>Make sure the in-memory backend response sanely if malloc() fails.</li>
-<li>Allow sqlite_exec() to be called from within user-defined SQL
- functions.</li>
-<li>Improved accuracy of floating-point conversions using "long double".</li>
-<li>Bug fixes in the experimental date/time functions.</li>
-}
-
-chng {2004 January 5 (2.8.9)} {
-<li>Fix a 32-bit integer overflow problem that could result in corrupt
- indices in a database if large negative numbers (less than -2147483648)
- were inserted into a indexed numeric column.</li>
-<li>Fix a locking problem on multi-threaded Linux implementations.</li>
-<li>Always use "." instead of "," as the decimal point even if the locale
- requests ",".</li>
-<li>Added UTC to localtime conversions to the experimental date/time
- functions.</li>
-<li>Bug fixes to date/time functions.</li>
-}
-
-chng {2003 December 17 (2.8.8)} {
-<li>Fix a critical bug introduced into 2.8.0 which could cause
- database corruption.</li>
-<li>Fix a problem with 3-way joins that do not use indices</li>
-<li>The VACUUM command now works with the non-callback API</li>
-<li>Improvements to the "PRAGMA integrity_check" command</li>
-}
-
-chng {2003 December 4 (2.8.7)} {
-<li>Added experimental sqlite_bind() and sqlite_reset() APIs.</li>
-<li>If the name of the database is an empty string, open a new database
- in a temporary file that is automatically deleted when the database
- is closed.</li>
-<li>Performance enhancements in the lemon-generated parser</li>
-<li>Experimental date/time functions revised.</li>
-<li>Disallow temporary indices on permanent tables.</li>
-<li>Documentation updates and typo fixes</li>
-<li>Added experimental sqlite_progress_handler() callback API</li>
-<li>Removed support for the Oracle8 outer join syntax.</li>
-<li>Allow GLOB and LIKE operators to work as functions.</li>
-<li>Other minor documentation and makefile changes and bug fixes.</li>
-}
-
-chng {2003 August 21 (2.8.6)} {
-<li>Moved the CVS repository to www.sqlite.org</li>
-<li>Update the NULL-handling documentation.</li>
-<li>Experimental date/time functions added.</li>
-<li>Bug fix: correctly evaluate a view of a view without segfaulting.</li>
-<li>Bug fix: prevent database corruption if you dropped a
- trigger that had the same name as a table.</li>
-<li>Bug fix: allow a VACUUM (without segfaulting) on an empty
- database after setting the EMPTY_RESULT_CALLBACKS pragma.</li>
-<li>Bug fix: if an integer value will not fit in a 32-bit int, store it in
- a double instead.</li>
-<li>Bug fix: Make sure the journal file directory entry is committed to disk
- before writing the database file.</li>
-}
-
-chng {2003 July 22 (2.8.5)} {
-<li>Make LIMIT work on a compound SELECT statement.</li>
-<li>LIMIT 0 now shows no rows. Use LIMIT -1 to see all rows.</li>
-<li>Correctly handle comparisons between an INTEGER PRIMARY KEY and
- a floating point number.</li>
-<li>Fix several important bugs in the new ATTACH and DETACH commands.</li>
-<li>Updated the <a href="nulls.html">NULL-handling document</a>.</li>
-<li>Allow NULL arguments in sqlite_compile() and sqlite_step().</li>
-<li>Many minor bug fixes</li>
-}
-
-chng {2003 June 29 (2.8.4)} {
-<li>Enhanced the "PRAGMA integrity_check" command to verify indices.</li>
-<li>Added authorization hooks for the new ATTACH and DETACH commands.</li>
-<li>Many documentation updates</li>
-<li>Many minor bug fixes</li>
-}
-
-chng {2003 June 4 (2.8.3)} {
-<li>Fix a problem that will corrupt the indices on a table if you
- do an INSERT OR REPLACE or an UPDATE OR REPLACE on a table that
- contains an INTEGER PRIMARY KEY plus one or more indices.</li>
-<li>Fix a bug in windows locking code so that locks work correctly
- when simultaneously accessed by Win95 and WinNT systems.</li>
-<li>Add the ability for INSERT and UPDATE statements to refer to the
- "rowid" (or "_rowid_" or "oid") columns.</li>
-<li>Other important bug fixes</li>
-}
-
-chng {2003 May 17 (2.8.2)} {
-<li>Fix a problem that will corrupt the database file if you drop a
- table from the main database that has a TEMP index.</li>
-}
-
-chng {2003 May 16 (2.8.1)} {
-<li>Reactivated the VACUUM command that reclaims unused disk space in
- a database file.</li>
-<li>Added the ATTACH and DETACH commands to allow interacting with multiple
- database files at the same time.</li>
-<li>Added support for TEMP triggers and indices.</li>
-<li>Added support for in-memory databases.</li>
-<li>Removed the experimental sqlite_open_aux_file(). Its function is
- subsumed in the new ATTACH command.</li>
-<li>The precedence order for ON CONFLICT clauses was changed so that
- ON CONFLICT clauses on BEGIN statements have a higher precedence than
- ON CONFLICT clauses on constraints.
-<li>Many, many bug fixes and compatibility enhancements.</li>
-}
-
-chng {2003 Feb 16 (2.8.0)} {
-<li>Modified the journal file format to make it more resistant to corruption
- that can occur after an OS crash or power failure.</li>
-<li>Added a new C/C++ API that does not use callback for returning data.</li>
-}
-
-chng {2003 Jan 25 (2.7.6)} {
-<li>Performance improvements. The library is now much faster.</li>
-<li>Added the <b>sqlite_set_authorizer()</b> API. Formal documentation has
- not been written - see the source code comments for instructions on
- how to use this function.</li>
-<li>Fix a bug in the GLOB operator that was preventing it from working
- with upper-case letters.</li>
-<li>Various minor bug fixes.</li>
-}
-
-chng {2002 Dec 27 (2.7.5)} {
-<li>Fix an uninitialized variable in pager.c which could (with a probability
- of about 1 in 4 billion) result in a corrupted database.</li>
-}
-
-chng {2002 Dec 17 (2.7.4)} {
-<li>Database files can now grow to be up to 2^41 bytes. The old limit
- was 2^31 bytes.</li>
-<li>The optimizer will now scan tables in the reverse if doing so will
- satisfy an ORDER BY ... DESC clause.</li>
-<li>The full pathname of the database file is now remembered even if
- a relative path is passed into sqlite_open(). This allows
- the library to continue operating correctly after a chdir().</li>
-<li>Speed improvements in the VDBE.</li>
-<li>Lots of little bug fixes.</li>
-}
-
-chng {2002 Oct 30 (2.7.3)} {
-<li>Various compiler compatibility fixes.</li>
-<li>Fix a bug in the "expr IN ()" operator.</li>
-<li>Accept column names in parentheses.</li>
-<li>Fix a problem with string memory management in the VDBE</li>
-<li>Fix a bug in the "table_info" pragma"</li>
-<li>Export the sqlite_function_type() API function in the Windows DLL</li>
-<li>Fix locking behavior under windows</li>
-<li>Fix a bug in LEFT OUTER JOIN</li>
-}
-
-chng {2002 Sep 25 (2.7.2)} {
-<li>Prevent journal file overflows on huge transactions.</li>
-<li>Fix a memory leak that occurred when sqlite_open() failed.</li>
-<li>Honor the ORDER BY and LIMIT clause of a SELECT even if the
- result set is used for an INSERT.</li>
-<li>Do not put write locks on the file used to hold TEMP tables.</li>
-<li>Added documentation on SELECT DISTINCT and on how SQLite handles NULLs.</li>
-<li>Fix a problem that was causing poor performance when many thousands
- of SQL statements were executed by a single sqlite_exec() call.</li>
-}
-
-chng {2002 Aug 31 (2.7.1)} {
-<li>Fix a bug in the ORDER BY logic that was introduced in version 2.7.0</li>
-<li>C-style comments are now accepted by the tokenizer.</li>
-<li>INSERT runs a little faster when the source is a SELECT statement.</li>
-}
-
-chng {2002 Aug 25 (2.7.0)} {
-<li>Make a distinction between numeric and text values when sorting.
- Text values sort according to memcmp(). Numeric values sort in
- numeric order.</li>
-<li>Allow multiple simultaneous readers under windows by simulating
- the reader/writers locks that are missing from Win95/98/ME.</li>
-<li>An error is now returned when trying to start a transaction if
- another transaction is already active.</li>
-}
-
-chng {2002 Aug 12 (2.6.3)} {
-<li>Add the ability to read both little-endian and big-endian databases.
- So database created under SunOS or MacOSX can be read and written
- under Linux or Windows and vice versa.</li>
-<li>Convert to the new website: http://www.sqlite.org/</li>
-<li>Allow transactions to span Linux Threads</li>
-<li>Bug fix in the processing of the ORDER BY clause for GROUP BY queries</li>
-}
-
-chng {2002 Jly 30 (2.6.2)} {
-<li>Text files read by the COPY command can now have line terminators
- of LF, CRLF, or CR.</li>
-<li>SQLITE_BUSY is handled correctly if encountered during database
- initialization.</li>
-<li>Fix to UPDATE triggers on TEMP tables.</li>
-<li>Documentation updates.</li>
-}
-
-chng {2002 Jly 19 (2.6.1)} {
-<li>Include a static string in the library that responds to the RCS
- "ident" command and which contains the library version number.</li>
-<li>Fix an assertion failure that occurred when deleting all rows of
- a table with the "count_changes" pragma turned on.</li>
-<li>Better error reporting when problems occur during the automatic
- 2.5.6 to 2.6.0 database format upgrade.</li>
-}
-
-chng {2002 Jly 17 (2.6.0)} {
-<li>Change the format of indices to correct a design flaw the originated
- with version 2.1.0. <font color="red">*** This is an incompatible
- file format change ***</font> When version 2.6.0 or later of the
- library attempts to open a database file created by version 2.5.6 or
- earlier, it will automatically and irreversibly convert the file format.
- <b>Make backup copies of older database files before opening them with
- version 2.6.0 of the library.</b>
- </li>
-}
-
-chng {2002 Jly 7 (2.5.6)} {
-<li>Fix more problems with rollback. Enhance the test suite to exercise
- the rollback logic extensively in order to prevent any future problems.
- </li>
-}
-
-chng {2002 Jly 6 (2.5.5)} {
-<li>Fix a bug which could cause database corruption during a rollback.
- This bugs was introduced in version 2.4.0 by the freelist
- optimization of checking [410].</li>
-<li>Fix a bug in aggregate functions for VIEWs.</li>
-<li>Other minor changes and enhancements.</li>
-}
-
-chng {2002 Jly 1 (2.5.4)} {
-<li>Make the "AS" keyword optional again.</li>
-<li>The datatype of columns now appear in the 4th argument to the
- callback.</li>
-<li>Added the <b>sqlite_open_aux_file()</b> API, though it is still
- mostly undocumented and untested.</li>
-<li>Added additional test cases and fixed a few bugs that those
- test cases found.</li>
-}
-
-chng {2002 Jun 24 (2.5.3)} {
-<li>Bug fix: Database corruption can occur due to the optimization
- that was introduced in version 2.4.0 (check-in [410]). The problem
- should now be fixed. The use of versions 2.4.0 through 2.5.2 is
- not recommended.</li>
-}
-
-chng {2002 Jun 24 (2.5.2)} {
-<li>Added the new <b>SQLITE_TEMP_MASTER</b> table which records the schema
- for temporary tables in the same way that <b>SQLITE_MASTER</b> does for
- persistent tables.</li>
-<li>Added an optimization to UNION ALL</li>
-<li>Fixed a bug in the processing of LEFT OUTER JOIN</li>
-<li>The LIMIT clause now works on subselects</li>
-<li>ORDER BY works on subselects</li>
-<li>There is a new TypeOf() function used to determine if an expression
- is numeric or text.</li>
-<li>Autoincrement now works for INSERT from a SELECT.</li>
-}
-
-chng {2002 Jun 19 (2.5.1)} {
-<li>The query optimizer now attempts to implement the ORDER BY clause
- using an index. Sorting is still used if not suitable index is
- available.</li>
-}
-
-chng {2002 Jun 17 (2.5.0)} {
-<li>Added support for row triggers.</li>
-<li>Added SQL-92 compliant handling of NULLs.</li>
-<li>Add support for the full SQL-92 join syntax and LEFT OUTER JOINs.</li>
-<li>Double-quoted strings interpreted as column names not text literals.</li>
-<li>Parse (but do not implement) foreign keys.</li>
-<li>Performance improvements in the parser, pager, and WHERE clause code
- generator.</li>
-<li>Make the LIMIT clause work on subqueries. (ORDER BY still does not
- work, though.)</li>
-<li>Added the "%Q" expansion to sqlite_*_printf().</li>
-<li>Bug fixes too numerous to mention (see the change log).</li>
-}
-
-chng {2002 May 09 (2.4.12)} {
-<li>Added logic to detect when the library API routines are called out
- of sequence.</li>
-}
-
-chng {2002 May 08 (2.4.11)} {
-<li>Bug fix: Column names in the result set were not being generated
- correctly for some (rather complex) VIEWs. This could cause a
- segfault under certain circumstances.</li>
-}
-
-chng {2002 May 02 (2.4.10)} {
-<li>Bug fix: Generate correct column headers when a compound SELECT is used
- as a subquery.</li>
-<li>Added the sqlite_encode_binary() and sqlite_decode_binary() functions to
- the source tree. But they are not yet linked into the library.</li>
-<li>Documentation updates.</li>
-<li>Export the sqlite_changes() function from windows DLLs.</li>
-<li>Bug fix: Do not attempt the subquery flattening optimization on queries
- that lack a FROM clause. To do so causes a segfault.</li>
-}
-
-chng {2002 Apr 21 (2.4.9)} {
-<li>Fix a bug that was causing the precompiled binary of SQLITE.EXE to
- report "out of memory" under Windows 98.</li>
-}
-
-chng {2002 Apr 20 (2.4.8)} {
-<li>Make sure VIEWs are created after their corresponding TABLEs in the
- output of the <b>.dump</b> command in the shell.</li>
-<li>Speed improvements: Do not do synchronous updates on TEMP tables.</li>
-<li>Many improvements and enhancements to the shell.</li>
-<li>Make the GLOB and LIKE operators functions that can be overridden
- by a programmer. This allows, for example, the LIKE operator to
- be changed to be case sensitive.</li>
-}
-
-chng {2002 Apr 06 (2.4.7)} {
-<li>Add the ability to put TABLE.* in the column list of a
- SELECT statement.</li>
-<li>Permit SELECT statements without a FROM clause.</li>
-<li>Added the <b>last_insert_rowid()</b> SQL function.</li>
-<li>Do not count rows where the IGNORE conflict resolution occurs in
- the row count.</li>
-<li>Make sure functions expressions in the VALUES clause of an INSERT
- are correct.</li>
-<li>Added the <b>sqlite_changes()</b> API function to return the number
- of row that changed in the most recent operation.</li>
-}
-
-chng {2002 Apr 02 (2.4.6)} {
-<li>Bug fix: Correctly handle terms in the WHERE clause of a join that
- do not contain a comparison operator.</li>
-}
-
-chng {2002 Apr 01 (2.4.5)} {
-<li>Bug fix: Correctly handle functions that appear in the WHERE clause
- of a join.</li>
-<li>When the PRAGMA vdbe_trace=ON is set, correctly print the P3 operand
- value when it is a pointer to a structure rather than a pointer to
- a string.</li>
-<li>When inserting an explicit NULL into an INTEGER PRIMARY KEY, convert
- the NULL value into a unique key automatically.</li>
-}
-
-chng {2002 Mar 24 (2.4.4)} {
-<li>Allow "VIEW" to be a column name</li>
-<li>Added support for CASE expressions (patch from Dan Kennedy)</li>
-<li>Added RPMS to the delivery (patches from Doug Henry)</li>
-<li>Fix typos in the documentation</li>
-<li>Cut over configuration management to a new CVS repository with
- its own CVSTrac bug tracking system.</li>
-}
-
-chng {2002 Mar 22 (2.4.3)} {
-<li>Fix a bug in SELECT that occurs when a compound SELECT is used as a
- subquery in the FROM of a SELECT.</li>
-<li>The <b>sqlite_get_table()</b> function now returns an error if you
- give it two or more SELECTs that return different numbers of columns.</li>
-}
-
-chng {2002 Mar 14 (2.4.2)} {
-<li>Bug fix: Fix an assertion failure that occurred when ROWID was a column
- in a SELECT statement on a view.</li>
-<li>Bug fix: Fix an uninitialized variable in the VDBE that would could an
- assert failure.</li>
-<li>Make the os.h header file more robust in detecting when the compile is
- for windows and when it is for unix.</li>
-}
-
-chng {2002 Mar 13 (2.4.1)} {
-<li>Using an unnamed subquery in a FROM clause would cause a segfault.</li>
-<li>The parser now insists on seeing a semicolon or the end of input before
- executing a statement. This avoids an accidental disaster if the
- WHERE keyword is misspelled in an UPDATE or DELETE statement.</li>
-}
-
-
-chng {2002 Mar 10 (2.4.0)} {
-<li>Change the name of the sanity_check PRAGMA to <b>integrity_check</b>
- and make it available in all compiles.</li>
-<li>SELECT min() or max() of an indexed column with no WHERE or GROUP BY
- clause is handled as a special case which avoids a complete table scan.</li>
-<li>Automatically generated ROWIDs are now sequential.</li>
-<li>Do not allow dot-commands of the command-line shell to occur in the
- middle of a real SQL command.</li>
-<li>Modifications to the "lemon" parser generator so that the parser tables
- are 4 times smaller.</li>
-<li>Added support for user-defined functions implemented in C.</li>
-<li>Added support for new functions: <b>coalesce()</b>, <b>lower()</b>,
- <b>upper()</b>, and <b>random()</b>
-<li>Added support for VIEWs.</li>
-<li>Added the subquery flattening optimizer.</li>
-<li>Modified the B-Tree and Pager modules so that disk pages that do not
- contain real data (free pages) are not journaled and are not
- written from memory back to the disk when they change. This does not
- impact database integrity, since the
- pages contain no real data, but it does make large INSERT operations
- about 2.5 times faster and large DELETEs about 5 times faster.</li>
-<li>Made the CACHE_SIZE pragma persistent</li>
-<li>Added the SYNCHRONOUS pragma</li>
-<li>Fixed a bug that was causing updates to fail inside of transactions when
- the database contained a temporary table.</li>
-}
-
-chng {2002 Feb 18 (2.3.3)} {
-<li>Allow identifiers to be quoted in square brackets, for compatibility
- with MS-Access.</li>
-<li>Added support for sub-queries in the FROM clause of a SELECT.</li>
-<li>More efficient implementation of sqliteFileExists() under Windows.
- (by Joel Luscy)</li>
-<li>The VALUES clause of an INSERT can now contain expressions, including
- scalar SELECT clauses.</li>
-<li>Added support for CREATE TABLE AS SELECT</li>
-<li>Bug fix: Creating and dropping a table all within a single
- transaction was not working.</li>
-}
-
-chng {2002 Feb 14 (2.3.2)} {
-<li>Bug fix: There was an incorrect assert() in pager.c. The real code was
- all correct (as far as is known) so everything should work OK if you
- compile with -DNDEBUG=1. When asserts are not disabled, there
- could be a fault.</li>
-}
-
-chng {2002 Feb 13 (2.3.1)} {
-<li>Bug fix: An assertion was failing if "PRAGMA full_column_names=ON;" was
- set and you did a query that used a rowid, like this:
- "SELECT rowid, * FROM ...".</li>
-}
-
-chng {2002 Jan 30 (2.3.0)} {
-<li>Fix a serious bug in the INSERT command which was causing data to go
- into the wrong columns if the data source was a SELECT and the INSERT
- clauses specified its columns in some order other than the default.</li>
-<li>Added the ability to resolve constraint conflicts is ways other than
- an abort and rollback. See the documentation on the "ON CONFLICT"
- clause for details.</li>
-<li>Temporary files are now automatically deleted by the operating system
- when closed. There are no more dangling temporary files on a program
- crash. (If the OS crashes, fsck will delete the file after reboot
- under Unix. I do not know what happens under Windows.)</li>
-<li>NOT NULL constraints are honored.</li>
-<li>The COPY command puts NULLs in columns whose data is '\N'.</li>
-<li>In the COPY command, backslash can now be used to escape a newline.</li>
-<li>Added the SANITY_CHECK pragma.</li>
-}
-
-chng {2002 Jan 28 (2.2.5)} {
-<li>Important bug fix: the IN operator was not working if either the
- left-hand or right-hand side was derived from an INTEGER PRIMARY KEY.</li>
-<li>Do not escape the backslash '\' character in the output of the
- <b>sqlite</b> command-line access program.</li>
-}
-
-chng {2002 Jan 22 (2.2.4)} {
-<li>The label to the right of an AS in the column list of a SELECT can now
- be used as part of an expression in the WHERE, ORDER BY, GROUP BY, and/or
- HAVING clauses.</li>
-<li>Fix a bug in the <b>-separator</b> command-line option to the <b>sqlite</b>
- command.</li>
-<li>Fix a problem with the sort order when comparing upper-case strings against
- characters greater than 'Z' but less than 'a'.</li>
-<li>Report an error if an ORDER BY or GROUP BY expression is constant.</li>
-}
-
-chng {2002 Jan 16 (2.2.3)} {
-<li>Fix warning messages in VC++ 7.0. (Patches from nicolas352001)</li>
-<li>Make the library thread-safe. (The code is there and appears to work
- but has not been stressed.)</li>
-<li>Added the new <b>sqlite_last_insert_rowid()</b> API function.</li>
-}
-
-chng {2002 Jan 13 (2.2.2)} {
-<li>Bug fix: An assertion was failing when a temporary table with an index
- had the same name as a permanent table created by a separate process.</li>
-<li>Bug fix: Updates to tables containing an INTEGER PRIMARY KEY and an
- index could fail.</li>
-}
-
-chng {2002 Jan 9 (2.2.1)} {
-<li>Bug fix: An attempt to delete a single row of a table with a WHERE
- clause of "ROWID=x" when no such rowid exists was causing an error.</li>
-<li>Bug fix: Passing in a NULL as the 3rd parameter to <b>sqlite_open()</b>
- would sometimes cause a coredump.</li>
-<li>Bug fix: DROP TABLE followed by a CREATE TABLE with the same name all
- within a single transaction was causing a coredump.</li>
-<li>Makefile updates from A. Rottmann</li>
-}
-
-chng {2001 Dec 22 (2.2.0)} {
-<li>Columns of type INTEGER PRIMARY KEY are actually used as the primary
- key in underlying B-Tree representation of the table.</li>
-<li>Several obscure, unrelated bugs were found and fixed while
- implemented the integer primary key change of the previous bullet.</li>
-<li>Added the ability to specify "*" as part of a larger column list in
- the result section of a SELECT statement. For example:
- <nobr>"<b>SELECT rowid, * FROM table1;</b>"</nobr>.</li>
-<li>Updates to comments and documentation.</li>
-}
-
-chng {2001 Dec 14 (2.1.7)} {
-<li>Fix a bug in <b>CREATE TEMPORARY TABLE</b> which was causing the
- table to be initially allocated in the main database file instead
- of in the separate temporary file. This bug could cause the library
- to suffer an assertion failure and it could cause "page leaks" in the
- main database file.
-<li>Fix a bug in the b-tree subsystem that could sometimes cause the first
- row of a table to be repeated during a database scan.</li>
-}
-
-chng {2001 Dec 14 (2.1.6)} {
-<li>Fix the locking mechanism yet again to prevent
- <b>sqlite_exec()</b> from returning SQLITE_PROTOCOL
- unnecessarily. This time the bug was a race condition in
- the locking code. This change effects both POSIX and Windows users.</li>
-}
-
-chng {2001 Dec 6 (2.1.5)} {
-<li>Fix for another problem (unrelated to the one fixed in 2.1.4)
- that sometimes causes <b>sqlite_exec()</b> to return SQLITE_PROTOCOL
- unnecessarily. This time the bug was
- in the POSIX locking code and should not effect windows users.</li>
-}
-
-chng {2001 Dec 4 (2.1.4)} {
-<li>Sometimes <b>sqlite_exec()</b> would return SQLITE_PROTOCOL when it
- should have returned SQLITE_BUSY.</li>
-<li>The fix to the previous bug uncovered a deadlock which was also
- fixed.</li>
-<li>Add the ability to put a single .command in the second argument
- of the sqlite shell</li>
-<li>Updates to the FAQ</li>
-}
-
-chng {2001 Nov 23 (2.1.3)} {
-<li>Fix the behavior of comparison operators
- (ex: "<b><</b>", "<b>==</b>", etc.)
- so that they are consistent with the order of entries in an index.</li>
-<li>Correct handling of integers in SQL expressions that are larger than
- what can be represented by the machine integer.</li>
-}
-
-chng {2001 Nov 22 (2.1.2)} {
-<li>Changes to support 64-bit architectures.</li>
-<li>Fix a bug in the locking protocol.</li>
-<li>Fix a bug that could (rarely) cause the database to become
- unreadable after a DROP TABLE due to corruption to the SQLITE_MASTER
- table.</li>
-<li>Change the code so that version 2.1.1 databases that were rendered
- unreadable by the above bug can be read by this version of
- the library even though the SQLITE_MASTER table is (slightly)
- corrupted.</li>
-}
-
-chng {2001 Nov 13 (2.1.1)} {
-<li>Bug fix: Sometimes arbitrary strings were passed to the callback
- function when the actual value of a column was NULL.</li>
-}
-
-chng {2001 Nov 12 (2.1.0)} {
-<li>Change the format of data records so that records up to 16MB in size
- can be stored.</li>
-<li>Change the format of indices to allow for better query optimization.</li>
-<li>Implement the "LIMIT ... OFFSET ..." clause on SELECT statements.</li>
-}
-
-chng {2001 Nov 3 (2.0.8)} {
-<li>Made selected parameters in API functions <b>const</b>. This should
- be fully backwards compatible.</li>
-<li>Documentation updates</li>
-<li>Simplify the design of the VDBE by restricting the number of sorters
- and lists to 1.
- In practice, no more than one sorter and one list was ever used anyhow.
- </li>
-}
-
-chng {2001 Oct 21 (2.0.7)} {
-<li>Any UTF-8 character or ISO8859 character can be used as part of
- an identifier.</li>
-<li>Patches from Christian Werner to improve ODBC compatibility and to
- fix a bug in the round() function.</li>
-<li>Plug some memory leaks that use to occur if malloc() failed.
- We have been and continue to be memory leak free as long as
- malloc() works.</li>
-<li>Changes to some test scripts so that they work on Windows in
- addition to Unix.</li>
-}
-
-chng {2001 Oct 19 (2.0.6)} {
-<li>Added the EMPTY_RESULT_CALLBACKS pragma</li>
-<li>Support for UTF-8 and ISO8859 characters in column and table names.</li>
-<li>Bug fix: Compute correct table names with the FULL_COLUMN_NAMES pragma
- is turned on.</li>
-}
-
-chng {2001 Oct 14 (2.0.5)} {
-<li>Added the COUNT_CHANGES pragma.</li>
-<li>Changes to the FULL_COLUMN_NAMES pragma to help out the ODBC driver.</li>
-<li>Bug fix: "SELECT count(*)" was returning NULL for empty tables.
- Now it returns 0.</li>
-}
-
-chng {2001 Oct 13 (2.0.4)} {
-<li>Bug fix: an obscure and relatively harmless bug was causing one of
- the tests to fail when gcc optimizations are turned on. This release
- fixes the problem.</li>
-}
-
-chng {2001 Oct 13 (2.0.3)} {
-<li>Bug fix: the <b>sqlite_busy_timeout()</b> function was delaying 1000
- times too long before failing.</li>
-<li>Bug fix: an assertion was failing if the disk holding the database
- file became full or stopped accepting writes for some other reason.
- New tests were added to detect similar problems in the future.</li>
-<li>Added new operators: <b>&</b> (bitwise-and)
- <b>|</b> (bitwise-or), <b>~</b> (ones-complement),
- <b><<</b> (shift left), <b>>></b> (shift right).</li>
-<li>Added new functions: <b>round()</b> and <b>abs()</b>.</li>
-}
-
-chng {2001 Oct 9 (2.0.2)} {
-<li>Fix two bugs in the locking protocol. (One was masking the other.)</li>
-<li>Removed some unused "#include <unistd.h>" that were causing problems
- for VC++.</li>
-<li>Fixed <b>sqlite.h</b> so that it is usable from C++</li>
-<li>Added the FULL_COLUMN_NAMES pragma. When set to "ON", the names of
- columns are reported back as TABLE.COLUMN instead of just COLUMN.</li>
-<li>Added the TABLE_INFO() and INDEX_INFO() pragmas to help support the
- ODBC interface.</li>
-<li>Added support for TEMPORARY tables and indices.</li>
-}
-
-chng {2001 Oct 2 (2.0.1)} {
-<li>Remove some C++ style comments from btree.c so that it will compile
- using compilers other than gcc.</li>
-<li>The ".dump" output from the shell does not work if there are embedded
- newlines anywhere in the data. This is an old bug that was carried
- forward from version 1.0. To fix it, the ".dump" output no longer
- uses the COPY command. It instead generates INSERT statements.</li>
-<li>Extend the expression syntax to support "expr NOT NULL" (with a
- space between the "NOT" and the "NULL") in addition to "expr NOTNULL"
- (with no space).</li>
-}
-
-chng {2001 Sep 28 (2.0.0)} {
-<li>Automatically build binaries for Linux and Windows and put them on
- the website.</li>
-}
-
-chng {2001 Sep 28 (2.0-alpha-4)} {
-<li>Incorporate makefile patches form A. Rottmann to use LIBTOOL</li>
-}
-
-chng {2001 Sep 27 (2.0-alpha-3)} {
-<li>SQLite now honors the UNIQUE keyword in CREATE UNIQUE INDEX. Primary
- keys are required to be unique.</li>
-<li>File format changed back to what it was for alpha-1</li>
-<li>Fixes to the rollback and locking behavior</li>
-}
-
-chng {2001 Sep 20 (2.0-alpha-2)} {
-<li>Initial release of version 2.0. The idea of renaming the library
- to "SQLus" was abandoned in favor of keeping the "SQLite" name and
- bumping the major version number.</li>
-<li>The pager and btree subsystems added back. They are now the only
- available backend.</li>
-<li>The Dbbe abstraction and the GDBM and memory drivers were removed.</li>
-<li>Copyright on all code was disclaimed. The library is now in the
- public domain.</li>
-}
-
-chng {2001 Jul 23 (1.0.32)} {
-<li>Pager and btree subsystems removed. These will be used in a follow-on
- SQL server library named "SQLus".</li>
-<li>Add the ability to use quoted strings as table and column names in
- expressions.</li>
-}
-
-chng {2001 Apr 14 (1.0.31)} {
-<li>Pager subsystem added but not yet used.</li>
-<li>More robust handling of out-of-memory errors.</li>
-<li>New tests added to the test suite.</li>
-}
-
-chng {2001 Apr 6 (1.0.30)} {
-<li>Remove the <b>sqlite_encoding</b> TCL variable that was introduced
- in the previous version.</li>
-<li>Add options <b>-encoding</b> and <b>-tcl-uses-utf</b> to the
- <b>sqlite</b> TCL command.</li>
-<li>Add tests to make sure that tclsqlite was compiled using Tcl header
- files and libraries that match.</li>
-}
-
-chng {2001 Apr 5 (1.0.29)} {
-<li>The library now assumes data is stored as UTF-8 if the --enable-utf8
- option is given to configure. The default behavior is to assume
- iso8859-x, as it has always done. This only makes a difference for
- LIKE and GLOB operators and the LENGTH and SUBSTR functions.</li>
-<li>If the library is not configured for UTF-8 and the Tcl library
- is one of the newer ones that uses UTF-8 internally,
- then a conversion from UTF-8 to iso8859 and
- back again is done inside the TCL interface.</li>
-}
-
-chng {2001 Apr 4 (1.0.28)} {
-<li>Added limited support for transactions. At this point, transactions
- will do table locking on the GDBM backend. There is no support (yet)
- for rollback or atomic commit.</li>
-<li>Added special column names ROWID, OID, and _ROWID_ that refer to the
- unique random integer key associated with every row of every table.</li>
-<li>Additional tests added to the regression suite to cover the new ROWID
- feature and the TCL interface bugs mentioned below.</li>
-<li>Changes to the "lemon" parser generator to help it work better when
- compiled using MSVC.</li>
-<li>Bug fixes in the TCL interface identified by Oleg Oleinick.</li>
-}
-
-chng {2001 Mar 20 (1.0.27)} {
-<li>When doing DELETE and UPDATE, the library used to write the record
- numbers of records to be deleted or updated into a temporary file.
- This is changed so that the record numbers are held in memory.</li>
-<li>The DELETE command without a WHILE clause just removes the database
- files from the disk, rather than going through and deleting record
- by record.</li>
-}
-
-chng {2001 Mar 20 (1.0.26)} {
-<li>A serious bug fixed on Windows. Windows users should upgrade.
- No impact to Unix.</li>
-}
-
-chng {2001 Mar 15 (1.0.25)} {
-<li>Modify the test scripts to identify tests that depend on system
- load and processor speed and
- to warn the user that a failure of one of those (rare) tests does
- not necessarily mean the library is malfunctioning. No changes to
- code.
- </li>
-}
-
-chng {2001 Mar 14 (1.0.24)} {
-<li>Fix a bug which was causing
- the UPDATE command to fail on systems where "malloc(0)" returns
- NULL. The problem does not appear Windows, Linux, or HPUX but does
- cause the library to fail on QNX.
- </li>
-}
-
-chng {2001 Feb 19 (1.0.23)} {
-<li>An unrelated (and minor) bug from Mark Muranwski fixed. The algorithm
- for figuring out where to put temporary files for a "memory:" database
- was not working quite right.
- </li>
-}
-
-chng {2001 Feb 19 (1.0.22)} {
-<li>The previous fix was not quite right. This one seems to work better.
- </li>
-}
-
-chng {2001 Feb 19 (1.0.21)} {
-<li>The UPDATE statement was not working when the WHERE clause contained
- some terms that could be satisfied using indices and other terms that
- could not. Fixed.</li>
-}
-
-chng {2001 Feb 11 (1.0.20)} {
-<li>Merge development changes into the main trunk. Future work toward
- using a BTree file structure will use a separate CVS source tree. This
- CVS tree will continue to support the GDBM version of SQLite only.</li>
-}
-
-chng {2001 Feb 6 (1.0.19)} {
-<li>Fix a strange (but valid) C declaration that was causing problems
- for QNX. No logical changes.</li>
-}
-
-chng {2001 Jan 4 (1.0.18)} {
-<li>Print the offending SQL statement when an error occurs.</li>
-<li>Do not require commas between constraints in CREATE TABLE statements.</li>
-<li>Added the "-echo" option to the shell.</li>
-<li>Changes to comments.</li>
-}
-
-chng {2000 Dec 10 (1.0.17)} {
-<li>Rewrote <b>sqlite_complete()</b> to make it faster.</li>
-<li>Minor tweaks to other code to make it run a little faster.</li>
-<li>Added new tests for <b>sqlite_complete()</b> and for memory leaks.</li>
-}
-
-chng {2000 Dec 4 (1.0.16)} {
-<li>Documentation updates. Mostly fixing of typos and spelling errors.</li>
-}
-
-chng {2000 Oct 23 (1.0.15)} {
-<li>Documentation updates</li>
-<li>Some sanity checking code was removed from the inner loop of vdbe.c
- to help the library to run a little faster. The code is only
- removed if you compile with -DNDEBUG.</li>
-}
-
-chng {2000 Oct 19 (1.0.14)} {
-<li>Added a "memory:" backend driver that stores its database in an
- in-memory hash table.</li>
-}
-
-chng {2000 Oct 18 (1.0.13)} {
-<li>Break out the GDBM driver into a separate file in anticipation
- to added new drivers.</li>
-<li>Allow the name of a database to be prefixed by the driver type.
- For now, the only driver type is "gdbm:".</li>
-}
-
-chng {2000 Oct 16 (1.0.12)} {
-<li>Fixed an off-by-one error that was causing a coredump in
- the '%q' format directive of the new
- <b>sqlite_..._printf()</b> routines.</li>
-<li>Added the <b>sqlite_interrupt()</b> interface.</li>
-<li>In the shell, <b>sqlite_interrupt()</b> is invoked when the
- user presses Control-C</li>
-<li>Fixed some instances where <b>sqlite_exec()</b> was
- returning the wrong error code.</li>
-}
-
-chng {2000 Oct 11 (1.0.10)} {
-<li>Added notes on how to compile for Windows95/98.</li>
-<li>Removed a few variables that were not being used. Etc.</li>
-}
-
-chng {2000 Oct 8 (1.0.9)} {
-<li>Added the <b>sqlite_..._printf()</b> interface routines.</li>
-<li>Modified the <b>sqlite</b> shell program to use the new interface
- routines.</li>
-<li>Modified the <b>sqlite</b> shell program to print the schema for
- the built-in SQLITE_MASTER table, if explicitly requested.</li>
-}
-
-chng {2000 Sep 30 (1.0.8)} {
-<li>Begin writing documentation on the TCL interface.</li>
-}
-
-chng {2000 Sep 29 (Not Released)} {
-<li>Added the <b>sqlite_get_table()</b> API</li>
-<li>Updated the documentation for due to the above change.</li>
-<li>Modified the <b>sqlite</b> shell to make use of the new
- sqlite_get_table() API in order to print a list of tables
- in multiple columns, similar to the way "ls" prints filenames.</li>
-<li>Modified the <b>sqlite</b> shell to print a semicolon at the
- end of each CREATE statement in the output of the ".schema" command.</li>
-}
-
-chng {2000 Sep 21 (Not Released)} {
-<li>Change the tclsqlite "eval" method to return a list of results if
- no callback script is specified.</li>
-<li>Change tclsqlite.c to use the Tcl_Obj interface</li>
-<li>Add tclsqlite.c to the libsqlite.a library</li>
-}
-
-chng {2000 Sep 13 (Version 1.0.5)} {
-<li>Changed the print format for floating point values from "%g" to "%.15g".
- </li>
-<li>Changed the comparison function so that numbers in exponential notation
- (ex: 1.234e+05) sort in numerical order.</li>
-}
-
-chng {2000 Aug 28 (Version 1.0.4)} {
-<li>Added functions <b>length()</b> and <b>substr()</b>.</li>
-<li>Fix a bug in the <b>sqlite</b> shell program that was causing
- a coredump when the output mode was "column" and the first row
- of data contained a NULL.</li>
-}
-
-chng {2000 Aug 22 (Version 1.0.3)} {
-<li>In the sqlite shell, print the "Database opened READ ONLY" message
- to stderr instead of stdout.</li>
-<li>In the sqlite shell, now print the version number on initial startup.</li>
-<li>Add the <b>sqlite_version[]</b> string constant to the library</li>
-<li>Makefile updates</li>
-<li>Bug fix: incorrect VDBE code was being generated for the following
- circumstance: a query on an indexed table containing a WHERE clause with
- an IN operator that had a subquery on its right-hand side.</li>
-}
-
-chng {2000 Aug 18 (Version 1.0.1)} {
-<li>Fix a bug in the configure script.</li>
-<li>Minor revisions to the website.</li>
-}
-
-chng {2000 Aug 17 (Version 1.0)} {
-<li>Change the <b>sqlite</b> program so that it can read
- databases for which it lacks write permission. (It used to
- refuse all access if it could not write.)</li>
-}
-
-chng {2000 Aug 9} {
-<li>Treat carriage returns as white space.</li>
-}
-
-chng {2000 Aug 8} {
-<li>Added pattern matching to the ".table" command in the "sqlite"
-command shell.</li>
-}
-
-chng {2000 Aug 4} {
-<li>Documentation updates</li>
-<li>Added "busy" and "timeout" methods to the Tcl interface</li>
-}
-
-chng {2000 Aug 3} {
-<li>File format version number was being stored in sqlite_master.tcl
- multiple times. This was harmless, but unnecessary. It is now fixed.</li>
-}
-
-chng {2000 Aug 2} {
-<li>The file format for indices was changed slightly in order to work
- around an inefficiency that can sometimes come up with GDBM when
- there are large indices having many entries with the same key.
- <font color="red">** Incompatible Change **</font></li>
-}
-
-chng {2000 Aug 1} {
-<li>The parser's stack was overflowing on a very long UPDATE statement.
- This is now fixed.</li>
-}
-
-chng {2000 July 31} {
-<li>Finish the <a href="vdbe.html">VDBE tutorial</a>.</li>
-<li>Added documentation on compiling to WindowsNT.</li>
-<li>Fix a configuration program for WindowsNT.</li>
-<li>Fix a configuration problem for HPUX.</li>
-}
-
-chng {2000 July 29} {
-<li>Better labels on column names of the result.</li>
-}
-
-chng {2000 July 28} {
-<li>Added the <b>sqlite_busy_handler()</b>
- and <b>sqlite_busy_timeout()</b> interface.</li>
-}
-
-chng {2000 June 23} {
-<li>Begin writing the <a href="vdbe.html">VDBE tutorial</a>.</li>
-}
-
-chng {2000 June 21} {
-<li>Clean up comments and variable names. Changes to documentation.
- No functional changes to the code.</li>
-}
-
-chng {2000 June 19} {
-<li>Column names in UPDATE statements were case sensitive.
- This mistake has now been fixed.</li>
-}
-
-chng {2000 June 16} {
-<li>Added the concatenate string operator (||)</li>
-}
-
-chng {2000 June 12} {
-<li>Added the fcnt() function to the SQL interpreter. The fcnt() function
- returns the number of database "Fetch" operations that have occurred.
- This function is designed for use in test scripts to verify that
- queries are efficient and appropriately optimized. Fcnt() has no other
- useful purpose, as far as I know.</li>
-<li>Added a bunch more tests that take advantage of the new fcnt() function.
- The new tests did not uncover any new problems.</li>
-}
-
-chng {2000 June 8} {
-<li>Added lots of new test cases</li>
-<li>Fix a few bugs discovered while adding test cases</li>
-<li>Begin adding lots of new documentation</li>
-}
-
-chng {2000 June 6} {
-<li>Added compound select operators: <B>UNION</b>, <b>UNION ALL</B>,
-<b>INTERSECT</b>, and <b>EXCEPT</b></li>
-<li>Added support for using <b>(SELECT ...)</b> within expressions</li>
-<li>Added support for <b>IN</b> and <b>BETWEEN</b> operators</li>
-<li>Added support for <b>GROUP BY</b> and <b>HAVING</b></li>
-<li>NULL values are now reported to the callback as a NULL pointer
- rather than an empty string.</li>
-}
-
-chng {2000 June 3} {
-<li>Added support for default values on columns of a table.</li>
-<li>Improved test coverage. Fixed a few obscure bugs found by the
-improved tests.</li>
-}
-
-chng {2000 June 2} {
-<li>All database files to be modified by an UPDATE, INSERT or DELETE are
-now locked before any changes are made to any files.
-This makes it safe (I think) to access
-the same database simultaneously from multiple processes.</li>
-<li>The code appears stable so we are now calling it "beta".</li>
-}
-
-chng {2000 June 1} {
-<li>Better support for file locking so that two or more processes
-(or threads)
-can access the same database simultaneously. More work needed in
-this area, though.</li>
-}
-
-chng {2000 May 31} {
-<li>Added support for aggregate functions (Ex: <b>COUNT(*)</b>, <b>MIN(...)</b>)
-to the SELECT statement.</li>
-<li>Added support for <B>SELECT DISTINCT ...</B></li>
-}
-
-chng {2000 May 30} {
-<li>Added the <b>LIKE</b> operator.</li>
-<li>Added a <b>GLOB</b> operator: similar to <B>LIKE</B>
-but it uses Unix shell globbing wildcards instead of the '%'
-and '_' wildcards of SQL.</li>
-<li>Added the <B>COPY</b> command patterned after
-<a href="http://www.postgresql.org/">PostgreSQL</a> so that SQLite
-can now read the output of the <b>pg_dump</b> database dump utility
-of PostgreSQL.</li>
-<li>Added a <B>VACUUM</B> command that that calls the
-<b>gdbm_reorganize()</b> function on the underlying database
-files.</li>
-<li>And many, many bug fixes...</li>
-}
-
-chng {2000 May 29} {
-<li>Initial Public Release of Alpha code</li>
-}
-
-puts {
-</DL>
-}
-footer {$Id:}
+++ /dev/null
-# This file contains TCL procedures used to generate standard parts of
-# web pages.
-#
-
-proc header {txt} {
- puts "<html><head><title>$txt</title></head>"
- puts {<DIV class="pdf_ignore">}
- puts \
-{<body bgcolor="white" link="#50695f" vlink="#508896">
-<table width="100%" border="0">
-<tr><td valign="top">
-<a href="index.html"><img src="sqlite.gif" border="none"></a></td>
-<td width="100%"></td>
-<td valign="bottom">
-<ul>
-<li><a href="http://www.sqlite.org/cvstrac/tktnew">bugs</a></li>
-<li><a href="changes.html">changes</a></li>
-<li><a href="contrib">contrib</a></li>
-<li><a href="download.html#cvs">cvs repository</a></li>
-<li><a href="docs.html">documentation</a></li>
-</ul>
-</td>
-<td width="10"></td>
-<td valign="bottom">
-<ul>
-<li><a href="download.html">download</a></li>
-<li><a href="faq.html">faq</a></li>
-<li><a href="index.html">home</a></li>
-<li><a href="copyright.html">license</a></li>
-<li><a href="index.html">news</a></li>
-</ul>
-</td>
-<td width="10"></td>
-<td valign="bottom">
-<ul>
-<li><a href="quickstart.html">quick start</a></li>
-<li><a href="support.html">support</a></li>
-<li><a href="lang.html">syntax</a></li>
-<li><a href="http://www.sqlite.org/cvstrac/timeline">timeline</a></li>
-<li><a href="http://www.sqlite.org/cvstrac/wiki">wiki</a></li>
-</ul>
-</td>
-</tr></table>
-<table width="100%">
-<tr><td bgcolor="#80a796"></td></tr>
-</table>}
- puts </DIV>
-}
-
-proc footer {{rcsid {}}} {
- puts {
-<table width="100%">
-<tr><td bgcolor="#80a796"></td></tr>
-</table>}
- set date [lrange $rcsid 3 4]
- if {$date!=""} {
- puts "<small><i>This page last modified on $date</i></small>"
- }
- puts {</body></html>}
-}
-
-
-# The following proc is used to ensure consistent formatting in the
-# HTML generated by lang.tcl and pragma.tcl.
-#
-proc Syntax {args} {
- puts {<table cellpadding="10" class=pdf_syntax>}
- foreach {rule body} $args {
- puts "<tr><td align=\"right\" valign=\"top\">"
- puts "<i><font color=\"#ff3434\">$rule</font></i> ::=</td>"
- regsub -all < $body {%LT} body
- regsub -all > $body {%GT} body
- regsub -all %LT $body {</font></b><i><font color="#ff3434">} body
- regsub -all %GT $body {</font></i><b><font color="#2c2cf0">} body
- regsub -all {[]|[*?]} $body {</font></b>&<b><font color="#2c2cf0">} body
- regsub -all "\n" [string trim $body] "<br>\n" body
- regsub -all "\n *" $body "\n\\ \\ \\ \\ " body
- regsub -all {[|,.*()]} $body {<big>&</big>} body
- regsub -all { = } $body { <big>=</big> } body
- regsub -all {STAR} $body {<big>*</big>} body
- ## These metacharacters must be handled to undo being
- ## treated as SQL punctuation characters above.
- regsub -all {RPPLUS} $body {</font></b>)+<b><font color="#2c2cf0">} body
- regsub -all {LP} $body {</font></b>(<b><font color="#2c2cf0">} body
- regsub -all {RP} $body {</font></b>)<b><font color="#2c2cf0">} body
- ## Place the left-hand side of the rule in the 2nd table column.
- puts "<td><b><font color=\"#2c2cf0\">$body</font></b></td></tr>"
- }
- puts {</table>}
-}
+++ /dev/null
-#
-# Run this Tcl script to generate the compile.html file.
-#
-set rcsid {$Id: compile.tcl,v 1.5 2005/03/19 15:10:45 drh Exp $ }
-source common.tcl
-header {Compilation Options For SQLite}
-
-puts {
-<h1>Compilation Options For SQLite</h1>
-
-<p>
-For most purposes, SQLite can be built just fine using the default
-compilation options. However, if required, the compile-time options
-documented below can be used to
-<a href="#omitfeatures">omit SQLite features</a> (resulting in
-a smaller compiled library size) or to change the
-<a href="#defaults">default values</a> of some parameters.
-</p>
-<p>
-Every effort has been made to ensure that the various combinations
-of compilation options work harmoniously and produce a working library.
-Nevertheless, it is strongly recommended that the SQLite test-suite
-be executed to check for errors before using an SQLite library built
-with non-standard compilation options.
-</p>
-<a name="defaults"></a>
-<h2>Options To Set Default Parameter Values</h2>
-
-<p><b>SQLITE_DEFAULT_AUTOVACUUM=<i><1 or 0></i></b><br>
-This macro determines if SQLite creates databases with the
-<a href="pragma.html#pragma_auto_vacuum">auto-vacuum</a>
-flag set by default. The default value is 0 (do not create auto-vacuum
-databases). In any case the compile-time default may be overridden by the
-"PRAGMA auto_vacuum" command.
-</p>
-
-<p><b>SQLITE_DEFAULT_CACHE_SIZE=<i><pages></i></b><br>
-This macro sets the default size of the page-cache for each attached
-database, in pages. This can be overridden by the "PRAGMA cache_size"
-comamnd. The default value is 2000.
-</p>
-
-<p><b>SQLITE_DEFAULT_PAGE_SIZE=<i><bytes></i></b><br>
-This macro is used to set the default page-size used when a
-database is created. The value assigned must be a power of 2. The
-default value is 1024. The compile-time default may be overridden at
-runtime by the "PRAGMA page_size" command.
-</p>
-
-<p><b>SQLITE_DEFAULT_TEMP_CACHE_SIZE=<i><pages></i></b><br>
-This macro sets the default size of the page-cache for temporary files
-created by SQLite to store intermediate results, in pages. It does
-not affect the page-cache for the temp database, where tables created
-using "CREATE TEMP TABLE" are stored. The default value is 500.
-</p>
-
-<p><b>SQLITE_MAX_PAGE_SIZE=<i><bytes></i></b><br>
-This is used to set the maximum allowable page-size that can
-be specified by the "PRAGMA page_size" command. The default value
-is 8192.
-</p>
-
-<a name="omitfeatures"></a>
-<h2>Options To Omit Features</h2>
-
-<p>The following options are used to reduce the size of the compiled
-library by omiting optional features. This is probably only useful
-in embedded systems where space is especially tight, as even with all
-features included the SQLite library is relatively small. Don't forget
-to tell your compiler to optimize for binary size! (the -Os option if
-using GCC).</p>
-
-<p>The macros in this section do not require values. The following
-compilation switches all have the same effect:<br>
--DSQLITE_OMIT_ALTERTABLE<br>
--DSQLITE_OMIT_ALTERTABLE=1<br>
--DSQLITE_OMIT_ALTERTABLE=0
-</p>
-
-<p>If any of these options are defined, then the same set of SQLITE_OMIT_XXX
-options must also be defined when using the 'lemon' tool to generate a parse.c
-file. Because of this, these options may only used when the library is built
-from source, not from the collection of pre-packaged C files provided for
-non-UNIX like platforms on the website.
-</p>
-
-<p><b>SQLITE_OMIT_ALTERTABLE</b><br>
-When this option is defined, the
-<a href="lang_altertable.html">ALTER TABLE</a> command is not included in the
-library. Executing an ALTER TABLE statement causes a parse error.
-</p>
-
-<p><b>SQLITE_OMIT_AUTHORIZATION</b><br>
-Defining this option omits the authorization callback feature from the
-library. The <a href="capi3ref.html#sqlite3_set_authorizer">
-sqlite3_set_authorizer()</a> API function is not present in the library.
-</p>
-
-<p><b>SQLITE_OMIT_AUTOVACUUM</b><br>
-If this option is defined, the library cannot create or write to
-databases that support
-<a href="pragma.html#pragma_auto_vacuum">auto-vacuum</a>. Executing a
-"PRAGMA auto_vacuum" statement is not an error, but does not return a value
-or modify the auto-vacuum flag in the database file. If a database that
-supports auto-vacuum is opened by a library compiled with this option, it
-is automatically opened in read-only mode.
-</p>
-
-<p><b>SQLITE_OMIT_AUTOINCREMENT</b><br>
-This option is used to omit the AUTOINCREMENT functionality. When this
-is macro is defined, columns declared as "INTEGER PRIMARY KEY AUTOINCREMENT"
-behave in the same way as columns declared as "INTEGER PRIMARY KEY" when a
-NULL is inserted. The sqlite_sequence system table is neither created, nor
-respected if it already exists.
-</p>
-<p><i>TODO: Need a link here - AUTOINCREMENT is not yet documented</i><p>
-
-<p><b>SQLITE_OMIT_BLOB_LITERAL</b><br>
-When this option is defined, it is not possible to specify a blob in
-an SQL statement using the X'ABCD' syntax.</p>
-}
-#<p>WARNING: The VACUUM command depends on this syntax for vacuuming databases
-#that contain blobs, so disabling this functionality may render a database
-#unvacuumable.
-#</p>
-#<p><i>TODO: Need a link here - is that syntax documented anywhere?</i><p>
-puts {
-
-<p><b>SQLITE_OMIT_COMPLETE</b><br>
-This option causes the <a href="capi3ref.html#sqlite3_complete">
-sqlite3_complete</a> API to be omitted.
-</p>
-
-<p><b>SQLITE_OMIT_COMPOUND_SELECT</b><br>
-This option is used to omit the compound SELECT functionality.
-<a href="lang_select.html">SELECT statements</a> that use the
-UNION, UNION ALL, INTERSECT or EXCEPT compound SELECT operators will
-cause a parse error.
-</p>
-
-<p><b>SQLITE_OMIT_CONFLICT_CLAUSE</b><br>
-In the future, this option will be used to omit the
-<a href="lang_conflict.html">ON CONFLICT</a> clause from the library.
-</p>
-
-<p><b>SQLITE_OMIT_DATETIME_FUNCS</b><br>
-If this option is defined, SQLite's built-in date and time manipulation
-functions are omitted. Specifically, the SQL functions julianday(), date(),
-time(), datetime() and strftime() are not available. The default column
-values CURRENT_TIME, CURRENT_DATE and CURRENT_DATETIME are still available.
-</p>
-
-<p><b>SQLITE_OMIT_EXPLAIN</b><br>
-Defining this option causes the EXPLAIN command to be omitted from the
-library. Attempting to execute an EXPLAIN statement will cause a parse
-error.
-</p>
-
-<p><b>SQLITE_OMIT_FLOATING_POINT</b><br>
-This option is used to omit floating-point number support from the SQLite
-library. When specified, specifying a floating point number as a literal
-(i.e. "1.01") results in a parse error.
-</p>
-<p>In the future, this option may also disable other floating point
-functionality, for example the sqlite3_result_double(),
-sqlite3_bind_double(), sqlite3_value_double() and sqlite3_column_double()
-API functions.
-</p>
-
-<p><b>SQLITE_OMIT_FOREIGN_KEY</b><br>
-If this option is defined, FOREIGN KEY clauses in column declarations are
-ignored.
-</p>
-
-<p><b>SQLITE_OMIT_INTEGRITY_CHECK</b><br>
-This option may be used to omit the
-<a href="pragma.html#pragma_integrity_check">"PRAGMA integrity_check"</a>
-command from the compiled library.
-</p>
-
-<p><b>SQLITE_OMIT_MEMORYDB</b><br>
-When this is defined, the library does not respect the special database
-name ":memory:" (normally used to create an in-memory database). If
-":memory:" is passed to sqlite3_open(), a file with this name will be
-opened or created.
-</p>
-
-<p><b>SQLITE_OMIT_PAGER_PRAGMAS</b><br>
-Defining this option omits pragmas related to the pager subsystem from
-the build. Currently, the
-<a href="pragma.html#pragma_default_cache_size">default_cache_size</a> and
-<a href="pragma.html#pragma_cache_size">cache_size</a> pragmas are omitted.
-</p>
-
-<p><b>SQLITE_OMIT_PRAGMA</b><br>
-This option is used to omit the <a href="pragma.html">PRAGMA command</a>
-from the library. Note that it is useful to define the macros that omit
-specific pragmas in addition to this, as they may also remove supporting code
-in other sub-systems. This macro removes the PRAGMA command only.
-</p>
-
-<p><b>SQLITE_OMIT_PROGRESS_CALLBACK</b><br>
-This option may be defined to omit the capability to issue "progress"
-callbacks during long-running SQL statements. The
-<a href="capi3ref.html#sqlite3_progress_handler">sqlite3_progress_handler()</a>
-API function is not present in the library.
-
-<p><b>SQLITE_OMIT_REINDEX</b><br>
-When this option is defined, the <a href="lang_reindex.html">REINDEX</a>
-command is not included in the library. Executing a REINDEX statement causes
-a parse error.
-</p>
-
-<p><b>SQLITE_OMIT_SCHEMA_PRAGMAS</b><br>
-Defining this option omits pragmas for querying the database schema from
-the build. Currently, the
-<a href="pragma.html#pragma_table_info">table_info</a>,
-<a href="pragma.html#pragma_index_info">index_info</a>,
-<a href="pragma.html#pragma_index_list">index_list</a> and
-<a href="pragma.html#pragma_database_list">database_list</a>
-pragmas are omitted.
-</p>
-
-<p><b>SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS</b><br>
-Defining this option omits pragmas for querying and modifying the
-database schema version and user version from the build. Specifically, the
-<a href="pragma.html#pragma_schema_version">schema_version</a> and
-<a href="pragma.html#pragma_user_version">user_version</a>
-pragmas are omitted.
-
-<p><b>SQLITE_OMIT_SUBQUERY</b><br>
-<p>If defined, support for sub-selects and the IN() operator are omitted.
-</p>
-
-<p><b>SQLITE_OMIT_TCL_VARIABLE</b><br>
-<p>If this macro is defined, then the special "$<variable-name>" syntax
-used to automatically bind SQL variables to TCL variables is omitted.
-</p>
-
-<p><b>SQLITE_OMIT_TRIGGER</b><br>
-Defining this option omits support for VIEW objects. Neither the
-<a href="lang_createtrigger.html">CREATE TRIGGER</a> or
-<a href="lang_droptrigger.html">DROP TRIGGER</a>
-commands are available in this case, attempting to execute either will result
-in a parse error.
-</p>
-<p>
-WARNING: If this macro is defined, it will not be possible to open a database
-for which the schema contains TRIGGER objects.
-</p>
-
-<p><b>SQLITE_OMIT_UTF16</b><br>
-This macro is used to omit support for UTF16 text encoding. When this is
-defined all API functions that return or accept UTF16 encoded text are
-unavailable. These functions can be identified by the fact that they end
-with '16', for example sqlite3_prepare16(), sqlite3_column_text16() and
-sqlite3_bind_text16().
-</p>
-
-<p><b>SQLITE_OMIT_VACUUM</b><br>
-When this option is defined, the <a href="lang_vacuum.html">VACUUM</a>
-command is not included in the library. Executing a VACUUM statement causes
-a parse error.
-</p>
-
-<p><b>SQLITE_OMIT_VIEW</b><br>
-Defining this option omits support for VIEW objects. Neither the
-<a href="lang_createview.html">CREATE VIEW</a> or
-<a href="lang_dropview.html">DROP VIEW</a>
-commands are available in this case, attempting to execute either will result
-in a parse error.
-</p>
-<p>
-WARNING: If this macro is defined, it will not be possible to open a database
-for which the schema contains VIEW objects.
-</p>
-}
-footer $rcsid
+++ /dev/null
-#
-# Run this Tcl script to generate the constraint.html file.
-#
-set rcsid {$Id: conflict.tcl,v 1.4 2004/10/10 17:24:55 drh Exp $ }
-source common.tcl
-header {Constraint Conflict Resolution in SQLite}
-puts {
-<h1>Constraint Conflict Resolution in SQLite</h1>
-
-<p>
-In most SQL databases, if you have a UNIQUE constraint on
-a table and you try to do an UPDATE or INSERT that violates
-the constraint, the database will abort the operation in
-progress, back out any prior changes associated with
-UPDATE or INSERT command, and return an error.
-This is the default behavior of SQLite.
-Beginning with version 2.3.0, though, SQLite allows you to
-define alternative ways for dealing with constraint violations.
-This article describes those alternatives and how to use them.
-</p>
-
-<h2>Conflict Resolution Algorithms</h2>
-
-<p>
-SQLite defines five constraint conflict resolution algorithms
-as follows:
-</p>
-
-<dl>
-<dt><b>ROLLBACK</b></dt>
-<dd><p>When a constraint violation occurs, an immediate ROLLBACK
-occurs, thus ending the current transaction, and the command aborts
-with a return code of SQLITE_CONSTRAINT. If no transaction is
-active (other than the implied transaction that is created on every
-command) then this algorithm works the same as ABORT.</p></dd>
-
-<dt><b>ABORT</b></dt>
-<dd><p>When a constraint violation occurs, the command backs out
-any prior changes it might have made and aborts with a return code
-of SQLITE_CONSTRAINT. But no ROLLBACK is executed so changes
-from prior commands within the same transaction
-are preserved. This is the default behavior for SQLite.</p></dd>
-
-<dt><b>FAIL</b></dt>
-<dd><p>When a constraint violation occurs, the command aborts with a
-return code SQLITE_CONSTRAINT. But any changes to the database that
-the command made prior to encountering the constraint violation
-are preserved and are not backed out. For example, if an UPDATE
-statement encountered a constraint violation on the 100th row that
-it attempts to update, then the first 99 row changes are preserved
-by change to rows 100 and beyond never occur.</p></dd>
-
-<dt><b>IGNORE</b></dt>
-<dd><p>When a constraint violation occurs, the one row that contains
-the constraint violation is not inserted or changed. But the command
-continues executing normally. Other rows before and after the row that
-contained the constraint violation continue to be inserted or updated
-normally. No error is returned.</p></dd>
-
-<dt><b>REPLACE</b></dt>
-<dd><p>When a UNIQUE constraint violation occurs, the pre-existing row
-that caused the constraint violation is removed prior to inserting
-or updating the current row. Thus the insert or update always occurs.
-The command continues executing normally. No error is returned.</p></dd>
-</dl>
-
-<h2>Why So Many Choices?</h2>
-
-<p>SQLite provides multiple conflict resolution algorithms for a
-couple of reasons. First, SQLite tries to be roughly compatible with as
-many other SQL databases as possible, but different SQL database
-engines exhibit different conflict resolution strategies. For
-example, PostgreSQL always uses ROLLBACK, Oracle always uses ABORT, and
-MySQL usually uses FAIL but can be instructed to use IGNORE or REPLACE.
-By supporting all five alternatives, SQLite provides maximum
-portability.</p>
-
-<p>Another reason for supporting multiple algorithms is that sometimes
-it is useful to use an algorithm other than the default.
-Suppose, for example, you are
-inserting 1000 records into a database, all within a single
-transaction, but one of those records is malformed and causes
-a constraint error. Under PostgreSQL or Oracle, none of the
-1000 records would get inserted. In MySQL, some subset of the
-records that appeared before the malformed record would be inserted
-but the rest would not. Neither behavior is especially helpful.
-What you really want is to use the IGNORE algorithm to insert
-all but the malformed record.</p>
-
-}
-footer $rcsid
+++ /dev/null
-<html>
-<body bgcolor="white">
-<h1 align="center">
-Copyright Release for<br>
-Contributions To SQLite
-</h1>
-
-<p>
-SQLite is software that implements an embeddable SQL database engine.
-SQLite is available for free download from http://www.sqlite.org/.
-The principal author and maintainer of SQLite has disclaimed all
-copyright interest in his contributions to SQLite
-and thus released his contributions into the public domain.
-In order to keep the SQLite software unencumbered by copyright
-claims, the principal author asks others who may from time to
-time contribute changes and enhancements to likewise disclaim
-their own individual copyright interest.
-</p>
-
-<p>
-Because the SQLite software found at http://www.sqlite.org/ is in the
-public domain, anyone is free to download the SQLite software
-from that website, make changes to the software, use, distribute,
-or sell the modified software, under either the original name or
-under some new name, without any need to obtain permission, pay
-royalties, acknowledge the original source of the software, or
-in any other way compensate, identify, or notify the original authors.
-Nobody is in any way compelled to contribute their SQLite changes and
-enhancements back to the SQLite website. This document concerns
-only changes and enhancements to SQLite that are intentionally and
-deliberately contributed back to the SQLite website.
-</p>
-
-<p>
-For the purposes of this document, "SQLite software" shall mean any
-computer source code, documentation, makefiles, test scripts, or
-other information that is published on the SQLite website,
-http://www.sqlite.org/. Precompiled binaries are excluded from
-the definition of "SQLite software" in this document because the
-process of compiling the software may introduce information from
-outside sources which is not properly a part of SQLite.
-</p>
-
-<p>
-The header comments on the SQLite source files exhort the reader to
-share freely and to never take more than one gives.
-In the spirit of that exhortation I make the following declarations:
-</p>
-
-<ol>
-<li><p>
-I dedicate to the public domain
-any and all copyright interest in the SQLite software that
-was publicly available on the SQLite website (http://www.sqlite.org/) prior
-to the date of the signature below and any changes or enhancements to
-the SQLite software
-that I may cause to be published on that website in the future.
-I make this dedication for the benefit of the public at large and
-to the detriment of my heirs and successors. I intend this
-dedication to be an overt act of relinquishment in perpetuity of
-all present and future rights to the SQLite software under copyright
-law.
-</p></li>
-
-<li><p>
-To the best of my knowledge and belief, the changes and enhancements that
-I have contributed to SQLite are either originally written by me
-or are derived from prior works which I have verified are also
-in the public domain and are not subject to claims of copyright
-by other parties.
-</p></li>
-
-<li><p>
-To the best of my knowledge and belief, no individual, business, organization,
-government, or other entity has any copyright interest
-in the SQLite software as it existed on the
-SQLite website as of the date on the signature line below.
-</p></li>
-
-<li><p>
-I agree never to publish any additional information
-to the SQLite website (by CVS, email, scp, FTP, or any other means) unless
-that information is an original work of authorship by me or is derived from
-prior published versions of SQLite.
-I agree never to copy and paste code into the SQLite code base from
-other sources.
-I agree never to publish on the SQLite website any information that
-would violate a law or breach a contract.
-</p></li>
-</ol>
-
-<p>
-<table width="100%" cellpadding="0" cellspacing="0">
-<tr>
-<td width="60%" valign="top">
-Signature:
-<p> </p>
-<p> </p>
-<p> </p>
-</td><td valign="top" align="left">
-Date:
-</td></tr>
-<td colspan=2>
-Name (printed):
-</td>
-</tr>
-</table>
-</body>
-</html>
+++ /dev/null
-set rcsid {$Id: copyright.tcl,v 1.7 2007/05/06 21:20:43 drh Exp $}
-source common.tcl
-header {SQLite Copyright}
-puts {
-<h2>SQLite Copyright</h2>
-
-<table align="right" vspace="0" hspace="10" border="1" cellpadding="20">
-<tr><td align="center">
-<img src="nocopy.gif"><br>
-SQLite is in the<br>
-<a href="http://en.wikipedia.org/wiki/Public_Domain">Public Domain</a>
-</td></tr>
-</table>
-
-<p>
-All of the deliverable code in SQLite has been dedicated to the
-<a href="http://en.wikipedia.org/wiki/Public_Domain">public domain</a>
-by the authors.
-All code authors, and representatives of the companies they work for,
-have signed affidavits dedicating their contributions to
-the public domain and originals of
-those signed affidavits are stored in a firesafe at the main offices
-of <a href="http://www.hwaci.com">Hwaci</a>.
-Anyone is free to copy, modify, publish, use, compile, sell, or distribute
-the original SQLite code, either in source code form or as a compiled binary,
-for any purpose, commercial or non-commercial, and by any means.
-</p>
-
-<p>
-The previous paragraph applies to the deliverable code in SQLite -
-those parts of the SQLite library that you actually bundle and
-ship with a larger application. Portions of the documentation and
-some code used as part of the build process might fall under
-other licenses. The details here are unclear. We do not worry
-about the licensing of the documentation and build code so much
-because none of these things are part of the core deliverable
-SQLite library.
-</p>
-
-<p>
-All of the deliverable code in SQLite has been written from scratch.
-No code has been taken from other projects or from the open
-internet. Every line of code can be traced back to its original
-author, and all of those authors have public domain dedications
-on file. So the SQLite code base is clean and is
-uncontaminated with licensed code from other projects.
-</p>
-
-<h2>Obtaining An Explicit License To Use SQLite</h2>
-
-<p>
-Even though SQLite is in the public domain and does not require
-a license, some users want to obtain a license anyway. Some reasons
-for obtaining a license include:
-</p>
-
-<ul>
-<li> You are using SQLite in a jurisdiction that does not recognize
- the public domain. </li>
-<li> You are using SQLite in a jurisdiction that does not recognize
- the right of an author to dedicate their work to the public
- domain. </li>
-<li> You want to hold a tangible legal document
- as evidence that you have the legal right to use and distribute
- SQLite. </li>
-<li> Your legal department tells you that you have to purchase a license.
- </li>
-</ul>
-
-<p>
-If you feel like you really have to purchase a license for SQLite,
-<a href="http://www.hwaci.com/">Hwaci</a>, the company that employs
-the architect and principal developers of SQLite, will sell you
-one.
-Please contact:
-</p>
-
-<blockquote>
-D. Richard Hipp <br />
-Hwaci - Applied Software Research <br />
-704.948.4565 <br />
-<a href="mailto:drh@hwaci.com">drh@hwaci.com</a>
-</blockquote>
-
-<h2>Contributed Code</h2>
-
-<p>
-In order to keep SQLite completely free and unencumbered by copyright,
-all new contributors to the SQLite code base are asked to dedicate
-their contributions to the public domain.
-If you want to send a patch or enhancement for possible inclusion in the
-SQLite source tree, please accompany the patch with the following statement:
-</p>
-
-<blockquote><i>
-The author or authors of this code dedicate any and all copyright interest
-in this code to the public domain. We make this dedication for the benefit
-of the public at large and to the detriment of our heirs and successors.
-We intend this dedication to be an overt act of relinquishment in
-perpetuity of all present and future rights to this code under copyright law.
-</i></blockquote>
-
-<p>
-We are not able to accept patches or changes to
-SQLite that are not accompanied by a statement such as the above.
-In addition, if you make
-changes or enhancements as an employee, then a simple statement such as the
-above is insufficient. You must also send by surface mail a copyright release
-signed by a company officer.
-A signed original of the copyright release should be mailed to:</p>
-
-<blockquote>
-Hwaci<br>
-6200 Maple Cove Lane<br>
-Charlotte, NC 28269<br>
-USA
-</blockquote>
-
-<p>
-A template copyright release is available
-in <a href="copyright-release.pdf">PDF</a> or
-<a href="copyright-release.html">HTML</a>.
-You can use this release to make future changes.
-</p>
-}
-footer $rcsid
+++ /dev/null
-set rcsid {$Id: datatype3.tcl,v 1.17 2007/06/20 16:13:23 drh Exp $}
-source common.tcl
-header {Datatypes In SQLite Version 3}
-puts {
-<h2>Datatypes In SQLite Version 3</h2>
-
-<h3>1. Storage Classes</h3>
-
-<P>Version 2 of SQLite stores all column values as ASCII text.
-Version 3 enhances this by providing the ability to store integer and
-real numbers in a more compact format and the capability to store
-BLOB data.</P>
-
-<P>Each value stored in an SQLite database (or manipulated by the
-database engine) has one of the following storage classes:</P>
-<UL>
- <LI><P><B>NULL</B>. The value is a NULL value.</P>
- <LI><P><B>INTEGER</B>. The value is a signed integer, stored in 1,
- 2, 3, 4, 6, or 8 bytes depending on the magnitude of the value.</P>
- <LI><P><B>REAL</B>. The value is a floating point value, stored as
- an 8-byte IEEE floating point number.</P>
- <LI><P><B>TEXT</B>. The value is a text string, stored using the
- database encoding (UTF-8, UTF-16BE or UTF-16-LE).</P>
- <LI><P><B>BLOB</B>. The value is a blob of data, stored exactly as
- it was input.</P>
-</UL>
-
-<P>As in SQLite version 2, any column in a version 3 database except an INTEGER
-PRIMARY KEY may be used to store any type of value. The exception to
-this rule is described below under 'Strict Affinity Mode'.</P>
-
-<P>All values supplied to SQLite, whether as literals embedded in SQL
-statements or values bound to pre-compiled SQL statements
-are assigned a storage class before the SQL statement is executed.
-Under circumstances described below, the
-database engine may convert values between numeric storage classes
-(INTEGER and REAL) and TEXT during query execution.
-</P>
-
-<P>Storage classes are initially assigned as follows:</P>
-<UL>
- <LI><P>Values specified as literals as part of SQL statements are
- assigned storage class TEXT if they are enclosed by single or double
- quotes, INTEGER if the literal is specified as an unquoted number
- with no decimal point or exponent, REAL if the literal is an
- unquoted number with a decimal point or exponent and NULL if the
- value is a NULL. Literals with storage class BLOB are specified
- using the X'ABCD' notation.</P>
- <LI><P>Values supplied using the sqlite3_bind_* APIs are assigned
- the storage class that most closely matches the native type bound
- (i.e. sqlite3_bind_blob() binds a value with storage class BLOB).</P>
-</UL>
-<P>The storage class of a value that is the result of an SQL scalar
-operator depends on the outermost operator of the expression.
-User-defined functions may return values with any storage class. It
-is not generally possible to determine the storage class of the
-result of an expression at compile time.</P>
-
-<a name="affinity">
-<h3>2. Column Affinity</h3>
-
-<p>
-In SQLite version 3, the type of a value is associated with the value
-itself, not with the column or variable in which the value is stored.
-(This is sometimes called
-<a href="http://www.cliki.net/manifest%20type%20system">
-manifest typing</a>.)
-All other SQL databases engines that we are aware of use the more
-restrictive system of static typing where the type is associated with
-the container, not the value.
-</p>
-
-<p>
-In order to maximize compatibility between SQLite and other database
-engines, SQLite support the concept of "type affinity" on columns.
-The type affinity of a column is the recommended type for data stored
-in that column. The key here is that the type is recommended, not
-required. Any column can still store any type of data, in theory.
-It is just that some columns, given the choice, will prefer to use
-one storage class over another. The preferred storage class for
-a column is called its "affinity".
-</p>
-
-<P>Each column in an SQLite 3 database is assigned one of the
-following type affinities:</P>
-<UL>
- <LI>TEXT</LI>
- <LI>NUMERIC</LI>
- <LI>INTEGER</LI>
- <LI>REAL</li>
- <LI>NONE</LI>
-</UL>
-
-<P>A column with TEXT affinity stores all data using storage classes
-NULL, TEXT or BLOB. If numerical data is inserted into a column with
-TEXT affinity it is converted to text form before being stored.</P>
-
-<P>A column with NUMERIC affinity may contain values using all five
-storage classes. When text data is inserted into a NUMERIC column, an
-attempt is made to convert it to an integer or real number before it
-is stored. If the conversion is successful, then the value is stored
-using the INTEGER or REAL storage class. If the conversion cannot be
-performed the value is stored using the TEXT storage class. No
-attempt is made to convert NULL or blob values.</P>
-
-<P>A column that uses INTEGER affinity behaves in the same way as a
-column with NUMERIC affinity, except that if a real value with no
-floating point component (or text value that converts to such) is
-inserted it is converted to an integer and stored using the INTEGER
-storage class.</P>
-
-<P>A column with REAL affinity behaves like a column with NUMERIC
-affinity except that it forces integer values into floating point
-representation. (As an optimization, integer values are stored on
-disk as integers in order to take up less space and are only converted
-to floating point as the value is read out of the table.)</P>
-
-<P>A column with affinity NONE does not prefer one storage class over
-another. It makes no attempt to coerce data before
-it is inserted.</P>
-
-<h4>2.1 Determination Of Column Affinity</h4>
-
-<P>The type affinity of a column is determined by the declared type
-of the column, according to the following rules:</P>
-<OL>
- <LI><P>If the datatype contains the string "INT" then it
- is assigned INTEGER affinity.</P>
-
- <LI><P>If the datatype of the column contains any of the strings
- "CHAR", "CLOB", or "TEXT" then that
- column has TEXT affinity. Notice that the type VARCHAR contains the
- string "CHAR" and is thus assigned TEXT affinity.</P>
-
- <LI><P>If the datatype for a column
- contains the string "BLOB" or if
- no datatype is specified then the column has affinity NONE.</P>
-
- <LI><P>If the datatype for a column
- contains any of the strings "REAL", "FLOA",
- or "DOUB" then the column has REAL affinity</P>
-
- <LI><P>Otherwise, the affinity is NUMERIC.</P>
-</OL>
-
-<P>If a table is created using a "CREATE TABLE <table> AS
-SELECT..." statement, then all columns have no datatype specified
-and they are given no affinity.</P>
-
-<h4>2.2 Column Affinity Example</h4>
-
-<blockquote>
-<PRE>CREATE TABLE t1(
- t TEXT,
- nu NUMERIC,
- i INTEGER,
- no BLOB
-);
-
--- Storage classes for the following row:
--- TEXT, REAL, INTEGER, TEXT
-INSERT INTO t1 VALUES('500.0', '500.0', '500.0', '500.0');
-
--- Storage classes for the following row:
--- TEXT, REAL, INTEGER, REAL
-INSERT INTO t1 VALUES(500.0, 500.0, 500.0, 500.0);
-</PRE>
-</blockquote>
-
-<a name="comparisons">
-<h3>3. Comparison Expressions</h3>
-
-<P>Like SQLite version 2, version 3
-features the binary comparison operators '=',
-'<', '<=', '>=' and '!=', an operation to test for set
-membership, 'IN', and the ternary comparison operator 'BETWEEN'.</P>
-<P>The results of a comparison depend on the storage classes of the
-two values being compared, according to the following rules:</P>
-<UL>
- <LI><P>A value with storage class NULL is considered less than any
- other value (including another value with storage class NULL).</P>
-
- <LI><P>An INTEGER or REAL value is less than any TEXT or BLOB value.
- When an INTEGER or REAL is compared to another INTEGER or REAL, a
- numerical comparison is performed.</P>
-
- <LI><P>A TEXT value is less than a BLOB value. When two TEXT values
- are compared, the C library function memcmp() is usually used to
- determine the result. However this can be overridden, as described
- under 'User-defined collation Sequences' below.</P>
-
- <LI><P>When two BLOB values are compared, the result is always
- determined using memcmp().</P>
-</UL>
-
-<P>SQLite may attempt to convert values between the numeric storage
-classes (INTEGER and REAL) and TEXT before performing a comparison.
-For binary comparisons, this is done in the cases enumerated below.
-The term "expression" used in the bullet points below means any
-SQL scalar expression or literal other than a column value. Note that
-if X and Y.Z are a column names, then +X and +Y.Z are considered
-expressions.</P>
-<UL>
- <LI><P>When a column value is compared to the result of an
- expression, the affinity of the column is applied to the result of
- the expression before the comparison takes place.</P>
-
- <LI><P>When two column values are compared, if one column has
- INTEGER or REAL or NUMERIC affinity and the other does not,
- then NUMERIC affinity is applied to any values with storage
- class TEXT extracted from the non-NUMERIC column.</P>
-
- <LI><P>When the results of two expressions are compared, no
- conversions occur. The results are compared as is. If a string
- is compared to a number, the number will always be less than the
- string.</P>
-</UL>
-
-<P>
-In SQLite, the expression "a BETWEEN b AND c" is equivalent to "a >= b
-AND a <= c", even if this means that different affinities are applied to
-'a' in each of the comparisons required to evaluate the expression.
-</P>
-
-<P>Expressions of the type "a IN (SELECT b ....)" are handled by the three
-rules enumerated above for binary comparisons (e.g. in a
-similar manner to "a = b"). For example if 'b' is a column value
-and 'a' is an expression, then the affinity of 'b' is applied to 'a'
-before any comparisons take place.</P>
-
-<P>SQLite treats the expression "a IN (x, y, z)" as equivalent to "a = +x OR
-a = +y OR a = +z". The values to the right of the IN operator (the "x", "y",
-and "z" values in this example) are considered to be expressions, even if they
-happen to be column values. If the value of the left of the IN operator is
-a column, then the affinity of that column is used. If the value is an
-expression then no conversions occur.
-</P>
-
-<h4>3.1 Comparison Example</h4>
-
-<blockquote>
-<PRE>
-CREATE TABLE t1(
- a TEXT,
- b NUMERIC,
- c BLOB
-);
-
--- Storage classes for the following row:
--- TEXT, REAL, TEXT
-INSERT INTO t1 VALUES('500', '500', '500');
-
--- 60 and 40 are converted to '60' and '40' and values are compared as TEXT.
-SELECT a < 60, a < 40 FROM t1;
-1|0
-
--- Comparisons are numeric. No conversions are required.
-SELECT b < 60, b < 600 FROM t1;
-0|1
-
--- Both 60 and 600 (storage class NUMERIC) are less than '500'
--- (storage class TEXT).
-SELECT c < 60, c < 600 FROM t1;
-0|0
-</PRE>
-</blockquote>
-<h3>4. Operators</h3>
-
-<P>All mathematical operators (which is to say, all operators other
-than the concatenation operator "||") apply NUMERIC
-affinity to all operands prior to being carried out. If one or both
-operands cannot be converted to NUMERIC then the result of the
-operation is NULL.</P>
-
-<P>For the concatenation operator, TEXT affinity is applied to both
-operands. If either operand cannot be converted to TEXT (because it
-is NULL or a BLOB) then the result of the concatenation is NULL.</P>
-
-<h3>5. Sorting, Grouping and Compound SELECTs</h3>
-
-<P>When values are sorted by an ORDER by clause, values with storage
-class NULL come first, followed by INTEGER and REAL values
-interspersed in numeric order, followed by TEXT values usually in
-memcmp() order, and finally BLOB values in memcmp() order. No storage
-class conversions occur before the sort.</P>
-
-<P>When grouping values with the GROUP BY clause values with
-different storage classes are considered distinct, except for INTEGER
-and REAL values which are considered equal if they are numerically
-equal. No affinities are applied to any values as the result of a
-GROUP by clause.</P>
-
-<P>The compound SELECT operators UNION,
-INTERSECT and EXCEPT perform implicit comparisons between values.
-Before these comparisons are performed an affinity may be applied to
-each value. The same affinity, if any, is applied to all values that
-may be returned in a single column of the compound SELECT result set.
-The affinity applied is the affinity of the column returned by the
-left most component SELECTs that has a column value (and not some
-other kind of expression) in that position. If for a given compound
-SELECT column none of the component SELECTs return a column value, no
-affinity is applied to the values from that column before they are
-compared.</P>
-
-<h3>6. Other Affinity Modes</h3>
-
-<P>The above sections describe the operation of the database engine
-in 'normal' affinity mode. SQLite version 3 will feature two other affinity
-modes, as follows:</P>
-<UL>
- <LI><P><B>Strict affinity</B> mode. In this mode if a conversion
- between storage classes is ever required, the database engine
- returns an error and the current statement is rolled back.</P>
-
- <LI><P><B>No affinity</B> mode. In this mode no conversions between
- storage classes are ever performed. Comparisons between values of
- different storage classes (except for INTEGER and REAL) are always
- false.</P>
-</UL>
-
-<a name="collation"></a>
-<h3>7. User-defined Collation Sequences</h3>
-
-<p>
-By default, when SQLite compares two text values, the result of the
-comparison is determined using memcmp(), regardless of the encoding of the
-string. SQLite v3 provides the ability for users to supply arbitrary
-comparison functions, known as user-defined collation sequences, to be used
-instead of memcmp().
-</p>
-<p>
-Aside from the default collation sequence BINARY, implemented using
-memcmp(), SQLite features one extra built-in collation sequences
-intended for testing purposes, the NOCASE collation:
-</p>
-<UL>
- <LI><b>BINARY</b> - Compares string data using memcmp(), regardless
- of text encoding.</LI>
- <LI><b>NOCASE</b> - The same as binary, except the 26 upper case
- characters used by the English language are
- folded to their lower case equivalents before
- the comparison is performed. </UL>
-
-
-<h4>7.1 Assigning Collation Sequences from SQL</h4>
-
-<p>
-Each column of each table has a default collation type. If a collation type
-other than BINARY is required, a COLLATE clause is specified as part of the
-<a href="lang_createtable.html">column definition</a> to define it.
-</p>
-
-<p>
-Whenever two text values are compared by SQLite, a collation sequence is
-used to determine the results of the comparison according to the following
-rules. Sections 3 and 5 of this document describe the circumstances under
-which such a comparison takes place.
-</p>
-
-<p>
-For binary comparison operators (=, <, >, <= and >=) if either operand is a
-column, then the default collation type of the column determines the
-collation sequence to use for the comparison. If both operands are columns,
-then the collation type for the left operand determines the collation
-sequence used. If neither operand is a column, then the BINARY collation
-sequence is used. For the purposes of this paragraph, a column name
-preceded by one or more unary "+" operators is considered a column name.
-</p>
-
-<p>
-The expression "x BETWEEN y and z" is equivalent to "x >= y AND x <=
-z". The expression "x IN (SELECT y ...)" is handled in the same way as the
-expression "x = y" for the purposes of determining the collation sequence
-to use. The collation sequence used for expressions of the form "x IN (y, z
-...)" is the default collation type of x if x is a column, or BINARY
-otherwise.
-</p>
-
-<p>
-An <a href="lang_select.html">ORDER BY</a> clause that is part of a SELECT
-statement may be assigned a collation sequence to be used for the sort
-operation explicitly. In this case the explicit collation sequence is
-always used. Otherwise, if the expression sorted by an ORDER BY clause is
-a column, then the default collation type of the column is used to
-determine sort order. If the expression is not a column, then the BINARY
-collation sequence is used.
-</p>
-
-<h4>7.2 Collation Sequences Example</h4>
-<p>
-The examples below identify the collation sequences that would be used to
-determine the results of text comparisons that may be performed by various
-SQL statements. Note that a text comparison may not be required, and no
-collation sequence used, in the case of numeric, blob or NULL values.
-</p>
-<blockquote>
-<PRE>
-CREATE TABLE t1(
- a, -- default collation type BINARY
- b COLLATE BINARY, -- default collation type BINARY
- c COLLATE REVERSE, -- default collation type REVERSE
- d COLLATE NOCASE -- default collation type NOCASE
-);
-
--- Text comparison is performed using the BINARY collation sequence.
-SELECT (a = b) FROM t1;
-
--- Text comparison is performed using the NOCASE collation sequence.
-SELECT (d = a) FROM t1;
-
--- Text comparison is performed using the BINARY collation sequence.
-SELECT (a = d) FROM t1;
-
--- Text comparison is performed using the REVERSE collation sequence.
-SELECT ('abc' = c) FROM t1;
-
--- Text comparison is performed using the REVERSE collation sequence.
-SELECT (c = 'abc') FROM t1;
-
--- Grouping is performed using the NOCASE collation sequence (i.e. values
--- 'abc' and 'ABC' are placed in the same group).
-SELECT count(*) GROUP BY d FROM t1;
-
--- Grouping is performed using the BINARY collation sequence.
-SELECT count(*) GROUP BY (d || '') FROM t1;
-
--- Sorting is performed using the REVERSE collation sequence.
-SELECT * FROM t1 ORDER BY c;
-
--- Sorting is performed using the BINARY collation sequence.
-SELECT * FROM t1 ORDER BY (c || '');
-
--- Sorting is performed using the NOCASE collation sequence.
-SELECT * FROM t1 ORDER BY c COLLATE NOCASE;
-
-</PRE>
-</blockquote>
-
-}
-footer $rcsid
+++ /dev/null
-#
-# Run this script to generated a datatypes.html output file
-#
-set rcsid {$Id: datatypes.tcl,v 1.8 2004/10/10 17:24:55 drh Exp $}
-source common.tcl
-header {Datatypes In SQLite version 2}
-puts {
-<h2>Datatypes In SQLite Version 2</h2>
-
-<h3>1.0 Typelessness</h3>
-<p>
-SQLite is "typeless". This means that you can store any
-kind of data you want in any column of any table, regardless of the
-declared datatype of that column.
-(See the one exception to this rule in section 2.0 below.)
-This behavior is a feature, not
-a bug. A database is suppose to store and retrieve data and it
-should not matter to the database what format that data is in.
-The strong typing system found in most other SQL engines and
-codified in the SQL language spec is a misfeature -
-it is an example of the implementation showing through into the
-interface. SQLite seeks to overcome this misfeature by allowing
-you to store any kind of data into any kind of column and by
-allowing flexibility in the specification of datatypes.
-</p>
-
-<p>
-A datatype to SQLite is any sequence of zero or more names
-optionally followed by a parenthesized lists of one or two
-signed integers. Notice in particular that a datatype may
-be <em>zero</em> or more names. That means that an empty
-string is a valid datatype as far as SQLite is concerned.
-So you can declare tables where the datatype of each column
-is left unspecified, like this:
-</p>
-
-<blockquote><pre>
-CREATE TABLE ex1(a,b,c);
-</pre></blockquote>
-
-<p>
-Even though SQLite allows the datatype to be omitted, it is
-still a good idea to include it in your CREATE TABLE statements,
-since the data type often serves as a good hint to other
-programmers about what you intend to put in the column. And
-if you ever port your code to another database engine, that
-other engine will probably require a datatype of some kind.
-SQLite accepts all the usual datatypes. For example:
-</p>
-
-<blockquote><pre>
-CREATE TABLE ex2(
- a VARCHAR(10),
- b NVARCHAR(15),
- c TEXT,
- d INTEGER,
- e FLOAT,
- f BOOLEAN,
- g CLOB,
- h BLOB,
- i TIMESTAMP,
- j NUMERIC(10,5)
- k VARYING CHARACTER (24),
- l NATIONAL VARYING CHARACTER(16)
-);
-</pre></blockquote>
-
-<p>
-And so forth. Basically any sequence of names optionally followed by
-one or two signed integers in parentheses will do.
-</p>
-
-<h3>2.0 The INTEGER PRIMARY KEY</h3>
-
-<p>
-One exception to the typelessness of SQLite is a column whose type
-is INTEGER PRIMARY KEY. (And you must use "INTEGER" not "INT".
-A column of type INT PRIMARY KEY is typeless just like any other.)
-INTEGER PRIMARY KEY columns must contain a 32-bit signed integer. Any
-attempt to insert non-integer data will result in an error.
-</p>
-
-<p>
-INTEGER PRIMARY KEY columns can be used to implement the equivalent
-of AUTOINCREMENT. If you try to insert a NULL into an INTEGER PRIMARY
-KEY column, the column will actually be filled with a integer that is
-one greater than the largest key already in the table. Or if the
-largest key is 2147483647, then the column will be filled with a
-random integer. Either way, the INTEGER PRIMARY KEY column will be
-assigned a unique integer. You can retrieve this integer using
-the <b>sqlite_last_insert_rowid()</b> API function or using the
-<b>last_insert_rowid()</b> SQL function in a subsequent SELECT statement.
-</p>
-
-<h3>3.0 Comparison and Sort Order</h3>
-
-<p>
-SQLite is typeless for the purpose of deciding what data is allowed
-to be stored in a column. But some notion of type comes into play
-when sorting and comparing data. For these purposes, a column or
-an expression can be one of two types: <b>numeric</b> and <b>text</b>.
-The sort or comparison may give different results depending on which
-type of data is being sorted or compared.
-</p>
-
-<p>
-If data is of type <b>text</b> then the comparison is determined by
-the standard C data comparison functions <b>memcmp()</b> or
-<b>strcmp()</b>. The comparison looks at bytes from two inputs one
-by one and returns the first non-zero difference.
-Strings are '\000' terminated so shorter
-strings sort before longer strings, as you would expect.
-</p>
-
-<p>
-For numeric data, this situation is more complex. If both inputs
-look like well-formed numbers, then they are converted
-into floating point values using <b>atof()</b> and compared numerically.
-If one input is not a well-formed number but the other is, then the
-number is considered to be less than the non-number. If neither inputs
-is a well-formed number, then <b>strcmp()</b> is used to do the
-comparison.
-</p>
-
-<p>
-Do not be confused by the fact that a column might have a "numeric"
-datatype. This does not mean that the column can contain only numbers.
-It merely means that if the column does contain a number, that number
-will sort in numerical order.
-</p>
-
-<p>
-For both text and numeric values, NULL sorts before any other value.
-A comparison of any value against NULL using operators like "<" or
-">=" is always false.
-</p>
-
-<h3>4.0 How SQLite Determines Datatypes</h3>
-
-<p>
-For SQLite version 2.6.3 and earlier, all values used the numeric datatype.
-The text datatype appears in version 2.7.0 and later. In the sequel it
-is assumed that you are using version 2.7.0 or later of SQLite.
-</p>
-
-<p>
-For an expression, the datatype of the result is often determined by
-the outermost operator. For example, arithmetic operators ("+", "*", "%")
-always return a numeric results. The string concatenation operator
-("||") returns a text result. And so forth. If you are ever in doubt
-about the datatype of an expression you can use the special <b>typeof()</b>
-SQL function to determine what the datatype is. For example:
-</p>
-
-<blockquote><pre>
-sqlite> SELECT typeof('abc'+123);
-numeric
-sqlite> SELECT typeof('abc'||123);
-text
-</pre></blockquote>
-
-<p>
-For table columns, the datatype is determined by the type declaration
-of the CREATE TABLE statement. The datatype is text if and only if
-the type declaration contains one or more of the following strings:
-</p>
-
-<blockquote>
-BLOB<br>
-CHAR<br>
-CLOB</br>
-TEXT
-</blockquote>
-
-<p>
-The search for these strings in the type declaration is case insensitive,
-of course. If any of the above strings occur anywhere in the type
-declaration, then the datatype of the column is text. Notice that
-the type "VARCHAR" contains "CHAR" as a substring so it is considered
-text.</p>
-
-<p>If none of the strings above occur anywhere in the type declaration,
-then the datatype is numeric. Note in particular that the datatype for columns
-with an empty type declaration is numeric.
-</p>
-
-<h3>5.0 Examples</h3>
-
-<p>
-Consider the following two command sequences:
-</p>
-
-<blockquote><pre>
-CREATE TABLE t1(a INTEGER UNIQUE); CREATE TABLE t2(b TEXT UNIQUE);
-INSERT INTO t1 VALUES('0'); INSERT INTO t2 VALUES(0);
-INSERT INTO t1 VALUES('0.0'); INSERT INTO t2 VALUES(0.0);
-</pre></blockquote>
-
-<p>In the sequence on the left, the second insert will fail. In this case,
-the strings '0' and '0.0' are treated as numbers since they are being
-inserted into a numeric column but 0==0.0 which violates the uniqueness
-constraint. However, the second insert in the right-hand sequence works. In
-this case, the constants 0 and 0.0 are treated a strings which means that
-they are distinct.</p>
-
-<p>SQLite always converts numbers into double-precision (64-bit) floats
-for comparison purposes. This means that a long sequence of digits that
-differ only in insignificant digits will compare equal if they
-are in a numeric column but will compare unequal if they are in a text
-column. We have:</p>
-
-<blockquote><pre>
-INSERT INTO t1 INSERT INTO t2
- VALUES('12345678901234567890'); VALUES(12345678901234567890);
-INSERT INTO t1 INSERT INTO t2
- VALUES('12345678901234567891'); VALUES(12345678901234567891);
-</pre></blockquote>
-
-<p>As before, the second insert on the left will fail because the comparison
-will convert both strings into floating-point number first and the only
-difference in the strings is in the 20-th digit which exceeds the resolution
-of a 64-bit float. In contrast, the second insert on the right will work
-because in that case, the numbers being inserted are strings and are
-compared using memcmp().</p>
-
-<p>
-Numeric and text types make a difference for the DISTINCT keyword too:
-</p>
-
-<blockquote><pre>
-CREATE TABLE t3(a INTEGER); CREATE TABLE t4(b TEXT);
-INSERT INTO t3 VALUES('0'); INSERT INTO t4 VALUES(0);
-INSERT INTO t3 VALUES('0.0'); INSERT INTO t4 VALUES(0.0);
-SELECT DISTINCT * FROM t3; SELECT DISTINCT * FROM t4;
-</pre></blockquote>
-
-<p>
-The SELECT statement on the left returns a single row since '0' and '0.0'
-are treated as numbers and are therefore indistinct. But the SELECT
-statement on the right returns two rows since 0 and 0.0 are treated
-a strings which are different.</p>
-}
-footer $rcsid
+++ /dev/null
-set rcsid {$Id: different.tcl,v 1.8 2006/12/18 14:12:21 drh Exp $}
-source common.tcl
-header {Distinctive Features Of SQLite}
-puts {
-<p>
-This page highlights some of the characteristics of SQLite that are
-unusual and which make SQLite different from many other SQL
-database engines.
-</p>
-}
-proc feature {tag name text} {
- puts "<a name=\"$tag\" />"
- puts "<p><b>$name</b></p>\n"
- puts "<blockquote>$text</blockquote>\n"
-}
-
-feature zeroconfig {Zero-Configuration} {
- SQLite does not need to be "installed" before it is used.
- There is no "setup" procedure. There is no
- server process that needs to be started, stopped, or configured.
- There is
- no need for an administrator to create a new database instance or assign
- access permissions to users.
- SQLite uses no configuration files.
- Nothing needs to be done to tell the system that SQLite is running.
- No actions are required to recover after a system crash or power failure.
- There is nothing to troubleshoot.
- <p>
- SQLite just works.
- <p>
- Other more familiar database engines run great once you get them going.
- But doing the initial installation and configuration can be
- intimidatingly complex.
-}
-
-feature serverless {Serverless} {
- Most SQL database engines are implemented as a separate server
- process. Programs that want to access the database communicate
- with the server using some kind of interprocess communcation
- (typically TCP/IP) to send requests to the server and to receive
- back results. SQLite does not work this way. With SQLite, the
- process that wants to access the database reads and writes
- directly from the database files on disk. There is no intermediary
- server process.
- <p>
- There are advantages and disadvantages to being serverless. The
- main advantage is that there is no separate server process
- to install, setup, configure, initialize, manage, and troubleshoot.
- This is one reason why SQLite is a "zero-configuration" database
- engine. Programs that use SQLite require no administrative support
- for setting up the database engine before they are run. Any program
- that is able to access the disk is able to use an SQLite database.
- <p>
- On the other hand, a database engine that uses a server can provide
- better protection from bugs in the client application - stray pointers
- in a client cannot corrupt memory on the server. And because a server
- is a single persistent process, it is able control database access with
- more precision, allowing for finer grain locking and better concurrancy.
- <p>
- Most SQL database engines are client/server based. Of those that are
- serverless, SQLite is the only one that this author knows of that
- allows multiple applications to access the same database at the same time.
-}
-
-feature onefile {Single Database File} {
- An SQLite database is a single ordinary disk file that can be located
- anywhere in the directory hierarchy. If SQLite can read
- the disk file then it can read anything in the database. If the disk
- file and its directory are writable, then SQLite can change anything
- in the database. Database files can easily be copied onto a USB
- memory stick or emailed for sharing.
- <p>
- Other SQL database engines tend to store data as a large collection of
- files. Often these files are in a standard location that only the
- database engine itself can access. This makes the data more secure,
- but also makes it harder to access. Some SQL database engines provide
- the option of writing directly to disk and bypassing the filesystem
- all together. This provides added performance, but at the cost of
- considerable setup and maintenance complexity.
-}
-
-feature small {Compact} {
- When optimized for size, the whole SQLite library with everything enabled
- is less than 225KiB in size (as measured on an ix86 using the "size"
- utility from the GNU compiler suite.) Unneeded features can be disabled
- at compile-time to further reduce the size of the library to under
- 170KiB if desired.
- <p>
- Most other SQL database engines are much larger than this. IBM boasts
- that it's recently released CloudScape database engine is "only" a 2MiB
- jar file - 10 times larger than SQLite even after it is compressed!
- Firebird boasts that it's client-side library is only 350KiB. That's
- 50% larger than SQLite and does not even contain the database engine.
- The Berkeley DB library from Sleepycat is 450KiB and it omits SQL
- support, providing the programmer with only simple key/value pairs.
-}
-
-feature typing {Manifest typing} {
- Most SQL database engines use static typing. A datatype is associated
- with each column in a table and only values of that particular datatype
- are allowed to be stored in that column. SQLite relaxes this restriction
- by using manifest typing.
- In manifest typing, the datatype is a property of the value itself, not
- of the column in which the value is stored.
- SQLite thus allows the user to store
- any value of any datatype into any column regardless of the declared type
- of that column. (There are some exceptions to this rule: An INTEGER
- PRIMARY KEY column may only store integers. And SQLite attempts to coerce
- values into the declared datatype of the column when it can.)
- <p>
- As far as we can tell, the SQL language specification allows the use
- of manifest typing. Nevertheless, most other SQL database engines are
- statically typed and so some people
- feel that the use of manifest typing is a bug in SQLite. But the authors
- of SQLite feel very strongly that this is a feature. The use of manifest
- typing in SQLite is a deliberate design decision which has proven in practice
- to make SQLite more reliable and easier to use, especially when used in
- combination with dynamically typed programming languages such as Tcl and
- Python.
-}
-
-feature flex {Variable-length records} {
- Most other SQL database engines allocated a fixed amount of disk space
- for each row in most tables. They play special tricks for handling
- BLOBs and CLOBs which can be of wildly varying length. But for most
- tables, if you declare a column to be a VARCHAR(100) then the database
- engine will allocate
- 100 bytes of disk space regardless of how much information you actually
- store in that column.
- <p>
- SQLite, in contrast, use only the amount of disk space actually
- needed to store the information in a row. If you store a single
- character in a VARCHAR(100) column, then only a single byte of disk
- space is consumed. (Actually two bytes - there is some overhead at
- the beginning of each column to record its datatype and length.)
- <p>
- The use of variable-length records by SQLite has a number of advantages.
- It results in smaller database files, obviously. It also makes the
- database run faster, since there is less information to move to and from
- disk. And, the use of variable-length records makes it possible for
- SQLite to employ manifest typing instead of static typing.
-}
-
-feature readable {Readable source code} {
- The source code to SQLite is designed to be readable and accessible to
- the average programmer. All procedures and data structures and many
- automatic variables are carefully commented with useful information about
- what they do. Boilerplate commenting is omitted.
-}
-
-feature vdbe {SQL statements compile into virtual machine code} {
- Every SQL database engine compiles each SQL statement into some kind of
- internal data structure which is then used to carry out the work of the
- statement. But in most SQL engines that internal data structure is a
- complex web of interlinked structures and objects. In SQLite, the compiled
- form of statements is a short program in a machine-language like
- representation. Users of the database can view this
- <a href="opcode.html">virtual machine language</a>
- by prepending the <a href="lang_explain.html">EXPLAIN</a> keyword
- to a query.
- <p>
- The use of a virtual machine in SQLite has been a great benefit to
- library's development. The virtual machine provides a crisp, well-defined
- junction between the front-end of SQLite (the part that parses SQL
- statements and generates virtual machine code) and the back-end (the
- part that executes the virtual machine code and computes a result.)
- The virtual machine allows the developers to see clearly and in an
- easily readable form what SQLite is trying to do with each statement
- it compiles, which is a tremendous help in debugging.
- Depending on how it is compiled, SQLite also has the capability of
- tracing the execution of the virtual machine - printing each
- virtual machine instruction and its result as it executes.
-}
-
-#feature binding {Tight bindings to dynamic languages} {
-# Because it is embedded, SQLite can have a much tighter and more natural
-# binding to high-level dynamic languages such as Tcl, Perl, Python,
-# PHP, and Ruby.
-# For example,
-#}
-
-feature license {Public domain} {
- The source code for SQLite is in the public domain. No claim of copyright
- is made on any part of the core source code. (The documentation and test
- code is a different matter - some sections of documentation and test logic
- are governed by open-sources licenses.) All contributors to the
- SQLite core software have signed affidavits specifically disavowing any
- copyright interest in the code. This means that anybody is able to legally
- do anything they want with the SQLite source code.
- <p>
- There are other SQL database engines with liberal licenses that allow
- the code to be broadly and freely used. But those other engines are
- still governed by copyright law. SQLite is different in that copyright
- law simply does not apply.
- <p>
- The source code files for other SQL database engines typically begin
- with a comment describing your license rights to view and copy that file.
- The SQLite source code contains no license since it is not governed by
- copyright. Instead of a license, the SQLite source code offers a blessing:
- <blockquote>
- <i>May you do good and not evil<br>
- May you find forgiveness for yourself and forgive others<br>
- May you share freely, never taking more than you give.</i>
- </blockquote>
-}
-
-feature extensions {SQL language extensions} {
- SQLite provides a number of enhancements to the SQL language
- not normally found in other database engines.
- The EXPLAIN keyword and manifest typing have already been mentioned
- above. SQLite also provides statements such as
- <a href="lang_replace.html">REPLACE</a> and the
- <a href="lang_conflict.html">ON CONFLICT</a> clause that allow for
- added control over the resolution of constraint conflicts.
- SQLite supports <a href="lang_attach.html">ATTACH</a> and
- <a href="lang_detach.html">DETACH</a> commands that allow multiple
- independent databases to be used together in the same query.
- And SQLite defines APIs that allows the user to add new
- <a href="capi3ref.html#sqlite3_create_function">SQL functions</a>
- and <a href="capi3ref.html#sqlite3_create_collation">collating sequences</a>.
-}
-
-
-footer $rcsid
+++ /dev/null
-# This script generates the "docs.html" page that describes various
-# sources of documentation available for SQLite.
-#
-set rcsid {$Id: docs.tcl,v 1.15 2007/10/04 00:29:29 drh Exp $}
-source common.tcl
-header {SQLite Documentation}
-puts {
-<h2>Available Documentation</h2>
-<table width="100%" cellpadding="5">
-}
-
-proc doc {name url desc} {
- puts {<tr><td valign="top" align="right">}
- regsub -all { +} $name {\ } name
- puts "<a href=\"$url\">$name</a></td>"
- puts {<td width="10"></td>}
- puts {<td valign="top" align="left">}
- puts $desc
- puts {</td></tr>}
-}
-
-doc {Appropriate Uses For SQLite} {whentouse.html} {
- This document describes situations where SQLite is an approriate
- database engine to use versus situations where a client/server
- database engine might be a better choice.
-}
-
-doc {Distinctive Features} {different.html} {
- This document enumerates and describes some of the features of
- SQLite that make it different from other SQL database engines.
-}
-
-doc {SQLite In 5 Minutes Or Less} {quickstart.html} {
- A very quick introduction to programming with SQLite.
-}
-
-doc {SQL Syntax} {lang.html} {
- This document describes the SQL language that is understood by
- SQLite.
-}
-doc {Version 3 C/C++ API<br>Reference} {capi3ref.html} {
- This document describes each API function separately.
-}
-doc {Sharing Cache Mode} {sharedcache.html} {
- Version 3.3.0 and later supports the ability for two or more
- database connections to share the same page and schema cache.
- This feature is useful for certain specialized applications.
-}
-doc {Tcl API} {tclsqlite.html} {
- A description of the TCL interface bindings for SQLite.
-}
-
-doc {How SQLite Implements Atomic Commit} {ac/atomiccommit.html} {
- A description of the logic within SQLite that implements
- transactions with atomic commit, even in the face of power
- failures.
-}
-doc {Moving From SQLite 3.4 to 3.5} {34to35.html} {
- A document describing the differences between SQLite version 3.4.2
- and 3.5.0.
-}
-
-doc {Pragma commands} {pragma.html} {
- This document describes SQLite performance tuning options and other
- special purpose database commands.
-}
-doc {SQLite Version 3} {version3.html} {
- A summary of of the changes between SQLite version 2.8 and SQLite version 3.0.
-}
-doc {Version 3 C/C++ API} {capi3.html} {
- A description of the C/C++ interface bindings for SQLite version 3.0.0
- and following.
-}
-doc {Version 3 DataTypes } {datatype3.html} {
- SQLite version 3 introduces the concept of manifest typing, where the
- type of a value is associated with the value itself, not the column that
- it is stored in.
- This page describes data typing for SQLite version 3 in further detail.
-}
-
-doc {Locking And Concurrency<br>In SQLite Version 3} {lockingv3.html} {
- A description of how the new locking code in version 3 increases
- concurrancy and decreases the problem of writer starvation.
-}
-
-doc {Overview Of The Optimizer} {optoverview.html} {
- A quick overview of the various query optimizations that are
- attempted by the SQLite code generator.
-}
-
-
-doc {Null Handling} {nulls.html} {
- Different SQL database engines handle NULLs in different ways. The
- SQL standards are ambiguous. This document describes how SQLite handles
- NULLs in comparison with other SQL database engines.
-}
-
-doc {Copyright} {copyright.html} {
- SQLite is in the public domain. This document describes what that means
- and the implications for contributors.
-}
-
-doc {Unsupported SQL} {omitted.html} {
- This page describes features of SQL that SQLite does not support.
-}
-
-doc {Version 2 C/C++ API} {c_interface.html} {
- A description of the C/C++ interface bindings for SQLite through version
- 2.8
-}
-
-
-doc {Version 2 DataTypes } {datatypes.html} {
- A description of how SQLite version 2 handles SQL datatypes.
- Short summary: Everything is a string.
-}
-
-doc {Release History} {changes.html} {
- A chronology of SQLite releases going back to version 1.0.0
-}
-
-
-doc {Speed Comparison} {speed.html} {
- The speed of version 2.7.6 of SQLite is compared against PostgreSQL and
- MySQL.
-}
-
-doc {Architecture} {arch.html} {
- An architectural overview of the SQLite library, useful for those who want
- to hack the code.
-}
-
-doc {VDBE Tutorial} {vdbe.html} {
- The VDBE is the subsystem within SQLite that does the actual work of
- executing SQL statements. This page describes the principles of operation
- for the VDBE in SQLite version 2.7. This is essential reading for anyone
- who want to modify the SQLite sources.
-}
-
-doc {VDBE Opcodes} {opcode.html} {
- This document is an automatically generated description of the various
- opcodes that the VDBE understands. Programmers can use this document as
- a reference to better understand the output of EXPLAIN listings from
- SQLite.
-}
-
-doc {Compilation Options} {compile.html} {
- This document describes the compile time options that may be set to
- modify the default behaviour of the library or omit optional features
- in order to reduce binary size.
-}
-
-doc {Backwards Compatibility} {formatchng.html} {
- This document details all of the incompatible changes to the SQLite
- file format that have occurred since version 1.0.0.
-}
-
-puts {</table>}
-footer $rcsid
+++ /dev/null
-#
-# Run this TCL script to generate HTML for the download.html file.
-#
-set rcsid {$Id: download.tcl,v 1.27 2007/05/08 18:30:36 drh Exp $}
-source common.tcl
-header {SQLite Download Page}
-
-puts {
-<h2>SQLite Download Page</h1>
-<table width="100%" cellpadding="5">
-}
-
-proc Product {pattern desc} {
- regsub {V[23]} $pattern {*} p3
- regsub V2 $pattern {(2[0-9a-z._]+)} pattern
- regsub V3 $pattern {(3[0-9a-z._]+)} pattern
- set p2 [string map {* .*} $pattern]
- set flist [glob -nocomplain $p3]
- foreach file [lsort -dict $flist] {
- if {![regexp ^$p2\$ $file all version]} continue
- regsub -all _ $version . version
- set size [file size $file]
- set units bytes
- if {$size>1024*1024} {
- set size [format %.2f [expr {$size/(1024.0*1024.0)}]]
- set units MiB
- } elseif {$size>1024} {
- set size [format %.2f [expr {$size/(1024.0)}]]
- set units KiB
- }
- puts "<tr><td width=\"10\"></td>"
- puts "<td valign=\"top\" align=\"right\">"
- puts "<a href=\"$file\">$file</a><br>($size $units)</td>"
- puts "<td width=\"5\"></td>"
- regsub -all VERSION $desc $version d2
- puts "<td valign=\"top\">[string trim $d2]</td></tr>"
- }
-}
-cd doc
-
-proc Heading {title} {
- puts "<tr><td colspan=4><big><b>$title</b></big></td></tr>"
-}
-
-Heading {Precompiled Binaries for Linux}
-
-Product sqlite3-V3.bin.gz {
- A command-line program for accessing and modifying
- SQLite version 3.* databases.
- See <a href="sqlite.html">the documentation</a> for additional information.
-}
-
-Product sqlite-V3.bin.gz {
- A command-line program for accessing and modifying
- SQLite databases.
- See <a href="sqlite.html">the documentation</a> for additional information.
-}
-
-Product tclsqlite-V3.so.gz {
- Bindings for <a href="http://www.tcl.tk/">Tcl/Tk</a>.
- You can import this shared library into either
- tclsh or wish to get SQLite database access from Tcl/Tk.
- See <a href="tclsqlite.html">the documentation</a> for details.
-}
-
-Product sqlite-V3.so.gz {
- A precompiled shared-library for Linux without the TCL bindings.
-}
-
-Product fts1-V3.so.gz {
- A precompiled
- <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsOne">FTS1 Module</a>
- for Linux.
-}
-
-Product fts2-V3.so.gz {
- A precompiled
- <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsTwo">FTS2 Module</a>
- for Linux.
-}
-
-Product sqlite-devel-V3.i386.rpm {
- RPM containing documentation, header files, and static library for
- SQLite version VERSION.
-}
-Product sqlite-V3-1.i386.rpm {
- RPM containing shared libraries and the <b>sqlite</b> command-line
- program for SQLite version VERSION.
-}
-
-Product sqlite*_analyzer-V3.bin.gz {
- An analysis program for database files compatible with SQLite
- version VERSION and later.
-}
-
-Heading {Precompiled Binaries For Windows}
-
-Product sqlite-V3.zip {
- A command-line program for accessing and modifing SQLite databases.
- See <a href="sqlite.html">the documentation</a> for additional information.
-}
-Product tclsqlite-V3.zip {
- Bindings for <a href="http://www.tcl.tk/">Tcl/Tk</a>.
- You can import this shared library into either
- tclsh or wish to get SQLite database access from Tcl/Tk.
- See <a href="tclsqlite.html">the documentation</a> for details.
-}
-Product sqlitedll-V3.zip {
- This is a DLL of the SQLite library without the TCL bindings.
- The only external dependency is MSVCRT.DLL.
-}
-
-Product fts1dll-V3.zip {
- A precompiled
- <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsOne">FTS1 Module</a>
- for win32.
-}
-
-Product fts2dll-V3.zip {
- A precompiled
- <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsTwo">FTS2 Module</a>
- for win32.
-}
-
-Product sqlite*_analyzer-V3.zip {
- An analysis program for database files compatible with SQLite version
- VERSION and later.
-}
-
-
-Heading {Source Code}
-
-Product {sqlite-V3.tar.gz} {
- A tarball of the complete source tree for SQLite version VERSION
- including all of the documentation.
-}
-
-Product {sqlite-source-V3.zip} {
- This ZIP archive contains preprocessed C code for the SQLite library as
- individual source files.
- Unlike the tarballs below, all of the preprocessing and automatic
- code generation has already been done on these C code files, so they
- can be converted to object code directly with any ordinary C compiler.
-}
-
-Product {sqlite-amalgamation-V3.zip} {
- This ZIP archive contains all preprocessed C code combined into a
- single source file (the
- <a href="http://www.sqlite.org/cvstrac/wiki?p=TheAmalgamation">
- amalgamation</a>).
-}
-
-Product {sqlite-V3-tea.tar.gz} {
- A tarball of proprocessed source code together with a
- <a href="http://www.tcl.tk/doc/tea/">Tcl Extension Architecture (TEA)</a>
- compatible configure script and makefile.
-}
-
-Product {sqlite-V3.src.rpm} {
- An RPM containing complete source code for SQLite version VERSION
-}
-
-Heading {Cross-Platform Binaries}
-
-Product {sqlite-V3.kit} {
- A <a href="http://www.equi4.com/starkit.html">starkit</a> containing
- precompiled SQLite binaries and Tcl bindings for Linux-x86, Windows,
- and Mac OS-X ppc and x86.
-}
-
-Heading {Historical Binaries And Source Code}
-
-Product sqlite-V2.bin.gz {
- A command-line program for accessing and modifying
- SQLite version 2.* databases on Linux-x86.
-}
-Product sqlite-V2.zip {
- A command-line program for accessing and modifying
- SQLite version 2.* databases on win32.
-}
-
-Product sqlite*_analyzer-V2.bin.gz {
- An analysis program for version 2.* database files on Linux-x86
-}
-Product sqlite*_analyzer-V2.zip {
- An analysis program for version 2.* database files on win32.
-}
-Product {sqlite-source-V2.zip} {
- This ZIP archive contains C source code for the SQLite library
- version VERSION.
-}
-
-
-
-
-puts {
-</table>
-
-<a name="cvs">
-<h3>Direct Access To The Sources Via Anonymous CVS</h3>
-
-<p>
-All SQLite source code is maintained in a
-<a href="http://www.cvshome.org/">CVS</a> repository that is
-available for read-only access by anyone. You can
-interactively view the
-repository contents and download individual files
-by visiting
-<a href="http://www.sqlite.org/cvstrac/dir?d=sqlite">
-http://www.sqlite.org/cvstrac/dir?d=sqlite</a>.
-To access the repository directly, use the following
-commands:
-</p>
-
-<blockquote><pre>
-cvs -d :pserver:anonymous@www.sqlite.org:/sqlite login
-cvs -d :pserver:anonymous@www.sqlite.org:/sqlite checkout sqlite
-</pre></blockquote>
-
-<p>
-When the first command prompts you for a password, enter "anonymous".
-</p>
-
-<p>
-To access the SQLite version 2.8 sources, begin by getting the 3.0
-tree as described above. Then update to the "version_2" branch
-as follows:
-</p>
-
-<blockquote><pre>
-cvs update -r version_2
-</pre></blockquote>
-
-}
-
-footer $rcsid
+++ /dev/null
-#
-# Run this Tcl script to generate the dynload.html file.
-#
-set rcsid {$Id: dynload.tcl,v 1.1 2001/02/11 16:58:22 drh Exp $}
-
-puts {<html>
-<head>
- <title>How to build a dynamically loaded Tcl extension for SQLite</title>
-</head>
-<body bgcolor=white>
-<h1 align=center>
-How To Build A Dynamically Loaded Tcl Extension
-</h1>}
-puts {<p>
-<i>This note was contributed by
-<a href="bsaunder@tampabay.rr.com.nospam">Bill Saunders</a>. Thanks, Bill!</i>
-
-<p>
-To compile the SQLite Tcl extension into a dynamically loaded module
-I did the following:
-</p>
-
-<ol>
-<li><p>Do a standard compile
-(I had a dir called bld at the same level as sqlite ie
- /root/bld
- /root/sqlite
-I followed the directions and did a standard build in the bld
-directory)</p></li>
-
-<li><p>
-Now do the following in the bld directory
-<blockquote><pre>
-gcc -shared -I. -lgdbm ../sqlite/src/tclsqlite.c libsqlite.a -o sqlite.so
-</pre></blockquote></p></li>
-
-<li><p>
-This should produce the file sqlite.so in the bld directory</p></li>
-
-<li><p>
-Create a pkgIndex.tcl file that contains this line
-
-<blockquote><pre>
-package ifneeded sqlite 1.0 [list load [file join $dir sqlite.so]]
-</pre></blockquote></p></li>
-
-<li><p>
-To use this put sqlite.so and pkgIndex.tcl in the same directory</p></li>
-
-<li><p>
-From that directory start wish</p></li>
-
-<li><p>
-Execute the following tcl command (tells tcl where to fine loadable
-modules)
-<blockquote><pre>
-lappend auto_path [exec pwd]
-</pre></blockquote></p></li>
-
-<li><p>
-Load the package
-<blockquote><pre>
-package require sqlite
-</pre></blockquote></p></li>
-
-<li><p>
-Have fun....</p></li>
-</ul>
-
-</body></html>}
+++ /dev/null
-#
-# Run this script to generated a faq.html output file
-#
-set rcsid {$Id: faq.tcl,v 1.40 2007/09/04 01:58:27 drh Exp $}
-source common.tcl
-header {SQLite Frequently Asked Questions</title>}
-
-set cnt 1
-proc faq {question answer} {
- set ::faq($::cnt) [list [string trim $question] [string trim $answer]]
- incr ::cnt
-}
-
-#############
-# Enter questions and answers here.
-
-faq {
- How do I create an AUTOINCREMENT field.
-} {
- <p>Short answer: A column declared INTEGER PRIMARY KEY will
- autoincrement.</p>
-
- <p>Here is the long answer:
- If you declare a column of a table to be INTEGER PRIMARY KEY, then
- whenever you insert a NULL
- into that column of the table, the NULL is automatically converted
- into an integer which is one greater than the largest value of that
- column over all other rows in the table, or 1 if the table is empty.
- (If the largest possible integer key, 9223372036854775807, then an
- unused key value is chosen at random.)
- For example, suppose you have a table like this:
-<blockquote><pre>
-CREATE TABLE t1(
- a INTEGER PRIMARY KEY,
- b INTEGER
-);
-</pre></blockquote>
- <p>With this table, the statement</p>
-<blockquote><pre>
-INSERT INTO t1 VALUES(NULL,123);
-</pre></blockquote>
- <p>is logically equivalent to saying:</p>
-<blockquote><pre>
-INSERT INTO t1 VALUES((SELECT max(a) FROM t1)+1,123);
-</pre></blockquote>
-
- <p>There is a new API function named
- <a href="capi3ref.html#sqlite3_last_insert_rowid">
- sqlite3_last_insert_rowid()</a> which will return the integer key
- for the most recent insert operation.</p>
-
- <p>Note that the integer key is one greater than the largest
- key that was in the table just prior to the insert. The new key
- will be unique over all keys currently in the table, but it might
- overlap with keys that have been previously deleted from the
- table. To create keys that are unique over the lifetime of the
- table, add the AUTOINCREMENT keyword to the INTEGER PRIMARY KEY
- declaration. Then the key chosen will be one more than than the
- largest key that has ever existed in that table. If the largest
- possible key has previously existed in that table, then the INSERT
- will fail with an SQLITE_FULL error code.</p>
-}
-
-faq {
- What datatypes does SQLite support?
-} {
- <p>See <a href="datatype3.html">http://www.sqlite.org/datatype3.html</a>.</p>
-}
-
-faq {
- SQLite lets me insert a string into a database column of type integer!
-} {
- <p>This is a feature, not a bug. SQLite does not enforce data type
- constraints. Any data can be
- inserted into any column. You can put arbitrary length strings into
- integer columns, floating point numbers in boolean columns, or dates
- in character columns. The datatype you assign to a column in the
- CREATE TABLE command does not restrict what data can be put into
- that column. Every column is able to hold
- an arbitrary length string. (There is one exception: Columns of
- type INTEGER PRIMARY KEY may only hold a 64-bit signed integer.
- An error will result
- if you try to put anything other than an integer into an
- INTEGER PRIMARY KEY column.)</p>
-
- <p>But SQLite does use the declared type of a column as a hint
- that you prefer values in that format. So, for example, if a
- column is of type INTEGER and you try to insert a string into
- that column, SQLite will attempt to convert the string into an
- integer. If it can, it inserts the integer instead. If not,
- it inserts the string. This feature is sometimes
- call <a href="datatype3.html#affinity">type or column affinity</a>.
- </p>
-}
-
-faq {
- Why doesn't SQLite allow me to use '0' and '0.0' as the primary
- key on two different rows of the same table?
-} {
- <p>Your primary key must have a numeric type. Change the datatype of
- your primary key to TEXT and it should work.</p>
-
- <p>Every row must have a unique primary key. For a column with a
- numeric type, SQLite thinks that <b>'0'</b> and <b>'0.0'</b> are the
- same value because they compare equal to one another numerically.
- (See the previous question.) Hence the values are not unique.</p>
-}
-
-
-faq {
- Can multiple applications or multiple instances of the same
- application access a single database file at the same time?
-} {
- <p>Multiple processes can have the same database open at the same
- time. Multiple processes can be doing a SELECT
- at the same time. But only one process can be making changes to
- the database at any moment in time, however.</p>
-
- <p>SQLite uses reader/writer locks to control access to the database.
- (Under Win95/98/ME which lacks support for reader/writer locks, a
- probabilistic simulation is used instead.)
- But use caution: this locking mechanism might
- not work correctly if the database file is kept on an NFS filesystem.
- This is because fcntl() file locking is broken on many NFS implementations.
- You should avoid putting SQLite database files on NFS if multiple
- processes might try to access the file at the same time. On Windows,
- Microsoft's documentation says that locking may not work under FAT
- filesystems if you are not running the Share.exe daemon. People who
- have a lot of experience with Windows tell me that file locking of
- network files is very buggy and is not dependable. If what they
- say is true, sharing an SQLite database between two or more Windows
- machines might cause unexpected problems.</p>
-
- <p>We are aware of no other <i>embedded</i> SQL database engine that
- supports as much concurrancy as SQLite. SQLite allows multiple processes
- to have the database file open at once, and for multiple processes to
- read the database at once. When any process wants to write, it must
- lock the entire database file for the duration of its update. But that
- normally only takes a few milliseconds. Other processes just wait on
- the writer to finish then continue about their business. Other embedded
- SQL database engines typically only allow a single process to connect to
- the database at once.</p>
-
- <p>However, client/server database engines (such as PostgreSQL, MySQL,
- or Oracle) usually support a higher level of concurrency and allow
- multiple processes to be writing to the same database at the same time.
- This is possible in a client/server database because there is always a
- single well-controlled server process available to coordinate access.
- If your application has a need for a lot of concurrency, then you should
- consider using a client/server database. But experience suggests that
- most applications need much less concurrency than their designers imagine.
- </p>
-
- <p>When SQLite tries to access a file that is locked by another
- process, the default behavior is to return SQLITE_BUSY. You can
- adjust this behavior from C code using the
- <a href="capi3ref.html#sqlite3_busy_handler">sqlite3_busy_handler()</a> or
- <a href="capi3ref.html#sqlite3_busy_timeout">sqlite3_busy_timeout()</a>
- API functions.</p>
-}
-
-faq {
- Is SQLite threadsafe?
-} {
- <p>Yes. Sometimes. In order to be thread-safe, SQLite must be compiled
- with the SQLITE_THREADSAFE preprocessor macro set to 1. Both the windows
- and linux precompiled binaries in the distribution are compiled this way.
- If you are unsure if the SQLite library you are linking against is compiled
- to be threadsafe you can call the
- <a href="capi3ref.html#sqlite3_threadsafe">sqlite3_threadsafe()</a>
- interface to find out.
- </p>
-
- <p>Prior to version 3.3.1,
- an <b>sqlite3</b> structure could only be used in the same thread
- that called <a href="capi3ref.html#sqlite3_open">sqlite3_open</a>
- to create it.
- You could not open a
- database in one thread then pass the handle off to another thread for
- it to use. This was due to limitations (bugs?) in many common threading
- implementations such as on RedHat9. Specifically, an fcntl() lock
- created by one thread cannot be removed or modified by a different
- thread on the troublesome systems. And since SQLite uses fcntl()
- locks heavily for concurrency control, serious problems arose if you
- start moving database connections across threads.</p>
-
- <p>The restriction on moving database connections across threads
- was relaxed somewhat in version 3.3.1. With that and subsequent
- versions, it is safe to move a connection handle across threads
- as long as the connection is not holding any fcntl() locks. You
- can safely assume that no locks are being held if no
- transaction is pending and all statements have been finalized.</p>
-
- <p>Under UNIX, you should not carry an open SQLite database across
- a fork() system call into the child process. Problems will result
- if you do.</p>
-}
-
-faq {
- How do I list all tables/indices contained in an SQLite database
-} {
- <p>If you are running the <b>sqlite3</b> command-line access program
- you can type "<b>.tables</b>" to get a list of all tables. Or you
- can type "<b>.schema</b>" to see the complete database schema including
- all tables and indices. Either of these commands can be followed by
- a LIKE pattern that will restrict the tables that are displayed.</p>
-
- <p>From within a C/C++ program (or a script using Tcl/Ruby/Perl/Python
- bindings) you can get access to table and index names by doing a SELECT
- on a special table named "<b>SQLITE_MASTER</b>". Every SQLite database
- has an SQLITE_MASTER table that defines the schema for the database.
- The SQLITE_MASTER table looks like this:</p>
-<blockquote><pre>
-CREATE TABLE sqlite_master (
- type TEXT,
- name TEXT,
- tbl_name TEXT,
- rootpage INTEGER,
- sql TEXT
-);
-</pre></blockquote>
- <p>For tables, the <b>type</b> field will always be <b>'table'</b> and the
- <b>name</b> field will be the name of the table. So to get a list of
- all tables in the database, use the following SELECT command:</p>
-<blockquote><pre>
-SELECT name FROM sqlite_master
-WHERE type='table'
-ORDER BY name;
-</pre></blockquote>
- <p>For indices, <b>type</b> is equal to <b>'index'</b>, <b>name</b> is the
- name of the index and <b>tbl_name</b> is the name of the table to which
- the index belongs. For both tables and indices, the <b>sql</b> field is
- the text of the original CREATE TABLE or CREATE INDEX statement that
- created the table or index. For automatically created indices (used
- to implement the PRIMARY KEY or UNIQUE constraints) the <b>sql</b> field
- is NULL.</p>
-
- <p>The SQLITE_MASTER table is read-only. You cannot change this table
- using UPDATE, INSERT, or DELETE. The table is automatically updated by
- CREATE TABLE, CREATE INDEX, DROP TABLE, and DROP INDEX commands.</p>
-
- <p>Temporary tables do not appear in the SQLITE_MASTER table. Temporary
- tables and their indices and triggers occur in another special table
- named SQLITE_TEMP_MASTER. SQLITE_TEMP_MASTER works just like SQLITE_MASTER
- except that it is only visible to the application that created the
- temporary tables. To get a list of all tables, both permanent and
- temporary, one can use a command similar to the following:
-<blockquote><pre>
-SELECT name FROM
- (SELECT * FROM sqlite_master UNION ALL
- SELECT * FROM sqlite_temp_master)
-WHERE type='table'
-ORDER BY name
-</pre></blockquote>
-}
-
-faq {
- Are there any known size limits to SQLite databases?
-} {
- <p>See <a href="limits.html">limits.html</a> for a full discussion of
- the limits of SQLite.</p>
-}
-
-faq {
- What is the maximum size of a VARCHAR in SQLite?
-} {
- <p>SQLite does not enforce the length of a VARCHAR. You can declare
- a VARCHAR(10) and SQLite will be happy to let you put 500 characters
- in it. And it will keep all 500 characters intact - it never truncates.
- </p>
-}
-
-faq {
- Does SQLite support a BLOB type?
-} {
- <p>SQLite versions 3.0 and later allow you to store BLOB data in any
- column, even columns that are declared to hold some other type.</p>
-}
-
-faq {
- How do I add or delete columns from an existing table in SQLite.
-} {
- <p>SQLite has limited
- <a href="lang_altertable.html">ALTER TABLE</a> support that you can
- use to add a column to the end of a table or to change the name of
- a table.
- If you what make more complex changes the structure of a table,
- you will have to recreate the
- table. You can save existing data to a temporary table, drop the
- old table, create the new table, then copy the data back in from
- the temporary table.</p>
-
- <p>For example, suppose you have a table named "t1" with columns
- names "a", "b", and "c" and that you want to delete column "c" from
- this table. The following steps illustrate how this could be done:
- </p>
-
- <blockquote><pre>
-BEGIN TRANSACTION;
-CREATE TEMPORARY TABLE t1_backup(a,b);
-INSERT INTO t1_backup SELECT a,b FROM t1;
-DROP TABLE t1;
-CREATE TABLE t1(a,b);
-INSERT INTO t1 SELECT a,b FROM t1_backup;
-DROP TABLE t1_backup;
-COMMIT;
-</pre></blockquote>
-}
-
-faq {
- I deleted a lot of data but the database file did not get any
- smaller. Is this a bug?
-} {
- <p>No. When you delete information from an SQLite database, the
- unused disk space is added to an internal "free-list" and is reused
- the next time you insert data. The disk space is not lost. But
- neither is it returned to the operating system.</p>
-
- <p>If you delete a lot of data and want to shrink the database file,
- run the <a href="lang_vacuum.html">VACUUM</a> command.
- VACUUM will reconstruct
- the database from scratch. This will leave the database with an empty
- free-list and a file that is minimal in size. Note, however, that the
- VACUUM can take some time to run (around a half second per megabyte
- on the Linux box where SQLite is developed) and it can use up to twice
- as much temporary disk space as the original file while it is running.
- </p>
-
- <p>As of SQLite version 3.1, an alternative to using the VACUUM command
- is auto-vacuum mode, enabled using the
- <a href="pragma.html#pragma_auto_vacuum">auto_vacuum pragma</a>.</p>
-}
-
-faq {
- Can I use SQLite in my commercial product without paying royalties?
-} {
- <p>Yes. SQLite is in the
- <a href="copyright.html">public domain</a>. No claim of ownership is made
- to any part of the code. You can do anything you want with it.</p>
-}
-
-faq {
- How do I use a string literal that contains an embedded single-quote (')
- character?
-} {
- <p>The SQL standard specifies that single-quotes in strings are escaped
- by putting two single quotes in a row. SQL works like the Pascal programming
- language in the regard. SQLite follows this standard. Example:
- </p>
-
- <blockquote><pre>
- INSERT INTO xyz VALUES('5 O''clock');
- </pre></blockquote>
-}
-
-faq {What is an SQLITE_SCHEMA error, and why am I getting one?} {
- <p>An SQLITE_SCHEMA error is returned when a
- prepared SQL statement is no longer valid and cannot be executed.
- When this occurs, the statement must be recompiled from SQL using
- the
- <a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a> API.
- In SQLite version 3, an SQLITE_SCHEMA error can
- only occur when using the
- <a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a>/<a
- href="capi3ref.html#sqlite3_step">sqlite3_step()</a>/<a
- href="capi3ref.html#sqlite3_finalize">sqlite3_finalize()</a>
- API to execute SQL, not when using the
- <a href="capi3ref.html#sqlite3_exec">sqlite3_exec()</a>. This was not
- the case in version 2.</p>
-
- <p>The most common reason for a prepared statement to become invalid
- is that the schema of the database was modified after the SQL was
- prepared (possibly by another process). The other reasons this can
- happen are:</p>
- <ul>
- <li>A database was <a href="lang_detach.html">DETACH</a>ed.
- <li>The database was <a href="lang_vacuum.html">VACUUM</a>ed
- <li>A user-function definition was deleted or changed.
- <li>A collation sequence definition was deleted or changed.
- <li>The authorization function was changed.
- </ul>
-
- <p>In all cases, the solution is to recompile the statement from SQL
- and attempt to execute it again. Because a prepared statement can be
- invalidated by another process changing the database schema, all code
- that uses the
- <a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a>/<a
- href="capi3ref.html#sqlite3_step">sqlite3_step()</a>/<a
- href="capi3ref.html#sqlite3_finalize">sqlite3_finalize()</a>
- API should be prepared to handle SQLITE_SCHEMA errors. An example
- of one approach to this follows:</p>
-
- <blockquote><pre>
-
- int rc;
- sqlite3_stmt *pStmt;
- char zSql[] = "SELECT .....";
-
- do {
- /* Compile the statement from SQL. Assume success. */
- sqlite3_prepare(pDb, zSql, -1, &pStmt, 0);
-
- while( SQLITE_ROW==sqlite3_step(pStmt) ){
- /* Do something with the row of available data */
- }
-
- /* Finalize the statement. If an SQLITE_SCHEMA error has
- ** occured, then the above call to sqlite3_step() will have
- ** returned SQLITE_ERROR. sqlite3_finalize() will return
- ** SQLITE_SCHEMA. In this case the loop will execute again.
- */
- rc = sqlite3_finalize(pStmt);
- } while( rc==SQLITE_SCHEMA );
-
- </pre></blockquote>
-}
-
-faq {Why does ROUND(9.95,1) return 9.9 instead of 10.0?
- Shouldn't 9.95 round up?} {
- <p>SQLite uses binary arithmetic and in binary, there is no
- way to write 9.95 in a finite number of bits. The closest to
- you can get to 9.95 in a 64-bit IEEE float (which is what
- SQLite uses) is 9.949999999999999289457264239899814128875732421875.
- So when you type "9.95", SQLite really understands the number to be
- the much longer value shown above. And that value rounds down.</p>
-
- <p>This kind of problem comes up all the time when dealing with
- floating point binary numbers. The general rule to remember is
- that most fractional numbers that have a finite representation in decimal
- (a.k.a "base-10")
- do not have a finite representation in binary (a.k.a "base-2").
- And so they are
- approximated using the closest binary number available. That
- approximation is usually very close, but it will be slightly off
- and in some cases can cause your results to be a little different
- from what you might expect.</p>
-}
-
-# End of questions and answers.
-#############
-
-puts {<h2>Frequently Asked Questions</h2>}
-
-# puts {<DL COMPACT>}
-# for {set i 1} {$i<$cnt} {incr i} {
-# puts " <DT><A HREF=\"#q$i\">($i)</A></DT>"
-# puts " <DD>[lindex $faq($i) 0]</DD>"
-# }
-# puts {</DL>}
-puts {<OL>}
-for {set i 1} {$i<$cnt} {incr i} {
- puts "<li><a href=\"#q$i\">[lindex $faq($i) 0]</a></li>"
-}
-puts {</OL>}
-
-for {set i 1} {$i<$cnt} {incr i} {
- puts "<A NAME=\"q$i\"><HR />"
- puts "<P><B>($i) [lindex $faq($i) 0]</B></P>\n"
- puts "<BLOCKQUOTE>[lindex $faq($i) 1]</BLOCKQUOTE></LI>\n"
-}
-
-puts {</OL>}
-footer $rcsid
+++ /dev/null
-#
-# Run this script to generated a fileformat.html output file
-#
-set rcsid {$Id: fileformat.tcl,v 1.13 2004/10/10 17:24:55 drh Exp $}
-source common.tcl
-header {SQLite Database File Format (Version 2)}
-puts {
-<h2>SQLite 2.X Database File Format</h2>
-
-<p>
-This document describes the disk file format for SQLite versions 2.1
-through 2.8. SQLite version 3.0 and following uses a very different
-format which is described separately.
-</p>
-
-<h3>1.0 Layers</h3>
-
-<p>
-SQLite is implemented in layers.
-(See the <a href="arch.html">architecture description</a>.)
-The format of database files is determined by three different
-layers in the architecture.
-</p>
-
-<ul>
-<li>The <b>schema</b> layer implemented by the VDBE.</li>
-<li>The <b>b-tree</b> layer implemented by btree.c</li>
-<li>The <b>pager</b> layer implemented by pager.c</li>
-</ul>
-
-<p>
-We will describe each layer beginning with the bottom (pager)
-layer and working upwards.
-</p>
-
-<h3>2.0 The Pager Layer</h3>
-
-<p>
-An SQLite database consists of
-"pages" of data. Each page is 1024 bytes in size.
-Pages are numbered beginning with 1.
-A page number of 0 is used to indicate "no such page" in the
-B-Tree and Schema layers.
-</p>
-
-<p>
-The pager layer is responsible for implementing transactions
-with atomic commit and rollback. It does this using a separate
-journal file. Whenever a new transaction is started, a journal
-file is created that records the original state of the database.
-If the program terminates before completing the transaction, the next
-process to open the database can use the journal file to restore
-the database to its original state.
-</p>
-
-<p>
-The journal file is located in the same directory as the database
-file and has the same name as the database file but with the
-characters "<tt>-journal</tt>" appended.
-</p>
-
-<p>
-The pager layer does not impose any content restrictions on the
-main database file. As far as the pager is concerned, each page
-contains 1024 bytes of arbitrary data. But there is structure to
-the journal file.
-</p>
-
-<p>
-A journal file begins with 8 bytes as follows:
-0xd9, 0xd5, 0x05, 0xf9, 0x20, 0xa1, 0x63, and 0xd6.
-Processes that are attempting to rollback a journal use these 8 bytes
-as a sanity check to make sure the file they think is a journal really
-is a valid journal. Prior version of SQLite used different journal
-file formats. The magic numbers for these prior formats are different
-so that if a new version of the library attempts to rollback a journal
-created by an earlier version, it can detect that the journal uses
-an obsolete format and make the necessary adjustments. This article
-describes only the newest journal format - supported as of version
-2.8.0.
-</p>
-
-<p>
-Following the 8 byte prefix is a three 4-byte integers that tell us
-the number of pages that have been committed to the journal,
-a magic number used for
-sanity checking each page, and the
-original size of the main database file before the transaction was
-started. The number of committed pages is used to limit how far
-into the journal to read. The use of the checksum magic number is
-described below.
-The original size of the database is used to restore the database
-file back to its original size.
-The size is expressed in pages (1024 bytes per page).
-</p>
-
-<p>
-All three integers in the journal header and all other multi-byte
-numbers used in the journal file are big-endian.
-That means that the most significant byte
-occurs first. That way, a journal file that is
-originally created on one machine can be rolled back by another
-machine that uses a different byte order. So, for example, a
-transaction that failed to complete on your big-endian SparcStation
-can still be rolled back on your little-endian Linux box.
-</p>
-
-<p>
-After the 8-byte prefix and the three 4-byte integers, the
-journal file consists of zero or more page records. Each page
-record is a 4-byte (big-endian) page number followed by 1024 bytes
-of data and a 4-byte checksum.
-The data is the original content of the database page
-before the transaction was started. So to roll back the transaction,
-the data is simply written into the corresponding page of the
-main database file. Pages can appear in the journal in any order,
-but they are guaranteed to appear only once. All page numbers will be
-between 1 and the maximum specified by the page size integer that
-appeared at the beginning of the journal.
-</p>
-
-<p>
-The so-called checksum at the end of each record is not really a
-checksum - it is the sum of the page number and the magic number which
-was the second integer in the journal header. The purpose of this
-value is to try to detect journal corruption that might have occurred
-because of a power loss or OS crash that occurred which the journal
-file was being written to disk. It could have been the case that the
-meta-data for the journal file, specifically the size of the file, had
-been written to the disk so that when the machine reboots it appears that
-file is large enough to hold the current record. But even though the
-file size has changed, the data for the file might not have made it to
-the disk surface at the time of the OS crash or power loss. This means
-that after reboot, the end of the journal file will contain quasi-random
-garbage data. The checksum is an attempt to detect such corruption. If
-the checksum does not match, that page of the journal is not rolled back.
-</p>
-
-<p>
-Here is a summary of the journal file format:
-</p>
-
-<ul>
-<li>8 byte prefix: 0xd9, 0xd5, 0x05, 0xf9, 0x20, 0xa1, 0x63, 0xd6</li>
-<li>4 byte number of records in journal</li>
-<li>4 byte magic number used for page checksums</li>
-<li>4 byte initial database page count</li>
-<li>Zero or more instances of the following:
- <ul>
- <li>4 byte page number</li>
- <li>1024 bytes of original data for the page</li>
- <li>4 byte checksum</li>
- </ul>
-</li>
-</ul>
-
-<h3>3.0 The B-Tree Layer</h3>
-
-<p>
-The B-Tree layer builds on top of the pager layer to implement
-one or more separate b-trees all in the same disk file. The
-algorithms used are taken from Knuth's <i>The Art Of Computer
-Programming.</i></p>
-
-<p>
-Page 1 of a database contains a header string used for sanity
-checking, a few 32-bit words of configuration data, and a pointer
-to the beginning of a list of unused pages in the database.
-All other pages in the
-database are either pages of a b-tree, overflow pages, or unused
-pages on the freelist.
-</p>
-
-<p>
-Each b-tree page contains zero or more database entries.
-Each entry has an unique key of one or more bytes and data of
-zero or more bytes.
-Both the key and data are arbitrary byte sequences. The combination
-of key and data are collectively known as "payload". The current
-implementation limits the amount of payload in a single entry to
-1048576 bytes. This limit can be raised to 16777216 by adjusting
-a single #define in the source code and recompiling. But most entries
-contain less than a hundred bytes of payload so a megabyte limit seems
-more than enough.
-</p>
-
-<p>
-Up to 238 bytes of payload for an entry can be held directly on
-a b-tree page. Any additional payload is contained on a linked list
-of overflow pages. This limit on the amount of payload held directly
-on b-tree pages guarantees that each b-tree page can hold at least
-4 entries. In practice, most entries are smaller than 238 bytes and
-thus most pages can hold more than 4 entries.
-</p>
-
-<p>
-A single database file can hold any number of separate, independent b-trees.
-Each b-tree is identified by its root page, which never changes.
-Child pages of the b-tree may change as entries are added and removed
-and pages split and combine. But the root page always stays the same.
-The b-tree itself does not record which pages are root pages and which
-are not. That information is handled entirely at the schema layer.
-</p>
-
-<h4>3.1 B-Tree Page 1 Details</h4>
-
-<p>
-Page 1 begins with the following 48-byte string:
-</p>
-
-<blockquote><pre>
-** This file contains an SQLite 2.1 database **
-</pre></blockquote>
-
-<p>
-If you count the number of characters in the string above, you will
-see that there are only 47. A '\000' terminator byte is added to
-bring the total to 48.
-</p>
-
-<p>
-A frequent question is why the string says version 2.1 when (as
-of this writing) we are up to version 2.7.0 of SQLite and any
-change to the second digit of the version is suppose to represent
-a database format change. The answer to this is that the B-tree
-layer has not changed any since version 2.1. There have been
-database format changes since version 2.1 but those changes have
-all been in the schema layer. Because the format of the b-tree
-layer is unchanged since version 2.1.0, the header string still
-says version 2.1.
-</p>
-
-<p>
-After the format string is a 4-byte integer used to determine the
-byte-order of the database. The integer has a value of
-0xdae37528. If this number is expressed as 0xda, 0xe3, 0x75, 0x28, then
-the database is in a big-endian format and all 16 and 32-bit integers
-elsewhere in the b-tree layer are also big-endian. If the number is
-expressed as 0x28, 0x75, 0xe3, and 0xda, then the database is in a
-little-endian format and all other multi-byte numbers in the b-tree
-layer are also little-endian.
-Prior to version 2.6.3, the SQLite engine was only able to read databases
-that used the same byte order as the processor they were running on.
-But beginning with 2.6.3, SQLite can read or write databases in any
-byte order.
-</p>
-
-<p>
-After the byte-order code are six 4-byte integers. Each integer is in the
-byte order determined by the byte-order code. The first integer is the
-page number for the first page of the freelist. If there are no unused
-pages in the database, then this integer is 0. The second integer is
-the number of unused pages in the database. The last 4 integers are
-not used by the b-tree layer. These are the so-called "meta" values that
-are passed up to the schema layer
-and used there for configuration and format version information.
-All bytes of page 1 past beyond the meta-value integers are unused
-and are initialized to zero.
-</p>
-
-<p>
-Here is a summary of the information contained on page 1 in the b-tree layer:
-</p>
-
-<ul>
-<li>48 byte header string</li>
-<li>4 byte integer used to determine the byte-order</li>
-<li>4 byte integer which is the first page of the freelist</li>
-<li>4 byte integer which is the number of pages on the freelist</li>
-<li>36 bytes of meta-data arranged as nine 4-byte integers</li>
-<li>928 bytes of unused space</li>
-</ul>
-
-<h4>3.2 Structure Of A Single B-Tree Page</h4>
-
-<p>
-Conceptually, a b-tree page contains N database entries and N+1 pointers
-to other b-tree pages.
-</p>
-
-<blockquote>
-<table border=1 cellspacing=0 cellpadding=5>
-<tr>
-<td align="center">Ptr<br>0</td>
-<td align="center">Entry<br>0</td>
-<td align="center">Ptr<br>1</td>
-<td align="center">Entry<br>1</td>
-<td align="center"><b>...</b></td>
-<td align="center">Ptr<br>N-1</td>
-<td align="center">Entry<br>N-1</td>
-<td align="center">Ptr<br>N</td>
-</tr>
-</table>
-</blockquote>
-
-<p>
-The entries are arranged in increasing order. That is, the key to
-Entry 0 is less than the key to Entry 1, and the key to Entry 1 is
-less than the key of Entry 2, and so forth. The pointers point to
-pages containing additional entries that have keys in between the
-entries on either side. So Ptr 0 points to another b-tree page that
-contains entries that all have keys less than Key 0, and Ptr 1
-points to a b-tree pages where all entries have keys greater than Key 0
-but less than Key 1, and so forth.
-</p>
-
-<p>
-Each b-tree page in SQLite consists of a header, zero or more "cells"
-each holding a single entry and pointer, and zero or more "free blocks"
-that represent unused space on the page.
-</p>
-
-<p>
-The header on a b-tree page is the first 8 bytes of the page.
-The header contains the value
-of the right-most pointer (Ptr N) and the byte offset into the page
-of the first cell and the first free block. The pointer is a 32-bit
-value and the offsets are each 16-bit values. We have:
-</p>
-
-<blockquote>
-<table border=1 cellspacing=0 cellpadding=5>
-<tr>
-<td align="center" width=30>0</td>
-<td align="center" width=30>1</td>
-<td align="center" width=30>2</td>
-<td align="center" width=30>3</td>
-<td align="center" width=30>4</td>
-<td align="center" width=30>5</td>
-<td align="center" width=30>6</td>
-<td align="center" width=30>7</td>
-</tr>
-<tr>
-<td align="center" colspan=4>Ptr N</td>
-<td align="center" colspan=2>Cell 0</td>
-<td align="center" colspan=2>Freeblock 0</td>
-</tr>
-</table>
-</blockquote>
-
-<p>
-The 1016 bytes of a b-tree page that come after the header contain
-cells and freeblocks. All 1016 bytes are covered by either a cell
-or a freeblock.
-</p>
-
-<p>
-The cells are connected in a linked list. Cell 0 contains Ptr 0 and
-Entry 0. Bytes 4 and 5 of the header point to Cell 0. Cell 0 then
-points to Cell 1 which contains Ptr 1 and Entry 1. And so forth.
-Cells vary in size. Every cell has a 12-byte header and at least 4
-bytes of payload space. Space is allocated to payload in increments
-of 4 bytes. Thus the minimum size of a cell is 16 bytes and up to
-63 cells can fit on a single page. The size of a cell is always a multiple
-of 4 bytes.
-A cell can have up to 238 bytes of payload space. If
-the payload is more than 238 bytes, then an additional 4 byte page
-number is appended to the cell which is the page number of the first
-overflow page containing the additional payload. The maximum size
-of a cell is thus 254 bytes, meaning that a least 4 cells can fit into
-the 1016 bytes of space available on a b-tree page.
-An average cell is usually around 52 to 100 bytes in size with about
-10 or 20 cells to a page.
-</p>
-
-<p>
-The data layout of a cell looks like this:
-</p>
-
-<blockquote>
-<table border=1 cellspacing=0 cellpadding=5>
-<tr>
-<td align="center" width=20>0</td>
-<td align="center" width=20>1</td>
-<td align="center" width=20>2</td>
-<td align="center" width=20>3</td>
-<td align="center" width=20>4</td>
-<td align="center" width=20>5</td>
-<td align="center" width=20>6</td>
-<td align="center" width=20>7</td>
-<td align="center" width=20>8</td>
-<td align="center" width=20>9</td>
-<td align="center" width=20>10</td>
-<td align="center" width=20>11</td>
-<td align="center" width=100>12 ... 249</td>
-<td align="center" width=20>250</td>
-<td align="center" width=20>251</td>
-<td align="center" width=20>252</td>
-<td align="center" width=20>253</td>
-</tr>
-<tr>
-<td align="center" colspan=4>Ptr</td>
-<td align="center" colspan=2>Keysize<br>(low)</td>
-<td align="center" colspan=2>Next</td>
-<td align="center" colspan=1>Ksz<br>(hi)</td>
-<td align="center" colspan=1>Dsz<br>(hi)</td>
-<td align="center" colspan=2>Datasize<br>(low)</td>
-<td align="center" colspan=1>Payload</td>
-<td align="center" colspan=4>Overflow<br>Pointer</td>
-</tr>
-</table>
-</blockquote>
-
-<p>
-The first four bytes are the pointer. The size of the key is a 24-bit
-where the upper 8 bits are taken from byte 8 and the lower 16 bits are
-taken from bytes 4 and 5 (or bytes 5 and 4 on little-endian machines.)
-The size of the data is another 24-bit value where the upper 8 bits
-are taken from byte 9 and the lower 16 bits are taken from bytes 10 and
-11 or 11 and 10, depending on the byte order. Bytes 6 and 7 are the
-offset to the next cell in the linked list of all cells on the current
-page. This offset is 0 for the last cell on the page.
-</p>
-
-<p>
-The payload itself can be any number of bytes between 1 and 1048576.
-But space to hold the payload is allocated in 4-byte chunks up to
-238 bytes. If the entry contains more than 238 bytes of payload, then
-additional payload data is stored on a linked list of overflow pages.
-A 4 byte page number is appended to the cell that contains the first
-page of this linked list.
-</p>
-
-<p>
-Each overflow page begins with a 4-byte value which is the
-page number of the next overflow page in the list. This value is
-0 for the last page in the list. The remaining
-1020 bytes of the overflow page are available for storing payload.
-Note that a full page is allocated regardless of the number of overflow
-bytes stored. Thus, if the total payload for an entry is 239 bytes,
-the first 238 are stored in the cell and the overflow page stores just
-one byte.
-</p>
-
-<p>
-The structure of an overflow page looks like this:
-</p>
-
-<blockquote>
-<table border=1 cellspacing=0 cellpadding=5>
-<tr>
-<td align="center" width=20>0</td>
-<td align="center" width=20>1</td>
-<td align="center" width=20>2</td>
-<td align="center" width=20>3</td>
-<td align="center" width=200>4 ... 1023</td>
-</tr>
-<tr>
-<td align="center" colspan=4>Next Page</td>
-<td align="center" colspan=1>Overflow Data</td>
-</tr>
-</table>
-</blockquote>
-
-<p>
-All space on a b-tree page which is not used by the header or by cells
-is filled by freeblocks. Freeblocks, like cells, are variable in size.
-The size of a freeblock is at least 4 bytes and is always a multiple of
-4 bytes.
-The first 4 bytes contain a header and the remaining bytes
-are unused. The structure of the freeblock is as follows:
-</p>
-
-<blockquote>
-<table border=1 cellspacing=0 cellpadding=5>
-<tr>
-<td align="center" width=20>0</td>
-<td align="center" width=20>1</td>
-<td align="center" width=20>2</td>
-<td align="center" width=20>3</td>
-<td align="center" width=200>4 ... 1015</td>
-</tr>
-<tr>
-<td align="center" colspan=2>Size</td>
-<td align="center" colspan=2>Next</td>
-<td align="center" colspan=1>Unused</td>
-</tr>
-</table>
-</blockquote>
-
-<p>
-Freeblocks are stored in a linked list in increasing order. That is
-to say, the first freeblock occurs at a lower index into the page than
-the second free block, and so forth. The first 2 bytes of the header
-are an integer which is the total number of bytes in the freeblock.
-The second 2 bytes are the index into the page of the next freeblock
-in the list. The last freeblock has a Next value of 0.
-</p>
-
-<p>
-When a new b-tree is created in a database, the root page of the b-tree
-consist of a header and a single 1016 byte freeblock. As entries are
-added, space is carved off of that freeblock and used to make cells.
-When b-tree entries are deleted, the space used by their cells is converted
-into freeblocks. Adjacent freeblocks are merged, but the page can still
-become fragmented. The b-tree code will occasionally try to defragment
-the page by moving all cells to the beginning and constructing a single
-freeblock at the end to take up all remaining space.
-</p>
-
-<h4>3.3 The B-Tree Free Page List</h4>
-
-<p>
-When information is removed from an SQLite database such that one or
-more pages are no longer needed, those pages are added to a list of
-free pages so that they can be reused later when new information is
-added. This subsection describes the structure of this freelist.
-</p>
-
-<p>
-The 32-bit integer beginning at byte-offset 52 in page 1 of the database
-contains the address of the first page in a linked list of free pages.
-If there are no free pages available, this integer has a value of 0.
-The 32-bit integer at byte-offset 56 in page 1 contains the number of
-free pages on the freelist.
-</p>
-
-<p>
-The freelist contains a trunk and many branches. The trunk of
-the freelist is composed of overflow pages. That is to say, each page
-contains a single 32-bit integer at byte offset 0 which
-is the page number of the next page on the freelist trunk.
-The payload area
-of each trunk page is used to record pointers to branch pages.
-The first 32-bit integer in the payload area of a trunk page
-is the number of branch pages to follow (between 0 and 254)
-and each subsequent 32-bit integer is a page number for a branch page.
-The following diagram shows the structure of a trunk freelist page:
-</p>
-
-<blockquote>
-<table border=1 cellspacing=0 cellpadding=5>
-<tr>
-<td align="center" width=20>0</td>
-<td align="center" width=20>1</td>
-<td align="center" width=20>2</td>
-<td align="center" width=20>3</td>
-<td align="center" width=20>4</td>
-<td align="center" width=20>5</td>
-<td align="center" width=20>6</td>
-<td align="center" width=20>7</td>
-<td align="center" width=200>8 ... 1023</td>
-</tr>
-<tr>
-<td align="center" colspan=4>Next trunk page</td>
-<td align="center" colspan=4># of branch pages</td>
-<td align="center" colspan=1>Page numbers for branch pages</td>
-</tr>
-</table>
-</blockquote>
-
-<p>
-It is important to note that only the pages on the trunk of the freelist
-contain pointers to other pages. The branch pages contain no
-data whatsoever. The fact that the branch pages are completely
-blank allows for an important optimization in the paging layer. When
-a branch page is removed from the freelist to be reused, it is not
-necessary to write the original content of that page into the rollback
-journal. The branch page contained no data to begin with, so there is
-no need to restore the page in the event of a rollback. Similarly,
-when a page is not longer needed and is added to the freelist as a branch
-page, it is not necessary to write the content of that page
-into the database file.
-Again, the page contains no real data so it is not necessary to record the
-content of that page. By reducing the amount of disk I/O required,
-these two optimizations allow some database operations
-to go four to six times faster than they would otherwise.
-</p>
-
-<h3>4.0 The Schema Layer</h3>
-
-<p>
-The schema layer implements an SQL database on top of one or more
-b-trees and keeps track of the root page numbers for all b-trees.
-Where the b-tree layer provides only unformatted data storage with
-a unique key, the schema layer allows each entry to contain multiple
-columns. The schema layer also allows indices and non-unique key values.
-</p>
-
-<p>
-The schema layer implements two separate data storage abstractions:
-tables and indices. Each table and each index uses its own b-tree
-but they use the b-tree capabilities in different ways. For a table,
-the b-tree key is a unique 4-byte integer and the b-tree data is the
-content of the table row, encoded so that columns can be separately
-extracted. For indices, the b-tree key varies in size depending on the
-size of the fields being indexed and the b-tree data is empty.
-</p>
-
-<h4>4.1 SQL Table Implementation Details</h4>
-
-<p>Each row of an SQL table is stored in a single b-tree entry.
-The b-tree key is a 4-byte big-endian integer that is the ROWID
-or INTEGER PRIMARY KEY for that table row.
-The key is stored in a big-endian format so
-that keys will sort in numerical order using memcmp() function.</p>
-
-<p>The content of a table row is stored in the data portion of
-the corresponding b-tree table. The content is encoded to allow
-individual columns of the row to be extracted as necessary. Assuming
-that the table has N columns, the content is encoded as N+1 offsets
-followed by N column values, as follows:
-</p>
-
-<blockquote>
-<table border=1 cellspacing=0 cellpadding=5>
-<tr>
-<td>offset 0</td>
-<td>offset 1</td>
-<td><b>...</b></td>
-<td>offset N-1</td>
-<td>offset N</td>
-<td>value 0</td>
-<td>value 1</td>
-<td><b>...</b></td>
-<td>value N-1</td>
-</tr>
-</table>
-</blockquote>
-
-<p>
-The offsets can be either 8-bit, 16-bit, or 24-bit integers depending
-on how much data is to be stored. If the total size of the content
-is less than 256 bytes then 8-bit offsets are used. If the total size
-of the b-tree data is less than 65536 then 16-bit offsets are used.
-24-bit offsets are used otherwise. Offsets are always little-endian,
-which means that the least significant byte occurs first.
-</p>
-
-<p>
-Data is stored as a nul-terminated string. Any empty string consists
-of just the nul terminator. A NULL value is an empty string with no
-nul-terminator. Thus a NULL value occupies zero bytes and an empty string
-occupies 1 byte.
-</p>
-
-<p>
-Column values are stored in the order that they appear in the CREATE TABLE
-statement. The offsets at the beginning of the record contain the
-byte index of the corresponding column value. Thus, Offset 0 contains
-the byte index for Value 0, Offset 1 contains the byte offset
-of Value 1, and so forth. The number of bytes in a column value can
-always be found by subtracting offsets. This allows NULLs to be
-recovered from the record unambiguously.
-</p>
-
-<p>
-Most columns are stored in the b-tree data as described above.
-The one exception is column that has type INTEGER PRIMARY KEY.
-INTEGER PRIMARY KEY columns correspond to the 4-byte b-tree key.
-When an SQL statement attempts to read the INTEGER PRIMARY KEY,
-the 4-byte b-tree key is read rather than information out of the
-b-tree data. But there is still an Offset associated with the
-INTEGER PRIMARY KEY, just like any other column. But the Value
-associated with that offset is always NULL.
-</p>
-
-<h4>4.2 SQL Index Implementation Details</h4>
-
-<p>
-SQL indices are implement using a b-tree in which the key is used
-but the data is always empty. The purpose of an index is to map
-one or more column values into the ROWID for the table entry that
-contains those column values.
-</p>
-
-<p>
-Each b-tree in an index consists of one or more column values followed
-by a 4-byte ROWID. Each column value is nul-terminated (even NULL values)
-and begins with a single character that indicates the datatype for that
-column value. Only three datatypes are supported: NULL, Number, and
-Text. NULL values are encoded as the character 'a' followed by the
-nul terminator. Numbers are encoded as the character 'b' followed by
-a string that has been crafted so that sorting the string using memcmp()
-will sort the corresponding numbers in numerical order. (See the
-sqliteRealToSortable() function in util.c of the SQLite sources for
-additional information on this encoding.) Numbers are also nul-terminated.
-Text values consists of the character 'c' followed by a copy of the
-text string and a nul-terminator. These encoding rules result in
-NULLs being sorted first, followed by numerical values in numerical
-order, followed by text values in lexicographical order.
-</p>
-
-<h4>4.4 SQL Schema Storage And Root B-Tree Page Numbers</h4>
-
-<p>
-The database schema is stored in the database in a special tabled named
-"sqlite_master" and which always has a root b-tree page number of 2.
-This table contains the original CREATE TABLE,
-CREATE INDEX, CREATE VIEW, and CREATE TRIGGER statements used to define
-the database to begin with. Whenever an SQLite database is opened,
-the sqlite_master table is scanned from beginning to end and
-all the original CREATE statements are played back through the parser
-in order to reconstruct an in-memory representation of the database
-schema for use in subsequent command parsing. For each CREATE TABLE
-and CREATE INDEX statement, the root page number for the corresponding
-b-tree is also recorded in the sqlite_master table so that SQLite will
-know where to look for the appropriate b-tree.
-</p>
-
-<p>
-SQLite users can query the sqlite_master table just like any other table
-in the database. But the sqlite_master table cannot be directly written.
-The sqlite_master table is automatically updated in response to CREATE
-and DROP statements but it cannot be changed using INSERT, UPDATE, or
-DELETE statements as that would risk corrupting the database.
-</p>
-
-<p>
-SQLite stores temporary tables and indices in a separate
-file from the main database file. The temporary table database file
-is the same structure as the main database file. The schema table
-for the temporary tables is stored on page 2 just as in the main
-database. But the schema table for the temporary database named
-"sqlite_temp_master" instead of "sqlite_master". Other than the
-name change, it works exactly the same.
-</p>
-
-<h4>4.4 Schema Version Numbering And Other Meta-Information</h4>
-
-<p>
-The nine 32-bit integers that are stored beginning at byte offset
-60 of Page 1 in the b-tree layer are passed up into the schema layer
-and used for versioning and configuration information. The meaning
-of the first four integers is shown below. The other five are currently
-unused.
-</p>
-
-<ol>
-<li>The schema version number</li>
-<li>The format version number</li>
-<li>The recommended pager cache size</li>
-<li>The safety level</li>
-</ol>
-
-<p>
-The first meta-value, the schema version number, is used to detect when
-the schema of the database is changed by a CREATE or DROP statement.
-Recall that when a database is first opened the sqlite_master table is
-scanned and an internal representation of the tables, indices, views,
-and triggers for the database is built in memory. This internal
-representation is used for all subsequent SQL command parsing and
-execution. But what if another process were to change the schema
-by adding or removing a table, index, view, or trigger? If the original
-process were to continue using the old schema, it could potentially
-corrupt the database by writing to a table that no longer exists.
-To avoid this problem, the schema version number is changed whenever
-a CREATE or DROP statement is executed. Before each command is
-executed, the current schema version number for the database file
-is compared against the schema version number from when the sqlite_master
-table was last read. If those numbers are different, the internal
-schema representation is erased and the sqlite_master table is reread
-to reconstruct the internal schema representation.
-(Calls to sqlite_exec() generally return SQLITE_SCHEMA when this happens.)
-</p>
-
-<p>
-The second meta-value is the schema format version number. This
-number tells what version of the schema layer should be used to
-interpret the file. There have been changes to the schema layer
-over time and this number is used to detect when an older database
-file is being processed by a newer version of the library.
-As of this writing (SQLite version 2.7.0) the current format version
-is "4".
-</p>
-
-<p>
-The third meta-value is the recommended pager cache size as set
-by the DEFAULT_CACHE_SIZE pragma. If the value is positive it
-means that synchronous behavior is enable (via the DEFAULT_SYNCHRONOUS
-pragma) and if negative it means that synchronous behavior is
-disabled.
-</p>
-
-<p>
-The fourth meta-value is safety level added in version 2.8.0.
-A value of 1 corresponds to a SYNCHRONOUS setting of OFF. In other
-words, SQLite does not pause to wait for journal data to reach the disk
-surface before overwriting pages of the database. A value of 2 corresponds
-to a SYNCHRONOUS setting of NORMAL. A value of 3 corresponds to a
-SYNCHRONOUS setting of FULL. If the value is 0, that means it has not
-been initialized so the default synchronous setting of NORMAL is used.
-</p>
-}
-footer $rcsid
+++ /dev/null
-#
-# Run this Tcl script to generate the formatchng.html file.
-#
-set rcsid {$Id: formatchng.tcl,v 1.20 2007/09/03 20:32:45 drh Exp $ }
-source common.tcl
-header {File Format Changes in SQLite}
-puts {
-<h2>File Format Changes in SQLite</h2>
-
-<p>
-Every effort is made to keep SQLite fully backwards compatible from
-one release to the next. Rarely, however, some
-enhancements or bug fixes may require a change to
-the underlying file format. When this happens and you
-must convert the contents of your
-databases into a portable ASCII representation using the old version
-of the library then reload the data using the new version of the
-library.
-</p>
-
-<p>
-You can tell if you should reload your databases by comparing the
-version numbers of the old and new libraries. If the first digit
-of the version number is different, then a reload of the database will
-be required. If the second digit changes, newer versions of SQLite
-will be able to read and write older database files, but older versions
-of the library may have difficulty reading or writing newer database
-files.
-For example, upgrading from
-version 2.8.14 to 3.0.0 requires a reload. Going from
-version 3.0.8 to 3.1.0 is backwards compatible but not necessarily
-forwards compatible.
-</p>
-
-<p>
-The following table summarizes the SQLite file format changes that have
-occurred since version 1.0.0:
-</p>
-
-<blockquote>
-<table border=2 cellpadding=5>
-<tr>
- <th>Version Change</th>
- <th>Approx. Date</th>
- <th>Description Of File Format Change</th>
-</tr>
-<tr>
- <td valign="top">1.0.32 to 2.0.0</td>
- <td valign="top">2001-Sep-20</td>
- <td>Version 1.0.X of SQLite used the GDBM library as its backend
- interface to the disk. Beginning in version 2.0.0, GDBM was replaced
- by a custom B-Tree library written especially for SQLite. The new
- B-Tree backend is twice as fast as GDBM, supports atomic commits and
- rollback, and stores an entire database in a single disk file instead
- using a separate file for each table as GDBM does. The two
- file formats are not even remotely similar.</td>
-</tr>
-<tr>
- <td valign="top">2.0.8 to 2.1.0</td>
- <td valign="top">2001-Nov-12</td>
- <td>The same basic B-Tree format is used but the details of the
- index keys were changed in order to provide better query
- optimization opportunities. Some of the headers were also changed in order
- to increase the maximum size of a row from 64KB to 24MB.<p>
-
- This change is an exception to the version number rule described above
- in that it is neither forwards or backwards compatible. A complete
- reload of the database is required. This is the only exception.</td>
-</tr>
-<tr>
- <td valign="top">2.1.7 to 2.2.0</td>
- <td valign="top">2001-Dec-21</td>
- <td>Beginning with version 2.2.0, SQLite no longer builds an index for
- an INTEGER PRIMARY KEY column. Instead, it uses that column as the actual
- B-Tree key for the main table.<p>Version 2.2.0 and later of the library
- will automatically detect when it is reading a 2.1.x database and will
- disable the new INTEGER PRIMARY KEY feature. In other words, version
- 2.2.x is backwards compatible to version 2.1.x. But version 2.1.x is not
- forward compatible with version 2.2.x. If you try to open
- a 2.2.x database with an older 2.1.x library and that database contains
- an INTEGER PRIMARY KEY, you will likely get a coredump. If the database
- schema does not contain any INTEGER PRIMARY KEYs, then the version 2.1.x
- and version 2.2.x database files will be identical and completely
- interchangeable.</p>
-</tr>
-<tr>
- <td valign="top">2.2.5 to 2.3.0</td>
- <td valign="top">2002-Jan-30</td>
- <td>Beginning with version 2.3.0, SQLite supports some additional syntax
- (the "ON CONFLICT" clause) in the CREATE TABLE and CREATE INDEX statements
- that are stored in the SQLITE_MASTER table. If you create a database that
- contains this new syntax, then try to read that database using version 2.2.5
- or earlier, the parser will not understand the new syntax and you will get
- an error. Otherwise, databases for 2.2.x and 2.3.x are interchangeable.</td>
-</tr>
-<tr>
- <td valign="top">2.3.3 to 2.4.0</td>
- <td valign="top">2002-Mar-10</td>
- <td>Beginning with version 2.4.0, SQLite added support for views.
- Information about views is stored in the SQLITE_MASTER table. If an older
- version of SQLite attempts to read a database that contains VIEW information
- in the SQLITE_MASTER table, the parser will not understand the new syntax
- and initialization will fail. Also, the
- way SQLite keeps track of unused disk blocks in the database file
- changed slightly.
- If an older version of SQLite attempts to write a database that
- was previously written by version 2.4.0 or later, then it may leak disk
- blocks.</td>
-</tr>
-<tr>
- <td valign="top">2.4.12 to 2.5.0</td>
- <td valign="top">2002-Jun-17</td>
- <td>Beginning with version 2.5.0, SQLite added support for triggers.
- Information about triggers is stored in the SQLITE_MASTER table. If an older
- version of SQLite attempts to read a database that contains a CREATE TRIGGER
- in the SQLITE_MASTER table, the parser will not understand the new syntax
- and initialization will fail.
- </td>
-</tr>
-<tr>
- <td valign="top">2.5.6 to 2.6.0</td>
- <td valign="top">2002-July-17</td>
- <td>A design flaw in the layout of indices required a file format change
- to correct. This change appeared in version 2.6.0.<p>
-
- If you use version 2.6.0 or later of the library to open a database file
- that was originally created by version 2.5.6 or earlier, an attempt to
- rebuild the database into the new format will occur automatically.
- This can take some time for a large database. (Allow 1 or 2 seconds
- per megabyte of database under Unix - longer under Windows.) This format
- conversion is irreversible. It is <strong>strongly</strong> suggested
- that you make a backup copy of older database files prior to opening them
- with version 2.6.0 or later of the library, in case there are errors in
- the format conversion logic.<p>
-
- Version 2.6.0 or later of the library cannot open read-only database
- files from version 2.5.6 or earlier, since read-only files cannot be
- upgraded to the new format.</p>
- </td>
-</tr>
-<tr>
- <td valign="top">2.6.3 to 2.7.0</td>
- <td valign="top">2002-Aug-13</td>
- <td><p>Beginning with version 2.7.0, SQLite understands two different
- datatypes: text and numeric. Text data sorts in memcmp() order.
- Numeric data sorts in numerical order if it looks like a number,
- or in memcmp() order if it does not.</p>
-
- <p>When SQLite version 2.7.0 or later opens a 2.6.3 or earlier database,
- it assumes all columns of all tables have type "numeric". For 2.7.0
- and later databases, columns have type "text" if their datatype
- string contains the substrings "char" or "clob" or "blob" or "text".
- Otherwise they are of type "numeric".</p>
-
- <p>Because "text" columns have a different sort order from numeric,
- indices on "text" columns occur in a different order for version
- 2.7.0 and later database. Hence version 2.6.3 and earlier of SQLite
- will be unable to read a 2.7.0 or later database. But version 2.7.0
- and later of SQLite will read earlier databases.</p>
- </td>
-</tr>
-<tr>
- <td valign="top">2.7.6 to 2.8.0</td>
- <td valign="top">2003-Feb-14</td>
- <td><p>Version 2.8.0 introduces a change to the format of the rollback
- journal file. The main database file format is unchanged. Versions
- 2.7.6 and earlier can read and write 2.8.0 databases and vice versa.
- Version 2.8.0 can rollback a transaction that was started by version
- 2.7.6 and earlier. But version 2.7.6 and earlier cannot rollback a
- transaction started by version 2.8.0 or later.</p>
-
- <p>The only time this would ever be an issue is when you have a program
- using version 2.8.0 or later that crashes with an incomplete
- transaction, then you try to examine the database using version 2.7.6 or
- earlier. The 2.7.6 code will not be able to read the journal file
- and thus will not be able to rollback the incomplete transaction
- to restore the database.</p>
- </td>
-</tr>
-<tr>
- <td valign="top">2.8.14 to 3.0.0</td>
- <td valign="top">2004-Jun-18</td>
- <td><p>Version 3.0.0 is a major upgrade for SQLite that incorporates
- support for UTF-16, BLOBs, and a more compact encoding that results
- in database files that are typically 25% to 50% smaller. The new file
- format is very different and is completely incompatible with the
- version 2 file format.</p>
- </td>
-</tr>
-<tr>
- <td valign="top">3.0.8 to 3.1.0</td>
- <td valign="top">2005-Jan-21</td>
- <td><p>Version 3.1.0 adds support for
- <a href="pragma.html#pragma_auto_vacuum">autovacuum mode</a>.
- Prior versions of SQLite will be able to read an autovacuumed
- database but will not be able to write it. If autovaccum is disabled
- (which is the default condition)
- then databases are fully forwards and backwards compatible.</p>
- </td>
-</tr>
-<tr>
- <td valign="top">3.1.6 to 3.2.0</td>
- <td valign="top">2005-Mar-19</td>
- <td><p>Version 3.2.0 adds support for the
- <a href="lang_altertable.html">ALTER TABLE ADD COLUMN</a>
- command. A database that has been modified by this command can
- not be read by a version of SQLite prior to 3.1.4. Running
- <a href="lang_vacuum.html">VACUUM</a>
- after the ALTER TABLE
- restores the database to a format such that it can be read by earlier
- SQLite versions.</p>
- </td>
-</tr>
-<tr>
- <td valign="top">3.2.8 to 3.3.0</td>
- <td valign="top">2006-Jan-10</td>
- <td><p>Version 3.3.0 adds support for descending indices and
- uses a new encoding for boolean values that requires
- less disk space. Version 3.3.0 can read and write database
- files created by prior versions of SQLite. But prior versions
- of SQLite will not be able to read or write databases created
- by Version 3.3.0</p>
- <p>If you need backwards and forwards capatibility, you can
- compile with -DSQLITE_DEFAULT_FILE_FORMAT=1. Or at runtime
- you can say "PRAGMA legacy_file_format=ON" prior to creating
- a new database file</p>
- <p>Once a database file is created, its format is fixed. So
- a database file created by SQLite 3.2.8 and merely modified
- by version 3.3.0 or later will retain the old format. Except,
- the VACUUM command recreates the database so running VACUUM
- on 3.3.0 or later will change the file format to the latest
- edition.</p>
- </td>
-</tr>
-<tr>
- <td valign="top">3.3.6 to 3.3.7</td>
- <td valign="top">2006-Aug-12</td>
- <td><p>The previous file format change has caused so much
- grief that the default behavior has been changed back to
- the original file format. This means that DESC option on
- indices is ignored by default that the more efficient encoding
- of boolean values is not used. In that way, older versions
- of SQLite can read and write databases created by newer
- versions. If the new features are desired, they can be
- enabled using pragma: "PRAGMA legacy_file_format=OFF".</p>
- <p>To be clear: both old and new file formats continue to
- be understood and continue to work. But the old file format
- is used by default instead of the new. This might change
- again in some future release - we may go back to generating
- the new file format by default - but probably not until
- all users have upgraded to a version of SQLite that will
- understand the new file format. That might take several
- years.</p></td>
-</tr>
-<tr>
- <td valign="top">3.4.2 to 3.5.0</td>
- <td valign="top">2007-Sep-3</td>
- <td><p>The design of the OS interface layer was changed for
- release 3.5.0. Applications that implemented a custom OS
- interface will need to be modified in order to upgrade.
- There are also some subtly different semantics a few obscure
- APIs. An <a href="34to35.html">article</a> is avilable which
- describing the changes in detail.</p>
-
- <p>The on-disk file format is unchanged.</p>
- </td>
-</tr>
-</table>
-</blockquote>
-
-<p>
-To perform a database reload, have ready versions of the
-<b>sqlite</b> command-line utility for both the old and new
-version of SQLite. Call these two executables "<b>sqlite-old</b>"
-and "<b>sqlite-new</b>". Suppose the name of your old database
-is "<b>old.db</b>" and you want to create a new database with
-the same information named "<b>new.db</b>". The command to do
-this is as follows:
-</p>
-
-<blockquote>
- sqlite-old old.db .dump | sqlite-new new.db
-</blockquote>
-}
-footer $rcsid
+++ /dev/null
-#!/usr/bin/tclsh
-source common.tcl
-header {SQLite home page}
-puts {
-<table width="100%" border="0" cellspacing="5">
-<tr>
-<td width="50%" valign="top">
-<h2>About SQLite</h2>
-<p>
- <table align="right" border="0"><tr><td>
- <a href="http://osdir.com/Article6677.phtml">
- <img src="2005osaward.gif"></a>
- </td></tr></table>
-SQLite is a small
-C library that implements a self-contained, embeddable,
-zero-configuration
-SQL database engine.
-Features include:
-</p>
-
-<p><ul>
-<li>Transactions are atomic, consistent, isolated, and durable (ACID)
- even after system crashes and power failures.
-<li>Zero-configuration - no setup or administration needed.</li>
-<li>Implements most of SQL92.
- (<a href="omitted.html">Features not supported</a>)</li>
-<li>A complete database is stored in a single disk file.</li>
-<li>Database files can be freely shared between machines with
- different byte orders.</li>
-<li>Supports terabyte-sized databases and gigabyte-sized strings
- and blobs. (See <a href="limits.html">limits.html</a>.)
-<li>Small code footprint:
- <a href="http://www.sqlite.org/cvstrac/wiki?p=SizeOfSqlite">
- less than 250KiB</a> fully configured or less
- than 150KiB with optional features omitted.</li>
-<li><a href="speed.html">Faster</a> than popular client/server database
- engines for most common operations.</li>
-<li>Simple, easy to use <a href="capi3.html">API</a>.</li>
-<li><a href="tclsqlite.html">TCL bindings</a> included.
- Bindings for many other languages
- <a href="http://www.sqlite.org/cvstrac/wiki?p=SqliteWrappers">
- available separately.</a></li>
-<li>Well-commented source code with over 98% test coverage.</li>
-<li>Available as a
- <a href="http://www.sqlite.org/cvstrac/wiki?p=TheAmalgamation">
- single ANSI-C source-code file</a> that you can easily drop into
- another project.
-<li>Self-contained: no external dependencies.</li>
-<li>Sources are in the <a href="copyright.html">public domain</a>.
- Use for any purpose.</li>
-</ul>
-</p>
-
-<p>
-The SQLite distribution comes with a standalone command-line
-access program (<a href="sqlite.html">sqlite</a>) that can
-be used to administer an SQLite database and which serves as
-an example of how to use the SQLite library.
-</p>
-
-</td>
-<td width="1" bgcolor="#80a796"></td>
-<td valign="top" width="50%">
-<h2>News</h2>
-}
-
-proc newsitem {date title text} {
- puts "<h3>$date - $title</h3>"
- regsub -all "\n( *\n)+" $text "</p>\n\n<p>" txt
- puts "<p>$txt</p>"
- puts "<hr width=\"50%\">"
-}
-
-newsitem {2007-Nov-05} {Version 3.5.2} {
- This is an incremental release that fixes several minor problems,
- adds some obscure features, and provides some performance tweaks.
- Upgrading is optional.
-
- The experimental compile-time option
- SQLITE_OMIT_MEMORY_ALLOCATION is no longer supported. On the other
- hand, it is now possible to compile SQLite so that it uses a static
- array for all its dynamic memory allocation needs and never calls
- malloc. Expect to see additional radical changes to the memory
- allocation subsystem in future releases.
-}
-
-newsitem {2007-Oct-04} {Version 3.5.1} {
- Fix a long-standing bug that might cause database corruption if a
- disk-full error occurs in the middle of a transaction and that
- transaction is not rolled back.
- <a href="http://www.sqlite.org/cvstrac/tktview?tn=2686">Ticket #2686.</a>
-
- The new VFS layer is stable. However, we still reserve the right to
- make tweaks to the interface definition of the VFS if necessary.
-}
-
-newsitem {2007-Sep-04} {Version 3.5.0 alpha} {
- The OS interface layer and the memory allocation subsystems in
- SQLite have been reimplemented. The published API is largely unchanged
- but the (unpublished) OS interface has been modified extensively.
- Applications that implement their own OS interface will require
- modification. See
- <a href="34to35.html">34to35.html</a> for details.<p>
-
- This is a large change. Approximately 10% of the source code was
- modified. We are calling this first release "alpha" in order to give
- the user community time to test and evaluate the changes before we
- freeze the new design.
-}
-
-puts {
-<p align="right"><a href="oldnews.html">Old news...</a></p>
-</td></tr></table>
-}
-footer {$Id: index.tcl,v 1.165 2007/11/05 18:11:18 drh Exp $}
+++ /dev/null
-#
-# Run this Tcl script to generate the lang-*.html files.
-#
-set rcsid {$Id: lang.tcl,v 1.137 2007/10/12 19:11:55 drh Exp $}
-source common.tcl
-
-if {[llength $argv]>0} {
- set outputdir [lindex $argv 0]
-} else {
- set outputdir ""
-}
-
-header {Query Language Understood by SQLite}
-puts {
-<h1 class="pdf_section">SQL As Understood By SQLite</h1>
-
-<p>The SQLite library understands most of the standard SQL
-language. But it does <a href="omitted.html">omit some features</a>
-while at the same time
-adding a few features of its own. This document attempts to
-describe precisely what parts of the SQL language SQLite does
-and does not support. A list of <a href="lang_keywords.html">keywords</a> is
-also provided.</p>
-
-<p>In all of the syntax diagrams that follow, literal text is shown in
-bold blue. Non-terminal symbols are shown in italic red. Operators
-that are part of the syntactic markup itself are shown in black roman.</p>
-
-<p>This document is just an overview of the SQL syntax implemented
-by SQLite. Many low-level productions are omitted. For detailed information
-on the language that SQLite understands, refer to the source code and
-the grammar file "parse.y".</p>
-
-<div class="pdf_ignore">
-<p>SQLite implements the follow syntax:</p>
-<p><ul>
-}
-
-proc slink {label} {
- if {[string match *.html $label]} {
- return $label
- }
- if {[string length $::outputdir]==0} {
- return #$label
- } else {
- return lang_$label.html
- }
-}
-
-foreach {section} [lsort -index 0 -dictionary {
- {{CREATE TABLE} createtable}
- {{CREATE VIRTUAL TABLE} createvtab}
- {{CREATE INDEX} createindex}
- {VACUUM vacuum}
- {{DROP TABLE} droptable}
- {{DROP INDEX} dropindex}
- {INSERT insert}
- {REPLACE replace}
- {DELETE delete}
- {UPDATE update}
- {SELECT select}
- {comment comment}
- {COPY copy}
- {EXPLAIN explain}
- {expression expr}
- {{BEGIN TRANSACTION} transaction}
- {{COMMIT TRANSACTION} transaction}
- {{END TRANSACTION} transaction}
- {{ROLLBACK TRANSACTION} transaction}
- {PRAGMA pragma.html}
- {{ON CONFLICT clause} conflict}
- {{CREATE VIEW} createview}
- {{DROP VIEW} dropview}
- {{CREATE TRIGGER} createtrigger}
- {{DROP TRIGGER} droptrigger}
- {{ATTACH DATABASE} attach}
- {{DETACH DATABASE} detach}
- {REINDEX reindex}
- {{ALTER TABLE} altertable}
- {{ANALYZE} analyze}
-}] {
- foreach {s_title s_tag} $section {}
- puts "<li><a href=\"[slink $s_tag]\">$s_title</a></li>"
-}
-puts {</ul></p>
-</div>
-
-<p>Details on the implementation of each command are provided in
-the sequel.</p>
-}
-
-proc Operator {name} {
- return "<font color=\"#2c2cf0\"><big>$name</big></font>"
-}
-proc Nonterminal {name} {
- return "<i><font color=\"#ff3434\">$name</font></i>"
-}
-proc Keyword {name} {
- return "<font color=\"#2c2cf0\">$name</font>"
-}
-proc Example {text} {
- puts "<blockquote><pre>$text</pre></blockquote>"
-}
-
-proc Section {name label} {
- global outputdir
-
- if {[string length $outputdir]!=0} {
- if {[llength [info commands puts_standard]]>0} {
- footer $::rcsid
- }
-
- if {[string length $label]>0} {
- rename puts puts_standard
- proc puts {str} {
- regsub -all {href="#([a-z]+)"} $str {href="lang_\1.html"} str
- puts_standard $::section_file $str
- }
- rename footer footer_standard
- proc footer {id} {
- footer_standard $id
- rename footer ""
- rename puts ""
- rename puts_standard puts
- rename footer_standard footer
- }
- set ::section_file [open [file join $outputdir lang_$label.html] w]
- header "Query Language Understood by SQLite: $name"
- puts "<h1>SQL As Understood By SQLite</h1>"
- puts "<a href=\"lang.html\">\[Contents\]</a>"
- puts "<h2>$name</h2>"
- return
- }
- }
- puts "\n<hr />"
- if {$label!=""} {
- puts "<a name=\"$label\"></a>"
- }
- puts "<h1>$name</h1>\n"
-}
-
-Section {ALTER TABLE} altertable
-
-Syntax {sql-statement} {
-ALTER TABLE [<database-name> .] <table-name> <alteration>
-} {alteration} {
-RENAME TO <new-table-name>
-} {alteration} {
-ADD [COLUMN] <column-def>
-}
-
-puts {
-<p>SQLite's version of the ALTER TABLE command allows the user to
-rename or add a new column to an existing table. It is not possible
-to remove a column from a table.
-</p>
-
-<p>The RENAME TO syntax is used to rename the table identified by
-<i>[database-name.]table-name</i> to <i>new-table-name</i>. This command
-cannot be used to move a table between attached databases, only to rename
-a table within the same database.</p>
-
-<p>If the table being renamed has triggers or indices, then these remain
-attached to the table after it has been renamed. However, if there are
-any view definitions, or statements executed by triggers that refer to
-the table being renamed, these are not automatically modified to use the new
-table name. If this is required, the triggers or view definitions must be
-dropped and recreated to use the new table name by hand.
-</p>
-
-<p>The ADD [COLUMN] syntax is used to add a new column to an existing table.
-The new column is always appended to the end of the list of existing columns.
-<i>Column-def</i> may take any of the forms permissable in a CREATE TABLE
-statement, with the following restrictions:
-<ul>
-<li>The column may not have a PRIMARY KEY or UNIQUE constraint.</li>
-<li>The column may not have a default value of CURRENT_TIME, CURRENT_DATE
- or CURRENT_TIMESTAMP.</li>
-<li>If a NOT NULL constraint is specified, then the column must have a
- default value other than NULL.
-</ul>
-
-<p>The execution time of the ALTER TABLE command is independent of
-the amount of data in the table. The ALTER TABLE command runs as quickly
-on a table with 10 million rows as it does on a table with 1 row.
-</p>
-
-<p>After ADD COLUMN has been run on a database, that database will not
-be readable by SQLite version 3.1.3 and earlier until the database
-is <a href="lang_vacuum.html">VACUUM</a>ed.</p>
-}
-
-Section {ANALYZE} analyze
-
-Syntax {sql-statement} {
- ANALYZE
-}
-Syntax {sql-statement} {
- ANALYZE <database-name>
-}
-Syntax {sql-statement} {
- ANALYZE [<database-name> .] <table-name>
-}
-
-puts {
-<p>The ANALYZE command gathers statistics about indices and stores them
-in a special tables in the database where the query optimizer can use
-them to help make better index choices.
-If no arguments are given, all indices in all attached databases are
-analyzed. If a database name is given as the argument, all indices
-in that one database are analyzed. If the argument is a table name,
-then only indices associated with that one table are analyzed.</p>
-
-<p>The initial implementation stores all statistics in a single
-table named <b>sqlite_stat1</b>. Future enhancements may create
-additional tables with the same name pattern except with the "1"
-changed to a different digit. The <b>sqlite_stat1</b> table cannot
-be <a href="#droptable">DROP</a>ped,
-but all the content can be <a href="#delete">DELETE</a>d which has the
-same effect.</p>
-}
-
-Section {ATTACH DATABASE} attach
-
-Syntax {sql-statement} {
-ATTACH [DATABASE] <database-filename> AS <database-name>
-}
-
-puts {
-<p>The ATTACH DATABASE statement adds another database
-file to the current database connection. If the filename contains
-punctuation characters it must be quoted. The names 'main' and
-'temp' refer to the main database and the database used for
-temporary tables. These cannot be detached. Attached databases
-are removed using the <a href="#detach">DETACH DATABASE</a>
-statement.</p>
-
-<p>You can read from and write to an attached database and you
-can modify the schema of the attached database. This is a new
-feature of SQLite version 3.0. In SQLite 2.8, schema changes
-to attached databases were not allowed.</p>
-
-<p>You cannot create a new table with the same name as a table in
-an attached database, but you can attach a database which contains
-tables whose names are duplicates of tables in the main database. It is
-also permissible to attach the same database file multiple times.</p>
-
-<p>Tables in an attached database can be referred to using the syntax
-<i>database-name.table-name</i>. If an attached table doesn't have
-a duplicate table name in the main database, it doesn't require a
-database name prefix. When a database is attached, all of its
-tables which don't have duplicate names become the default table
-of that name. Any tables of that name attached afterwards require the table
-prefix. If the default table of a given name is detached, then
-the last table of that name attached becomes the new default.</p>
-
-<p>
-Transactions involving multiple attached databases are atomic,
-assuming that the main database is not ":memory:". If the main
-database is ":memory:" then
-transactions continue to be atomic within each individual
-database file. But if the host computer crashes in the middle
-of a COMMIT where two or more database files are updated,
-some of those files might get the changes where others
-might not.
-Atomic commit of attached databases is a new feature of SQLite version 3.0.
-In SQLite version 2.8, all commits to attached databases behaved as if
-the main database were ":memory:".
-</p>
-
-<p>There is a compile-time limit of 10 attached database files.</p>
-}
-
-
-Section {BEGIN TRANSACTION} transaction
-
-Syntax {sql-statement} {
-BEGIN [ DEFERRED | IMMEDIATE | EXCLUSIVE ] [TRANSACTION [<name>]]
-}
-Syntax {sql-statement} {
-END [TRANSACTION [<name>]]
-}
-Syntax {sql-statement} {
-COMMIT [TRANSACTION [<name>]]
-}
-Syntax {sql-statement} {
-ROLLBACK [TRANSACTION [<name>]]
-}
-
-puts {
-
-<p>
-No changes can be made to the database except within a transaction.
-Any command that changes the database (basically, any SQL command
-other than SELECT) will automatically start a transaction if
-one is not already in effect. Automatically started transactions
-are committed at the conclusion of the command.
-</p>
-
-<p>
-Transactions can be started manually using the BEGIN
-command. Such transactions usually persist until the next
-COMMIT or ROLLBACK command. But a transaction will also
-ROLLBACK if the database is closed or if an error occurs
-and the ROLLBACK conflict resolution algorithm is specified.
-See the documentation on the <a href="#conflict">ON CONFLICT</a>
-clause for additional information about the ROLLBACK
-conflict resolution algorithm.
-</p>
-
-<p>
-END TRANSACTION is an alias for COMMIT.
-</p>
-
-<p>The optional transaction name is current ignored. SQLite
-does not recognize nested transactions at this time.
-However, future versions of SQLite may be enhanced to support nested
-transactions and the transaction name would then become significant.
-Application are advised not to use the transaction name in order
-to avoid future compatibility problems.</p>
-
-<p>
-Transactions can be deferred, immediate, or exclusive.
-The default transaction behavior is deferred.
-Deferred means that no locks are acquired
-on the database until the database is first accessed. Thus with a
-deferred transaction, the BEGIN statement itself does nothing. Locks
-are not acquired until the first read or write operation. The first read
-operation against a database creates a SHARED lock and the first
-write operation creates a RESERVED lock. Because the acquisition of
-locks is deferred until they are needed, it is possible that another
-thread or process could create a separate transaction and write to
-the database after the BEGIN on the current thread has executed.
-If the transaction is immediate, then RESERVED locks
-are acquired on all databases as soon as the BEGIN command is
-executed, without waiting for the
-database to be used. After a BEGIN IMMEDIATE, you are guaranteed that
-no other thread or process will be able to write to the database or
-do a BEGIN IMMEDIATE or BEGIN EXCLUSIVE. Other processes can continue
-to read from the database, however. An exclusive transaction causes
-EXCLUSIVE locks to be acquired on all databases. After a BEGIN
-EXCLUSIVE, you are guaranteed that no other thread or process will
-be able to read or write the database until the transaction is
-complete.
-</p>
-
-<p>
-A description of the meaning of SHARED, RESERVED, and EXCLUSIVE locks
-is available <a href="lockingv3.html">separately</a>.
-</p>
-
-<p>
-The COMMIT command does not actually perform a commit until all
-pending SQL commands finish. Thus if two or more SELECT statements
-are in the middle of processing and a COMMIT is executed, the commit
-will not actually occur until all SELECT statements finish.
-</p>
-
-<p>
-An attempt to execute COMMIT might result in an SQLITE_BUSY return code.
-This indicates that another thread or process had a read lock on the database
-that prevented the database from being updated. When COMMIT fails in this
-way, the transaction remains active and the COMMIT can be retried later
-after the reader has had a chance to clear.
-</p>
-
-<h3>Response To Errors Within A Transaction</h3>
-
-<p>If certain kinds of errors occur within a transaction, the
-transaction may or may not be rolled back automatically. The
-errors that cause the behavior include:</p>
-
-<ul>
-<li> SQLITE_FULL: database or disk full
-<li> SQLITE_IOERR: disk I/O error
-<li> SQLITE_BUSY: database in use by another process
-<li> SQLITE_NOMEM: out or memory
-<li> SQLITE_INTERRUPT: processing interrupted by user request
-</ul>
-
-<p>
-For all of these errors, SQLite attempts to undo just the one statement
-it was working on and leave changes from prior statements within the
-same transaction intact and continue with the transaction. However,
-depending on the statement being evaluated and the point at which the
-error occurs, it might be necessary for SQLite to rollback and
-cancel the transaction. An application can tell which
-course of action SQLite took by using the
-<a href="capi3ref.html#sqlite3_get_autocommit">sqlite3_get_autocommit()</a>
-C-language interface.</p>
-
-<p>It is recommended that applications respond to the errors
-listed above by explicitly issuing a ROLLBACK command. If the
-transaction has already been rolled back automatically
-by the error response, then the ROLLBACK command will fail with an
-error, but no harm is caused by this.</p>
-
-<p>Future versions of SQLite may extend the list of errors which
-might cause automatic transaction rollback. Future versions of
-SQLite might change the error response. In particular, we may
-choose to simplify the interface in future versions of SQLite by
-causing the errors above to force an unconditional rollback.</p>
-}
-
-
-Section comment comment
-
-Syntax {comment} {<SQL-comment> | <C-comment>
-} {SQL-comment} {-- <single-line>
-} {C-comment} {/STAR <multiple-lines> [STAR/]
-}
-
-puts {
-<p> Comments aren't SQL commands, but can occur in SQL queries. They are
-treated as whitespace by the parser. They can begin anywhere whitespace
-can be found, including inside expressions that span multiple lines.
-</p>
-
-<p> SQL comments only extend to the end of the current line.</p>
-
-<p> C comments can span any number of lines. If there is no terminating
-delimiter, they extend to the end of the input. This is not treated as
-an error. A new SQL statement can begin on a line after a multiline
-comment ends. C comments can be embedded anywhere whitespace can occur,
-including inside expressions, and in the middle of other SQL statements.
-C comments do not nest. SQL comments inside a C comment will be ignored.
-</p>
-}
-
-
-Section COPY copy
-
-Syntax {sql-statement} {
-COPY [ OR <conflict-algorithm> ] [<database-name> .] <table-name> FROM <filename>
-[ USING DELIMITERS <delim> ]
-}
-
-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
-data into a table. It is modeled after a similar command found
-in PostgreSQL. In fact, the SQLite COPY command is specifically
-designed to be able to read the output of the PostgreSQL dump
-utility <b>pg_dump</b> so that data can be easily transferred from
-PostgreSQL into SQLite.</p>
-
-<p>The table-name is the name of an existing table which is to
-be filled with data. The filename is a string or identifier that
-names a file from which data will be read. The filename can be
-the <b>STDIN</b> to read data from standard input.</p>
-
-<p>Each line of the input file is converted into a single record
-in the table. Columns are separated by tabs. If a tab occurs as
-data within a column, then that tab is preceded by a baskslash "\"
-character. A baskslash in the data appears as two backslashes in
-a row. The optional USING DELIMITERS clause can specify a delimiter
-other than tab.</p>
-
-<p>If a column consists of the character "\N", that column is filled
-with the value NULL.</p>
-
-<p>The optional conflict-clause allows the specification of an alternative
-constraint conflict resolution algorithm to use for this one command.
-See the section titled
-<a href="#conflict">ON CONFLICT</a> for additional information.</p>
-
-<p>When the input data source is STDIN, the input can be terminated
-by a line that contains only a baskslash and a dot:}
-puts "\"[Operator \\.]\".</p>"
-
-
-Section {CREATE INDEX} createindex
-
-Syntax {sql-statement} {
-CREATE [UNIQUE] INDEX [IF NOT EXISTS] [<database-name> .] <index-name>
-ON <table-name> ( <column-name> [, <column-name>]* )
-} {column-name} {
-<name> [ COLLATE <collation-name>] [ ASC | DESC ]
-}
-
-puts {
-<p>The CREATE INDEX command consists of the keywords "CREATE INDEX" followed
-by the name of the new index, the keyword "ON", the name of a previously
-created table that is to be indexed, and a parenthesized list of names of
-columns in the table that are used for the index key.
-Each column name can be followed by one of the "ASC" or "DESC" keywords
-to indicate sort order, but the sort order is ignored in the current
-implementation. Sorting is always done in ascending order.</p>
-
-<p>The COLLATE clause following each column name defines a collating
-sequence used for text entires in that column. The default collating
-sequence is the collating sequence defined for that column in the
-CREATE TABLE statement. Or if no collating sequence is otherwise defined,
-the built-in BINARY collating sequence is used.</p>
-
-<p>There are no arbitrary limits on the number of indices that can be
-attached to a single table, nor on the number of columns in an index.</p>
-
-<p>If the UNIQUE keyword appears between CREATE and INDEX then duplicate
-index entries are not allowed. Any attempt to insert a duplicate entry
-will result in an error.</p>
-
-<p>The exact text
-of each CREATE INDEX statement is stored in the <b>sqlite_master</b>
-or <b>sqlite_temp_master</b> table, depending on whether the table
-being indexed is temporary. Every time the database is opened,
-all CREATE INDEX statements
-are read from the <b>sqlite_master</b> table and used to regenerate
-SQLite's internal representation of the index layout.</p>
-
-<p>If the optional IF NOT EXISTS clause is present and another index
-with the same name aleady exists, then this command becomes a no-op.</p>
-
-<p>Indexes are removed with the <a href="#dropindex">DROP INDEX</a>
-command.</p>
-}
-
-
-Section {CREATE TABLE} {createtable}
-
-Syntax {sql-command} {
-CREATE [TEMP | TEMPORARY] TABLE [IF NOT EXISTS] [<database-name> .] <table-name> (
- <column-def> [, <column-def>]*
- [, <constraint>]*
-)
-} {sql-command} {
-CREATE [TEMP | TEMPORARY] TABLE [<database-name>.] <table-name> AS <select-statement>
-} {column-def} {
-<name> [<type>] [[CONSTRAINT <name>] <column-constraint>]*
-} {type} {
-<typename> |
-<typename> ( <number> ) |
-<typename> ( <number> , <number> )
-} {column-constraint} {
-NOT NULL [ <conflict-clause> ] |
-PRIMARY KEY [<sort-order>] [ <conflict-clause> ] [AUTOINCREMENT] |
-UNIQUE [ <conflict-clause> ] |
-CHECK ( <expr> ) |
-DEFAULT <value> |
-COLLATE <collation-name>
-} {constraint} {
-PRIMARY KEY ( <column-list> ) [ <conflict-clause> ] |
-UNIQUE ( <column-list> ) [ <conflict-clause> ] |
-CHECK ( <expr> )
-} {conflict-clause} {
-ON CONFLICT <conflict-algorithm>
-}
-
-puts {
-<p>A CREATE TABLE statement is basically the keywords "CREATE TABLE"
-followed by the name of a new table and a parenthesized list of column
-definitions and constraints. The table name can be either an identifier
-or a string. Tables names that begin with "<b>sqlite_</b>" are reserved
-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.
-The datatype for the column does not restrict what data may be put
-in that column.
-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 COLLATE clause specifies what text <a href="datatype3.html#collation">
-collating function</a> to use when comparing text entries for the column.
-The built-in BINARY collating function is used by default.
-<p>
-The DEFAULT constraint specifies a default value to use when doing an INSERT.
-The value may be NULL, a string constant or a number. Starting with version
-3.1.0, the default value may also be one of the special case-independant
-keywords CURRENT_TIME, CURRENT_DATE or CURRENT_TIMESTAMP. If the value is
-NULL, a string constant or number, it is literally inserted into the column
-whenever an INSERT statement that does not specify a value for the column is
-executed. If the value is CURRENT_TIME, CURRENT_DATE or CURRENT_TIMESTAMP, then
-the current UTC date and/or time is inserted into the columns. For
-CURRENT_TIME, the format is HH:MM:SS. For CURRENT_DATE, YYYY-MM-DD. The format
-for CURRENT_TIMESTAMP is "YYYY-MM-DD HH:MM:SS".
-</p>
-
-<p>Specifying a PRIMARY KEY normally just creates a UNIQUE index
-on the corresponding columns. However, if primary key is on a single column
-that has datatype INTEGER, then that column is used internally
-as the actual key of the B-Tree for the table. This means that the column
-may only hold unique integer values. (Except for this one case,
-SQLite ignores the datatype specification of columns and allows
-any kind of data to be put in a column regardless of its declared
-datatype.) If a table does not have an INTEGER PRIMARY KEY column,
-then the B-Tree key will be a automatically generated integer.
-<a name="rowid"> The
-B-Tree key for a row can always be accessed using one of the
-special names "<b>ROWID</b>", "<b>OID</b>", or "<b>_ROWID_</b>".
-This is true regardless of whether or not there is an INTEGER
-PRIMARY KEY. An INTEGER PRIMARY KEY column can also include the
-keyword AUTOINCREMENT. The AUTOINCREMENT keyword modified the way
-that B-Tree keys are automatically generated. Additional detail
-on automatic B-Tree key generation is available
-<a href="autoinc.html">separately</a>.</p>
-
-<p>According to the SQL standard, PRIMARY KEY should imply NOT NULL.
-Unfortunately, due to a long-standing coding oversight, this is not
-the case in SQLite. SQLite allows NULL values
-in a PRIMARY KEY column. We could change SQLite to conform to the
-standard (and we might do so in the future), but by the time the
-oversight was discovered, SQLite was in such wide use that we feared
-breaking legacy code if we fixed the problem. So for now we have
-chosen to contain allowing NULLs in PRIMARY KEY columns.
-Developers should be aware, however, that we may change SQLite to
-conform to the SQL standard in future and should design new programs
-accordingly.</p>
-
-<p>If the "TEMP" or "TEMPORARY" keyword occurs in between "CREATE"
-and "TABLE" then the table that is created is only visible
-within that same database connection
-and is automatically deleted when
-the database connection is closed. Any indices created on a temporary table
-are also temporary. Temporary tables and indices are stored in a
-separate file distinct from the main database file.</p>
-
-<p> If a <database-name> is specified, then the table is created in
-the named database. It is an error to specify both a <database-name>
-and the TEMP keyword, unless the <database-name> is "temp". If no
-database name is specified, and the TEMP keyword is not present,
-the table is created in the main database.</p>
-
-<p>The optional conflict-clause following each constraint
-allows the specification of an alternative default
-constraint conflict resolution algorithm for that constraint.
-The default is abort ABORT. Different constraints within the same
-table may have different default conflict resolution algorithms.
-If an COPY, INSERT, or UPDATE command specifies a different conflict
-resolution algorithm, then that algorithm is used in place of the
-default algorithm specified in the CREATE TABLE statement.
-See the section titled
-<a href="#conflict">ON CONFLICT</a> for additional information.</p>
-
-<p>CHECK constraints are supported as of version 3.3.0. Prior
-to version 3.3.0, CHECK constraints were parsed but not enforced.</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 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
-the names of the columns in the result.</p>
-
-<p>The exact text
-of each CREATE TABLE statement is stored in the <b>sqlite_master</b>
-table. Every time the database is opened, all CREATE TABLE statements
-are read from the <b>sqlite_master</b> table and used to regenerate
-SQLite's internal representation of the table layout.
-If the original command was a CREATE TABLE AS then then an equivalent
-CREATE TABLE statement is synthesized and store in <b>sqlite_master</b>
-in place of the original command.
-The text of CREATE TEMPORARY TABLE statements are stored in the
-<b>sqlite_temp_master</b> table.
-</p>
-
-<p>If the optional IF NOT EXISTS clause is present and another table
-with the same name aleady exists, then this command becomes a no-op.</p>
-
-<p>Tables are removed using the <a href="#droptable">DROP TABLE</a>
-statement. </p>
-}
-
-
-Section {CREATE TRIGGER} createtrigger
-
-Syntax {sql-statement} {
-CREATE [TEMP | TEMPORARY] TRIGGER [IF NOT EXISTS] <trigger-name> [ BEFORE | AFTER ]
-<database-event> ON [<database-name> .] <table-name>
-<trigger-action>
-}
-
-Syntax {sql-statement} {
-CREATE [TEMP | TEMPORARY] TRIGGER [IF NOT EXISTS] <trigger-name> INSTEAD OF
-<database-event> ON [<database-name> .] <view-name>
-<trigger-action>
-}
-
-Syntax {database-event} {
-DELETE |
-INSERT |
-UPDATE |
-UPDATE OF <column-list>
-}
-
-Syntax {trigger-action} {
-[ FOR EACH ROW ] [ WHEN <expression> ]
-BEGIN
- <trigger-step> ; [ <trigger-step> ; ]*
-END
-}
-
-Syntax {trigger-step} {
-<update-statement> | <insert-statement> |
-<delete-statement> | <select-statement>
-}
-
-puts {
-<p>The CREATE TRIGGER statement is used to add triggers to the
-database schema. Triggers are database operations (the <i>trigger-action</i>)
-that are automatically performed when a specified database event (the
-<i>database-event</i>) occurs. </p>
-
-<p>A trigger may be specified to fire whenever a DELETE, INSERT or UPDATE of a
-particular database table occurs, or whenever an UPDATE of one or more
-specified columns of a table are updated.</p>
-
-<p>At this time SQLite supports only FOR EACH ROW triggers, not FOR EACH
-STATEMENT triggers. Hence explicitly specifying FOR EACH ROW is optional. FOR
-EACH ROW implies that the SQL statements specified as <i>trigger-steps</i>
-may be executed (depending on the WHEN clause) for each database row being
-inserted, updated or deleted by the statement causing the trigger to fire.</p>
-
-<p>Both the WHEN clause and the <i>trigger-steps</i> may access elements of
-the row being inserted, deleted or updated using references of the form
-"NEW.<i>column-name</i>" and "OLD.<i>column-name</i>", where
-<i>column-name</i> is the name of a column from the table that the trigger
-is associated with. OLD and NEW references may only be used in triggers on
-<i>trigger-event</i>s for which they are relevant, as follows:</p>
-
-<table border=0 cellpadding=10>
-<tr>
-<td valign="top" align="right" width=120><i>INSERT</i></td>
-<td valign="top">NEW references are valid</td>
-</tr>
-<tr>
-<td valign="top" align="right" width=120><i>UPDATE</i></td>
-<td valign="top">NEW and OLD references are valid</td>
-</tr>
-<tr>
-<td valign="top" align="right" width=120><i>DELETE</i></td>
-<td valign="top">OLD references are valid</td>
-</tr>
-</table>
-</p>
-
-<p>If a WHEN clause is supplied, the SQL statements specified as <i>trigger-steps</i> are only executed for rows for which the WHEN clause is true. If no WHEN clause is supplied, the SQL statements are executed for all rows.</p>
-
-<p>The specified <i>trigger-time</i> determines when the <i>trigger-steps</i>
-will be executed relative to the insertion, modification or removal of the
-associated row.</p>
-
-<p>An ON CONFLICT clause may be specified as part of an UPDATE or INSERT
-<i>trigger-step</i>. However if an ON CONFLICT clause is specified as part of
-the statement causing the trigger to fire, then this conflict handling
-policy is used instead.</p>
-
-<p>Triggers are automatically dropped when the table that they are
-associated with is dropped.</p>
-
-<p>Triggers may be created on views, as well as ordinary tables, by specifying
-INSTEAD OF in the CREATE TRIGGER statement. If one or more ON INSERT, ON DELETE
-or ON UPDATE triggers are defined on a view, then it is not an error to execute
-an INSERT, DELETE or UPDATE statement on the view, respectively. Thereafter,
-executing an INSERT, DELETE or UPDATE on the view causes the associated
- triggers to fire. The real tables underlying the view are not modified
- (except possibly explicitly, by a trigger program).</p>
-
-<p><b>Example:</b></p>
-
-<p>Assuming that customer records are stored in the "customers" table, and
-that order records are stored in the "orders" table, the following trigger
-ensures that all associated orders are redirected when a customer changes
-his or her address:</p>
-}
-Example {
-CREATE TRIGGER update_customer_address UPDATE OF address ON customers
- BEGIN
- UPDATE orders SET address = new.address WHERE customer_name = old.name;
- END;
-}
-puts {
-<p>With this trigger installed, executing the statement:</p>
-}
-
-Example {
-UPDATE customers SET address = '1 Main St.' WHERE name = 'Jack Jones';
-}
-puts {
-<p>causes the following to be automatically executed:</p>
-}
-Example {
-UPDATE orders SET address = '1 Main St.' WHERE customer_name = 'Jack Jones';
-}
-
-puts {
-<p>Note that currently, triggers may behave oddly when created on tables
- with INTEGER PRIMARY KEY fields. If a BEFORE trigger program modifies the
- INTEGER PRIMARY KEY field of a row that will be subsequently updated by the
- statement that causes the trigger to fire, then the update may not occur.
- The workaround is to declare the table with a PRIMARY KEY column instead
- of an INTEGER PRIMARY KEY column.</p>
-}
-
-puts {
-<p>A special SQL function RAISE() may be used within a trigger-program, with the following syntax</p>
-}
-Syntax {raise-function} {
-RAISE ( ABORT, <error-message> ) |
-RAISE ( FAIL, <error-message> ) |
-RAISE ( ROLLBACK, <error-message> ) |
-RAISE ( IGNORE )
-}
-puts {
-<p>When one of the first three forms is called during trigger-program execution, the specified ON CONFLICT processing is performed (either ABORT, FAIL or
- ROLLBACK) and the current query terminates. An error code of SQLITE_CONSTRAINT is returned to the user, along with the specified error message.</p>
-
-<p>When RAISE(IGNORE) is called, the remainder of the current trigger program,
-the statement that caused the trigger program to execute and any subsequent
- trigger programs that would of been executed are abandoned. No database
- changes are rolled back. If the statement that caused the trigger program
- to execute is itself part of a trigger program, then that trigger program
- resumes execution at the beginning of the next step.
-</p>
-
-<p>Triggers are removed using the <a href="#droptrigger">DROP TRIGGER</a>
-statement.</p>
-}
-
-
-Section {CREATE VIEW} {createview}
-
-Syntax {sql-command} {
-CREATE [TEMP | TEMPORARY] VIEW [IF NOT EXISTS] [<database-name>.] <view-name> AS <select-statement>
-}
-
-puts {
-<p>The CREATE VIEW command assigns a name to a pre-packaged
-<a href="#select">SELECT</a>
-statement. Once the view is created, it can be used in the FROM clause
-of another SELECT in place of a table name.
-</p>
-
-<p>If the "TEMP" or "TEMPORARY" keyword occurs in between "CREATE"
-and "VIEW" then the view that is created is only visible to the
-process that opened the database and is automatically deleted when
-the database is closed.</p>
-
-<p> If a <database-name> is specified, then the view is created in
-the named database. It is an error to specify both a <database-name>
-and the TEMP keyword, unless the <database-name> is "temp". If no
-database name is specified, and the TEMP keyword is not present,
-the table is created in the main database.</p>
-
-<p>You cannot COPY, DELETE, INSERT or UPDATE a view. Views are read-only
-in SQLite. However, in many cases you can use a <a href="#createtrigger">
-TRIGGER</a> on the view to accomplish the same thing. Views are removed
-with the <a href="#dropview">DROP VIEW</a>
-command.</p>
-}
-
-Section {CREATE VIRTUAL TABLE} {createvtab}
-
-Syntax {sql-command} {
-CREATE VIRTUAL TABLE [<database-name> .] <table-name> USING <module-name> [( <arguments> )]
-}
-
-puts {
-<p>A virtual table is an interface to an external storage or computation
-engine that appears to be a table but does not actually store information
-in the database file.</p>
-
-<p>In general, you can do anything with a virtual table that can be done
-with an ordinary table, except that you cannot create triggers on a
-virtual table. Some virtual table implementations might impose additional
-restrictions. For example, many virtual tables are read-only.</p>
-
-<p>The <module-name> is the name of an object that implements
-the virtual table. The <module-name> must be registered with
-the SQLite database connection using
-<a href="capi3ref.html#sqlite3_create_module">sqlite3_create_module</a>
-prior to issuing the CREATE VIRTUAL TABLE statement.
-The module takes zero or more comma-separated arguments.
-The arguments can be just about any text as long as it has balanced
-parentheses. The argument syntax is sufficiently general that the
-arguments can be made to appear as column definitions in a traditional
-<a href="#createtable">CREATE TABLE</a> statement.
-SQLite passes the module arguments directly
-to the module without any interpretation. It is the responsibility
-of the module implementation to parse and interpret its own arguments.</p>
-
-<p>A virtual table is destroyed using the ordinary
-<a href="#droptable">DROP TABLE</a> statement. There is no
-DROP VIRTUAL TABLE statement.</p>
-}
-
-Section DELETE delete
-
-Syntax {sql-statement} {
-DELETE FROM [<database-name> .] <table-name> [WHERE <expr>]
-}
-
-puts {
-<p>The DELETE command is used to remove records from a table.
-The command consists of the "DELETE FROM" keywords followed by
-the name of the table from which records are to be removed.
-</p>
-
-<p>Without a WHERE clause, all rows of the table are removed.
-If a WHERE clause is supplied, then only those rows that match
-the expression are removed.</p>
-}
-
-
-Section {DETACH DATABASE} detach
-
-Syntax {sql-command} {
-DETACH [DATABASE] <database-name>
-}
-
-puts {
-<p>This statement detaches an additional database connection previously
-attached using the <a href="#attach">ATTACH DATABASE</a> statement. It
-is possible to have the same database file attached multiple times using
-different names, and detaching one connection to a file will leave the
-others intact.</p>
-
-<p>This statement will fail if SQLite is in the middle of a transaction.</p>
-}
-
-
-Section {DROP INDEX} dropindex
-
-Syntax {sql-command} {
-DROP INDEX [IF EXISTS] [<database-name> .] <index-name>
-}
-
-puts {
-<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.</p>
-
-<p>The DROP INDEX statement does not reduce the size of the database
-file in the default mode.
-Empty space in the database is retained for later INSERTs. To
-remove free space in the database, use the <a href="#vacuum">VACUUM</a>
-command. If AUTOVACUUM mode is enabled for a database then space
-will be freed automatically by DROP INDEX.</p>
-}
-
-
-Section {DROP TABLE} droptable
-
-Syntax {sql-command} {
-DROP TABLE [IF EXISTS] [<database-name>.] <table-name>
-}
-
-puts {
-<p>The DROP TABLE statement removes a table added with the <a href=
-"#createtable">CREATE TABLE</a> statement. The name specified is the
-table name. It is completely removed from the database schema and the
-disk file. The table can not be recovered. All indices associated
-with the table are also deleted.</p>
-
-<p>The DROP TABLE statement does not reduce the size of the database
-file in the default mode. Empty space in the database is retained for
-later INSERTs. To
-remove free space in the database, use the <a href="#vacuum">VACUUM</a>
-command. If AUTOVACUUM mode is enabled for a database then space
-will be freed automatically by DROP TABLE.</p>
-
-<p>The optional IF EXISTS clause suppresses the error that would normally
-result if the table does not exist.</p>
-}
-
-
-Section {DROP TRIGGER} droptrigger
-Syntax {sql-statement} {
-DROP TRIGGER [IF EXISTS] [<database-name> .] <trigger-name>
-}
-puts {
-<p>The DROP TRIGGER statement removes a trigger created by the
-<a href="#createtrigger">CREATE TRIGGER</a> statement. The trigger is
-deleted from the database schema. Note that triggers are automatically
-dropped when the associated table is dropped.</p>
-}
-
-
-Section {DROP VIEW} dropview
-
-Syntax {sql-command} {
-DROP VIEW [IF EXISTS] <view-name>
-}
-
-puts {
-<p>The DROP VIEW statement removes a view created by the <a href=
-"#createview">CREATE VIEW</a> statement. The name specified is the
-view name. It is removed from the database schema, but no actual data
-in the underlying base tables is modified.</p>
-}
-
-
-Section EXPLAIN explain
-
-Syntax {sql-statement} {
-EXPLAIN <sql-statement>
-}
-
-puts {
-<p>The EXPLAIN command modifier is a non-standard extension. The
-idea comes from a similar command found in PostgreSQL, but the operation
-is completely different.</p>
-
-<p>If the EXPLAIN keyword appears before any other SQLite SQL command
-then instead of actually executing the command, the SQLite library will
-report back the sequence of virtual machine instructions it would have
-used to execute the command had the EXPLAIN keyword not been present.
-For additional information about virtual machine instructions see
-the <a href="arch.html">architecture description</a> or the documentation
-on <a href="opcode.html">available opcodes</a> for the virtual machine.</p>
-}
-
-
-Section expression expr
-
-Syntax {expr} {
-<expr> <binary-op> <expr> |
-<expr> [NOT] <like-op> <expr> [ESCAPE <expr>] |
-<unary-op> <expr> |
-( <expr> ) |
-<column-name> |
-<table-name> . <column-name> |
-<database-name> . <table-name> . <column-name> |
-<literal-value> |
-<parameter> |
-<function-name> ( <expr-list> | STAR ) |
-<expr> ISNULL |
-<expr> NOTNULL |
-<expr> [NOT] BETWEEN <expr> AND <expr> |
-<expr> [NOT] IN ( <value-list> ) |
-<expr> [NOT] IN ( <select-statement> ) |
-<expr> [NOT] IN [<database-name> .] <table-name> |
-[EXISTS] ( <select-statement> ) |
-CASE [<expr>] LP WHEN <expr> THEN <expr> RPPLUS [ELSE <expr>] END |
-CAST ( <expr> AS <type> ) |
-<expr> COLLATE <collation-name>
-} {like-op} {
-LIKE | GLOB | REGEXP | MATCH
-}
-
-puts {
-<p>This section is different from the others. Most other sections of
-this document talks about a particular SQL command. This section does
-not talk about a standalone command but about "expressions" which are
-subcomponents of most other commands.</p>
-
-<p>SQLite understands the following binary operators, in order from
-highest to lowest precedence:</p>
-
-<blockquote><pre>
-<font color="#2c2cf0"><big>||
-* / %
-+ -
-<< >> & |
-< <= > >=
-= == != <> </big>IN
-AND
-OR</font>
-</pre></blockquote>
-
-<p>Supported unary prefix operators are these:</p>
-
-<blockquote><pre>
-<font color="#2c2cf0"><big>- + ! ~ NOT</big></font>
-</pre></blockquote>
-
-<p>The COLLATE operator can be thought of as a unary postfix
-operator. The COLLATE operator has the highest precedence.
-It always binds more tightly than any prefix unary operator or
-any binary operator.</p>
-
-<p>The unary operator [Operator +] is a no-op. It can be applied
-to strings, numbers, or blobs and it always gives as its result the
-value of the operand.</p>
-
-<p>Note that there are two variations of the equals and not equals
-operators. Equals can be either}
-puts "[Operator =] or [Operator ==].
-The non-equals operator can be either
-[Operator !=] or [Operator {<>}].
-The [Operator ||] operator is \"concatenate\" - it joins together
-the two strings of its operands.
-The operator [Operator %] outputs the remainder of its left
-operand modulo its right operand.</p>
-
-<p>The result of any binary operator is a numeric value, except
-for the [Operator ||] concatenation operator which gives a string
-result.</p>"
-
-puts {
-
-<a name="literal_value"></a>
-<p>
-A literal value is an integer number or a floating point number.
-Scientific notation is supported. The "." character is always used
-as the decimal point even if the locale setting specifies "," for
-this role - the use of "," for the decimal point would result in
-syntactic ambiguity. A string constant is formed by enclosing the
-string in single quotes ('). A single quote within the string can
-be encoded by putting two single quotes in a row - as in Pascal.
-C-style escapes using the backslash character are not supported because
-they are not standard SQL.
-BLOB literals are string literals containing hexadecimal data and
-preceded by a single "x" or "X" character. For example:</p>
-
-<blockquote><pre>
-X'53514C697465'
-</pre></blockquote>
-
-<p>
-A literal value can also be the token "NULL".
-</p>
-
-<p>
-A parameter specifies a placeholder in the expression for a literal
-value that is filled in at runtime using the
-<a href="capi3ref.html#sqlite3_bind_int">sqlite3_bind</a> API.
-Parameters can take several forms:
-</p
-
-<blockquote>
-<table class="pdf_functions">
-<tr>
-<td align="right" valign="top"><b>?</b><i>NNN</i></td><td width="20"></td>
-<td>A question mark followed by a number <i>NNN</i> holds a spot for the
-NNN-th parameter. NNN must be between 1 and 999.</td>
-</tr>
-<tr>
-<td align="right" valign="top"><b>?</b></td><td width="20"></td>
-<td>A question mark that is not followed by a number holds a spot for
-the next unused parameter.</td>
-</tr>
-<tr>
-<td align="right" valign="top"><b>:</b><i>AAAA</i></td><td width="20"></td>
-<td>A colon followed by an identifier name holds a spot for a named
-parameter with the name AAAA. Named parameters are also numbered.
-The number assigned is the next unused number. To avoid confusion,
-it is best to avoid mixing named and numbered parameters.</td>
-</tr>
-<tr>
-<td align="right" valign="top"><b>@</b><i>AAAA</i></td><td width="20"></td>
-<td>An "at" sign works exactly like a colon.</td>
-</tr>
-<tr>
-<td align="right" valign="top"><b>$</b><i>AAAA</i></td><td width="20"></td>
-<td>A dollar-sign followed by an identifier name also holds a spot for a named
-parameter with the name AAAA. The identifier name in this case can include
-one or more occurances of "::" and a suffix enclosed in "(...)" containing
-any text at all. This syntax is the form of a variable name in the Tcl
-programming language.</td>
-</tr>
-</table>
-</blockquote>
-
-<p>Parameters that are not assigned values using
-<a href="capi3ref.html#sqlite3_bind_int">sqlite3_bind</a> are treated
-as NULL.</p>
-
-<a name="like"></a>
-<p>The LIKE operator does a pattern matching comparison. The operand
-to the right contains the pattern, the left hand operand contains the
-string to match against the pattern.
-}
-puts "A percent symbol [Operator %] in the pattern matches any
-sequence of zero or more characters in the string. An underscore
-[Operator _] in the pattern matches any single character in the
-string. Any other character matches itself or it's lower/upper case
-equivalent (i.e. case-insensitive matching). (A bug: SQLite only
-understands upper/lower case for 7-bit Latin characters. Hence the
-LIKE operator is case sensitive for 8-bit iso8859 characters or UTF-8
-characters. For example, the expression <b>'a' LIKE 'A'</b>
-is TRUE but <b>'æ' LIKE 'Æ'</b> is FALSE.).</p>"
-
-puts {
-<p>If the optional ESCAPE clause is present, then the expression
-following the ESCAPE keyword must evaluate to a string consisting of
-a single character. This character may be used in the LIKE pattern
-to include literal percent or underscore characters. The escape
-character followed by a percent symbol, underscore or itself matches a
-literal percent symbol, underscore or escape character in the string,
-respectively. The infix LIKE operator is implemented by calling the
-user function <a href="#likeFunc"> like(<i>X</i>,<i>Y</i>)</a>.</p>
-}
-
-puts {
-The LIKE operator is not case sensitive and will match upper case
-characters on one side against lower case characters on the other.
-(A bug: SQLite only understands upper/lower case for 7-bit Latin
-characters. Hence the LIKE operator is case sensitive for 8-bit
-iso8859 characters or UTF-8 characters. For example, the expression
-<b>'a' LIKE 'A'</b> is TRUE but
-<b>'æ' LIKE 'Æ'</b> is FALSE.).</p>
-
-<p>The infix LIKE
-operator is implemented by calling the user function <a href="#likeFunc">
-like(<i>X</i>,<i>Y</i>)</a>. If an ESCAPE clause is present, it adds
-a third parameter to the function call. If the functionality of LIKE can be
-overridden by defining an alternative implementation of the
-like() SQL function.</p>
-</p>
-
-<a name="glob"></a>
-<p>The GLOB operator is similar to LIKE but uses the Unix
-file globbing syntax for its wildcards. Also, GLOB is case
-sensitive, unlike LIKE. Both GLOB and LIKE may be preceded by
-the NOT keyword to invert the sense of the test. The infix GLOB
-operator is implemented by calling the user function <a href="#globFunc">
-glob(<i>X</i>,<i>Y</i>)</a> and can be modified by overriding
-that function.</p>
-
-<a name="regexp"></a>
-<p>The REGEXP operator is a special syntax for the regexp()
-user function. No regexp() user function is defined by default
-and so use of the REGEXP operator will normally result in an
-error message. If a user-defined function named "regexp"
-is added at run-time, that function will be called in order
-to implement the REGEXP operator.</p>
-
-<a name="match"></a>
-<p>The MATCH operator is a special syntax for the match()
-user function. The default match() function implementation
-raises and exception and is not really useful for anything.
-But extensions can override the match() function with more
-helpful logic.</p>
-
-<p>A column name can be any of the names defined in the CREATE TABLE
-statement or one of the following special identifiers: "<b>ROWID</b>",
-"<b>OID</b>", or "<b>_ROWID_</b>".
-These special identifiers all describe the
-unique integer key (the "row key") associated with every
-row of every table.
-The special identifiers only refer to the row key if the CREATE TABLE
-statement does not define a real column with the same name. Row keys
-act like read-only columns. A row key can be used anywhere a regular
-column can be used, except that you cannot change the value
-of a row key in an UPDATE or INSERT statement.
-"SELECT * ..." does not return the row key.</p>
-
-<p>SELECT statements can appear in expressions as either the
-right-hand operand of the IN operator, as a scalar quantity, or
-as the operand of an EXISTS operator.
-As a scalar quantity or the operand of an IN operator,
-the SELECT should have only a single column in its
-result. Compound SELECTs (connected with keywords like UNION or
-EXCEPT) are allowed.
-With the EXISTS operator, the columns in the result set of the SELECT are
-ignored and the expression returns TRUE if one or more rows exist
-and FALSE if the result set is empty.
-If no terms in the SELECT expression refer to value in the containing
-query, then the expression is evaluated once prior to any other
-processing and the result is reused as necessary. If the SELECT expression
-does contain variables from the outer query, then the SELECT is reevaluated
-every time it is needed.</p>
-
-<p>When a SELECT is the right operand of the IN operator, the IN
-operator returns TRUE if the result of the left operand is any of
-the values generated by the select. The IN operator may be preceded
-by the NOT keyword to invert the sense of the test.</p>
-
-<p>When a SELECT appears within an expression but is not the right
-operand of an IN operator, then the first row of the result of the
-SELECT becomes the value used in the expression. If the SELECT yields
-more than one result row, all rows after the first are ignored. If
-the SELECT yields no rows, then the value of the SELECT is NULL.</p>
-
-<p>A CAST expression changes the datatype of the <expr> into the
-type specified by <type>.
-<type> can be any non-empty type name that is valid
-for the type in a column definition of a CREATE TABLE statement.</p>
-
-<p>Both simple and aggregate functions are supported. A simple
-function can be used in any expression. Simple functions return
-a result immediately based on their inputs. Aggregate functions
-may only be used in a SELECT statement. Aggregate functions compute
-their result across all rows of the result set.</p>
-
-<a name="corefunctions"></a>
-<b>Core Functions</b>
-
-<p>The core functions shown below are available by default. Additional
-functions may be written in C and added to the database engine using
-the <a href="capi3ref.html#cfunc">sqlite3_create_function()</a>
-API.</p>
-
-<table border=0 cellpadding=10 class="pdf_functions">
-<tr>
-<td valign="top" align="right" width=120>abs(<i>X</i>)</td>
-<td valign="top">Return the absolute value of argument <i>X</i>.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">coalesce(<i>X</i>,<i>Y</i>,...)</td>
-<td valign="top">Return a copy of the first non-NULL argument. If
-all arguments are NULL then NULL is returned. There must be at least
-2 arguments.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">
-<a name="globFunc"></a>
-glob(<i>X</i>,<i>Y</i>)</td>
-<td valign="top">This function is used to implement the
-"<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="#globFunc">GLOB</a> operator.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">ifnull(<i>X</i>,<i>Y</i>)</td>
-<td valign="top">Return a copy of the first non-NULL argument. If
-both arguments are NULL then NULL is returned. This behaves the same as
-<b>coalesce()</b> above.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">
-<a name="hexFunc">
-hex(<i>X</i>)</td>
-<td valign="top">The argument is interpreted as a BLOB. The result
-is a hexadecimal rendering of the content of that blob.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">last_insert_rowid()</td>
-<td valign="top">Return the <a href="lang_createtable.html#rowid">ROWID</a>
-of the last row insert from this
-connection to the database. This is the same value that would be returned
-from the <b>sqlite_last_insert_rowid()</b> API function.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">length(<i>X</i>)</td>
-<td valign="top">Return the string length of <i>X</i> in characters.
-If SQLite is configured to support UTF-8, then the number of UTF-8
-characters is returned, not the number of bytes.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">
-<a name="likeFunc"></a>
-like(<i>X</i>,<i>Y</i>)<br>
-like(<i>X</i>,<i>Y</i>,<i>Z</i>)</td>
-<td valign="top">
-This function is used to implement the "<b>X LIKE Y [ESCAPE Z]</b>"
-syntax of SQL. If the optional ESCAPE clause is present, then the
-user-function is invoked with three arguments. Otherwise, it is
-invoked with two arguments only. 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. When doing this, it may be important
-to override both the two and three argument versions of the like()
-function. Otherwise, different code may be called to implement the
-LIKE operator depending on whether or not an ESCAPE clause was
-specified.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">load_extension(<i>X</i>)<br>
-load_extension(<i>X</i>,<i>Y</i>)</td>
-<td valign="top">Load SQLite extensions out of the shared library
-file named <i>X</i> using the entry point <i>Y</i>. The result
-is a NULL. If <i>Y</i> is omitted then the default entry point
-of <b>sqlite3_extension_init</b> is used. This function raises
-an exception if the extension fails to load or initialize correctly.
-
-<p>This function will fail if the extension attempts to modify
-or delete a SQL function or collating sequence. The
-extension can add new functions or collating sequences, but cannot
-modify or delete existing functions or collating sequences because
-those functions and/or collating sequences might be used elsewhere
-in the currently running SQL statement. To load an extension that
-changes or deletes functions or collating sequences, use the
-<a href="capi3ref.html#sqlite3_load_extension">sqlite3_load_extension()</a>
-C-language API.</p>
-</tr>
-
-<tr>
-<td valign="top" align="right">lower(<i>X</i>)</td>
-<td valign="top">Return a copy of string <i>X</i> will all characters
-converted to lower case. The C library <b>tolower()</b> routine is used
-for the conversion, which means that this function might not
-work correctly on UTF-8 characters.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">
-<a name="ltrimFunc">
-ltrim(<i>X</i>)<br>ltrim(<i>X</i>,<i>Y</i>)</td>
-<td valign="top">Return a string formed by removing any and all
-characters that appear in <i>Y</i> from the left side of <i>X</i>.
-If the <i>Y</i> argument is omitted, spaces are removed.</td>
-</tr>
-
-
-<tr>
-<td valign="top" align="right">max(<i>X</i>,<i>Y</i>,...)</td>
-<td valign="top">Return the argument with the maximum value. Arguments
-may be strings in addition to numbers. The maximum value is determined
-by the usual sort order. Note that <b>max()</b> is a simple function when
-it has 2 or more arguments but converts to an aggregate function if given
-only a single argument.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">min(<i>X</i>,<i>Y</i>,...)</td>
-<td valign="top">Return the argument with the minimum value. Arguments
-may be strings in addition to numbers. The minimum value is determined
-by the usual sort order. Note that <b>min()</b> is a simple function when
-it has 2 or more arguments but converts to an aggregate function if given
-only a single argument.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">nullif(<i>X</i>,<i>Y</i>)</td>
-<td valign="top">Return the first argument if the arguments are different,
-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 pseudo-random integer
-between -9223372036854775808 and +9223372036854775807.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">
-<a name="replaceFunc">
-replace(<i>X</i>,<i>Y</i>,<i>Z</i>)</td>
-<td valign="top">Return a string formed by substituting string <i>Z</i> for
-every occurrance of string <i>Y</i> in string <i>X</i>. The BINARY
-collating sequence is used for comparisons.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">
-<a name="randomblobFunc">
-randomblob(<i>N</i>)</td>
-<td valign="top">Return a <i>N</i>-byte blob containing pseudo-random bytes.
-<i>N</i> should be a postive integer.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">round(<i>X</i>)<br>round(<i>X</i>,<i>Y</i>)</td>
-<td valign="top">Round off the number <i>X</i> to <i>Y</i> digits to the
-right of the decimal point. If the <i>Y</i> argument is omitted, 0 is
-assumed.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">
-<a name="rtrimFunc">
-rtrim(<i>X</i>)<br>rtrim(<i>X</i>,<i>Y</i>)</td>
-<td valign="top">Return a string formed by removing any and all
-characters that appear in <i>Y</i> from the right side of <i>X</i>.
-If the <i>Y</i> argument is omitted, spaces are removed.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">soundex(<i>X</i>)</td>
-<td valign="top">Compute the soundex encoding of the string <i>X</i>.
-The string "?000" is returned if the argument is NULL.
-This function is omitted from SQLite by default.
-It is only available the -DSQLITE_SOUNDEX=1 compiler option
-is used when SQLite is built.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">sqlite_version(*)</td>
-<td valign="top">Return the version string for the SQLite library
-that is running. Example: "2.8.0"</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">
- substr(<i>X</i>,<i>Y</i>,<i>Z</i>)<br>
- substr(<i>X</i>,<i>Y</i>)</td>
-<td valign="top">Return a substring of input string <i>X</i> that begins
-with the <i>Y</i>-th character and which is <i>Z</i> characters long.
-If <i>Z</i> is omitted then all character through the end of the string
-are returned.
-The left-most character of <i>X</i> is number 1. If <i>Y</i> is negative
-the the first character of the substring is found by counting from the
-right rather than the left. If <i>X</i> is string
-then characters indices refer to actual UTF-8 characters. If
-<i>X</i> is a BLOB then the indices refer to bytes.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">
-<a name="trimFunc">
-trim(<i>X</i>)<br>trim(<i>X</i>,<i>Y</i>)</td>
-<td valign="top">Return a string formed by removing any and all
-characters that appear in <i>Y</i> from both ends of <i>X</i>.
-If the <i>Y</i> argument is omitted, spaces are removed.</td>
-</tr>
-
-
-<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 "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>
-<td valign="top" align="right">upper(<i>X</i>)</td>
-<td valign="top">Return a copy of input string <i>X</i> converted to all
-upper-case letters. The implementation of this function uses the C library
-routine <b>toupper()</b> which means it may not work correctly on
-UTF-8 strings.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">zeroblob(<i>N</i>)</td>
-<td valign="top"><a name="zeroblob">
-Return a BLOB consisting of N bytes of 0x00. SQLite
-manages these zeroblobs very efficiently. Zeroblobs can be used to
-reserve space for a BLOB that is later written using
-<a href="capi3ref.html#sqlite3_blob_open">incremental BLOB I/O</a>.</td>
-</tr>
-
-</table>
-
-<b>Date And Time Functions</b>
-
-<p>Date and time functions are documented in the
-<a href="http://www.sqlite.org/cvstrac/wiki?p=DateAndTimeFunctions">
-SQLite Wiki</a>.</p>
-
-<a name="aggregatefunctions"></a>
-<b>Aggregate Functions</b>
-
-<p>
-The aggregate functions shown below are available by default. Additional
-aggregate functions written in C may be added using the
-<a href="capi3ref.html#sqlite3_create_function">sqlite3_create_function()</a>
-API.</p>
-
-<p>
-In any aggregate function that takes a single argument, that argument
-can be preceeded by the keyword DISTINCT. In such cases, duplicate
-elements are filtered before being passed into the aggregate function.
-For example, the function "count(distinct X)" will return the number
-of distinct values of column X instead of the total number of non-null
-values in column X.
-</p>
-
-<table border=0 cellpadding=10 class="pdf_functions">
-<tr>
-<td valign="top" align="right" width=120>avg(<i>X</i>)</td>
-<td valign="top">Return the average value of all non-NULL <i>X</i> within a
-group. String and BLOB values that do not look like numbers are
-interpreted as 0.
-The result of avg() is always a floating point value even if all
-inputs are integers. </p></td>
-</tr>
-
-<tr>
-<td valign="top" align="right">count(<i>X</i>)<br>count(*)</td>
-<td valign="top">The first form return a count of the number of times
-that <i>X</i> is not NULL in a group. The second form (with no argument)
-returns the total number of rows in the group.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">max(<i>X</i>)</td>
-<td valign="top">Return the maximum value of all values in the group.
-The usual sort order is used to determine the maximum.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">min(<i>X</i>)</td>
-<td valign="top">Return the minimum non-NULL value of all values in the group.
-The usual sort order is used to determine the minimum. NULL is only returned
-if all values in the group are NULL.</td>
-</tr>
-
-<tr>
-<td valign="top" align="right">sum(<i>X</i>)<br>total(<i>X</i>)</td>
-<td valign="top">Return the numeric sum of all non-NULL values in the group.
- If there are no non-NULL input rows then sum() returns
- NULL but total() returns 0.0.
- NULL is not normally a helpful result for the sum of no rows
- but the SQL standard requires it and most other
- SQL database engines implement sum() that way so SQLite does it in the
- same way in order to be compatible. The non-standard total() function
- is provided as a convenient way to work around this design problem
- in the SQL language.</p>
-
- <p>The result of total() is always a floating point value.
- The result of sum() is an integer value if all non-NULL inputs are integers.
- If any input to sum() is neither an integer or a NULL
- then sum() returns a floating point value
- which might be an approximation to the true sum.</p>
-
- <p>Sum() will throw an "integer overflow" exception if all inputs
- are integers or NULL
- and an integer overflow occurs at any point during the computation.
- Total() never throws an exception.</p>
-</tr>
-</table>
-}
-
-
-Section INSERT insert
-
-Syntax {sql-statement} {
-INSERT [OR <conflict-algorithm>] INTO [<database-name> .] <table-name> [(<column-list>)] VALUES(<value-list>) |
-INSERT [OR <conflict-algorithm>] INTO [<database-name> .] <table-name> [(<column-list>)] <select-statement>
-}
-
-puts {
-<p>The INSERT statement comes in two basic forms. The first form
-(with the "VALUES" keyword) creates a single new row in an existing table.
-If no column-list is specified then the number of values must
-be the same as the number of columns in the table. If a column-list
-is specified, then the number of values must match the number of
-specified columns. Columns of the table that do not appear in the
-column list are filled with the default value, or with NULL if no
-default value is specified.
-</p>
-
-<p>The second form of the INSERT statement takes it data from a
-SELECT statement. The number of columns in the result of the
-SELECT must exactly match the number of columns in the table if
-no column list is specified, or it must match the number of columns
-name in the column list. A new entry is made in the table
-for every row of the SELECT result. The SELECT may be simple
-or compound.</p>
-
-<p>The optional conflict-clause allows the specification of an alternative
-constraint conflict resolution algorithm to use during this one command.
-See the section titled
-<a href="#conflict">ON CONFLICT</a> for additional information.
-For compatibility with MySQL, the parser allows the use of the
-single keyword <a href="#replace">REPLACE</a> as an alias for "INSERT OR REPLACE".
-</p>
-}
-
-
-Section {ON CONFLICT clause} conflict
-
-Syntax {conflict-clause} {
-ON CONFLICT <conflict-algorithm>
-} {conflict-algorithm} {
-ROLLBACK | ABORT | FAIL | IGNORE | REPLACE
-}
-
-puts {
-<p>The ON CONFLICT clause is not a separate SQL command. It is a
-non-standard clause that can appear in many other SQL commands.
-It is given its own section in this document because it is not
-part of standard SQL and therefore might not be familiar.</p>
-
-<p>The syntax for the ON CONFLICT clause is as shown above for
-the CREATE TABLE command. For the INSERT and
-UPDATE commands, the keywords "ON CONFLICT" are replaced by "OR", to make
-the syntax seem more natural. For example, instead of
-"INSERT ON CONFLICT IGNORE" we have "INSERT OR IGNORE".
-The keywords change but the meaning of the clause is the same
-either way.</p>
-
-<p>The ON CONFLICT clause specifies an algorithm used to resolve
-constraint conflicts. There are five choices: ROLLBACK, ABORT,
-FAIL, IGNORE, and REPLACE. The default algorithm is ABORT. This
-is what they mean:</p>
-
-<dl>
-<dt><b>ROLLBACK</b></dt>
-<dd><p>When a constraint violation occurs, an immediate ROLLBACK
-occurs, thus ending the current transaction, and the command aborts
-with a return code of SQLITE_CONSTRAINT. If no transaction is
-active (other than the implied transaction that is created on every
-command) then this algorithm works the same as ABORT.</p></dd>
-
-<dt><b>ABORT</b></dt>
-<dd><p>When a constraint violation occurs, the command backs out
-any prior changes it might have made and aborts with a return code
-of SQLITE_CONSTRAINT. But no ROLLBACK is executed so changes
-from prior commands within the same transaction
-are preserved. This is the default behavior.</p></dd>
-
-<dt><b>FAIL</b></dt>
-<dd><p>When a constraint violation occurs, the command aborts with a
-return code SQLITE_CONSTRAINT. But any changes to the database that
-the command made prior to encountering the constraint violation
-are preserved and are not backed out. For example, if an UPDATE
-statement encountered a constraint violation on the 100th row that
-it attempts to update, then the first 99 row changes are preserved
-but changes to rows 100 and beyond never occur.</p></dd>
-
-<dt><b>IGNORE</b></dt>
-<dd><p>When a constraint violation occurs, the one row that contains
-the constraint violation is not inserted or changed. But the command
-continues executing normally. Other rows before and after the row that
-contained the constraint violation continue to be inserted or updated
-normally. No error is returned.</p></dd>
-
-<dt><b>REPLACE</b></dt>
-<dd><p>When a UNIQUE constraint violation occurs, the pre-existing rows
-that are causing the constraint violation are removed prior to inserting
-or updating the current row. Thus the insert or update always occurs.
-The command continues executing normally. No error is returned.
-If a NOT NULL constraint violation occurs, the NULL value is replaced
-by the default value for that column. If the column has no default
-value, then the ABORT algorithm is used. If a CHECK constraint violation
-occurs then the IGNORE algorithm is used.</p>
-
-<p>When this conflict resolution strategy deletes rows in order to
-satisfy a constraint, it does not invoke delete triggers on those
-rows. This behavior might change in a future release.</p>
-</dl>
-
-<p>The algorithm specified in the OR clause of a INSERT or UPDATE
-overrides any algorithm specified in a CREATE TABLE.
-If no algorithm is specified anywhere, the ABORT algorithm is used.</p>
-}
-
-Section REINDEX reindex
-
-Syntax {sql-statement} {
- REINDEX <collation name>
-}
-Syntax {sql-statement} {
- REINDEX [<database-name> .] <table/index-name>
-}
-
-puts {
-<p>The REINDEX command is used to delete and recreate indices from scratch.
-This is useful when the definition of a collation sequence has changed.
-</p>
-
-<p>In the first form, all indices in all attached databases that use the
-named collation sequence are recreated. In the second form, if
-<i>[database-name.]table/index-name</i> identifies a table, then all indices
-associated with the table are rebuilt. If an index is identified, then only
-this specific index is deleted and recreated.
-</p>
-
-<p>If no <i>database-name</i> is specified and there exists both a table or
-index and a collation sequence of the specified name, then indices associated
-with the collation sequence only are reconstructed. This ambiguity may be
-dispelled by always specifying a <i>database-name</i> when reindexing a
-specific table or index.
-}
-
-Section REPLACE replace
-
-Syntax {sql-statement} {
-REPLACE INTO [<database-name> .] <table-name> [( <column-list> )] VALUES ( <value-list> ) |
-REPLACE INTO [<database-name> .] <table-name> [( <column-list> )] <select-statement>
-}
-
-puts {
-<p>The REPLACE command is an alias for the "INSERT OR REPLACE" variant
-of the <a href="#insert">INSERT</a> command. This alias is provided for
-compatibility with MySQL. See the
-<a href="#insert">INSERT</a> command documentation for additional
-information.</p>
-}
-
-
-Section SELECT select
-
-Syntax {sql-statement} {
-SELECT [ALL | DISTINCT] <result> [FROM <table-list>]
-[WHERE <expr>]
-[GROUP BY <expr-list>]
-[HAVING <expr>]
-[<compound-op> <select>]*
-[ORDER BY <sort-expr-list>]
-[LIMIT <integer> [LP OFFSET | , RP <integer>]]
-} {result} {
-<result-column> [, <result-column>]*
-} {result-column} {
-STAR | <table-name> . STAR | <expr> [ [AS] <string> ]
-} {table-list} {
-<table> [<join-op> <table> <join-args>]*
-} {table} {
-<table-name> [AS <alias>] |
-( <select> ) [AS <alias>]
-} {join-op} {
-, | [NATURAL] [LEFT | RIGHT | FULL] [OUTER | INNER | CROSS] JOIN
-} {join-args} {
-[ON <expr>] [USING ( <id-list> )]
-} {sort-expr-list} {
-<expr> [<sort-order>] [, <expr> [<sort-order>]]*
-} {sort-order} {
-[ COLLATE <collation-name> ] [ ASC | DESC ]
-} {compound_op} {
-UNION | UNION ALL | INTERSECT | EXCEPT
-}
-
-puts {
-<p>The SELECT statement is used to query the database. The
-result of a SELECT is zero or more rows of data where each row
-has a fixed number of columns. The number of columns in the
-result is specified by the expression list in between the
-SELECT and FROM keywords. Any arbitrary expression can be used
-as a result. If a result expression is }
-puts "[Operator *] then all columns of all tables are substituted"
-puts {for that one expression. If the expression is the name of}
-puts "a table followed by [Operator .*] then the result is all columns"
-puts {in that one table.</p>
-
-<p>The DISTINCT keyword causes a subset of result rows to be returned,
-in which each result row is different. NULL values are not treated as
-distinct from each other. The default behavior is that all result rows
-be returned, which can be made explicit with the keyword ALL.</p>
-
-<p>The query is executed against one or more tables specified after
-the FROM keyword. If multiple tables names are separated by commas,
-then the query is against the cross join of the various tables.
-The full SQL-92 join syntax can also be used to specify joins.
-A sub-query
-in parentheses may be substituted for any table name in the FROM clause.
-The entire FROM clause may be omitted, in which case the result is a
-single row consisting of the values of the expression list.
-</p>
-
-<p>The WHERE clause can be used to limit the number of rows over
-which the query operates.</p>
-
-<p>The GROUP BY clauses causes one or more rows of the result to
-be combined into a single row of output. This is especially useful
-when the result contains aggregate functions. The expressions in
-the GROUP BY clause do <em>not</em> have to be expressions that
-appear in the result. The HAVING clause is similar to WHERE except
-that HAVING applies after grouping has occurred. The HAVING expression
-may refer to values, even aggregate functions, that are not in the result.</p>
-
-<p>The ORDER BY clause causes the output rows to be sorted.
-The argument to ORDER BY is a list of expressions that are used as the
-key for the sort. The expressions do not have to be part of the
-result for a simple SELECT, but in a compound SELECT each sort
-expression must exactly match one of the result columns. Each
-sort expression may be optionally followed by a COLLATE keyword and
-the name of a collating function used for ordering text and/or
-keywords ASC or DESC to specify the sort order.</p>
-
-<p>The LIMIT clause places an upper bound on the number of rows
-returned in the result. A negative LIMIT indicates no upper bound.
-The optional OFFSET following LIMIT specifies how many
-rows to skip at the beginning of the result set.
-In a compound query, the LIMIT clause may only appear on the
-final SELECT statement.
-The limit is applied to the entire query not
-to the individual SELECT statement to which it is attached.
-Note that if the OFFSET keyword is used in the LIMIT clause, then the
-limit is the first number and the offset is the second number. If a
-comma is used instead of the OFFSET keyword, then the offset is the
-first number and the limit is the second number. This seeming
-contradition is intentional - it maximizes compatibility with legacy
-SQL database systems.
-</p>
-
-<p>A compound SELECT is formed from two or more simple SELECTs connected
-by one of the operators UNION, UNION ALL, INTERSECT, or EXCEPT. In
-a compound SELECT, all the constituent SELECTs must specify the
-same number of result columns. There may be only a single ORDER BY
-clause at the end of the compound SELECT. The UNION and UNION ALL
-operators combine the results of the SELECTs to the right and left into
-a single big table. The difference is that in UNION all result rows
-are distinct where in UNION ALL there may be duplicates.
-The INTERSECT operator takes the intersection of the results of the
-left and right SELECTs. EXCEPT takes the result of left SELECT after
-removing the results of the right SELECT. When three or more SELECTs
-are connected into a compound, they group from left to right.</p>
-}
-
-
-Section UPDATE update
-
-Syntax {sql-statement} {
-UPDATE [ OR <conflict-algorithm> ] [<database-name> .] <table-name>
-SET <assignment> [, <assignment>]*
-[WHERE <expr>]
-} {assignment} {
-<column-name> = <expr>
-}
-
-puts {
-<p>The UPDATE statement is used to change the value of columns in
-selected rows of a table. Each assignment in an UPDATE specifies
-a column name to the left of the equals sign and an arbitrary expression
-to the right. The expressions may use the values of other columns.
-All expressions are evaluated before any assignments are made.
-A WHERE clause can be used to restrict which rows are updated.</p>
-
-<p>The optional conflict-clause allows the specification of an alternative
-constraint conflict resolution algorithm to use during this one command.
-See the section titled
-<a href="#conflict">ON CONFLICT</a> for additional information.</p>
-}
-
-
-Section VACUUM vacuum
-
-Syntax {sql-statement} {
-VACUUM [<index-or-table-name>]
-}
-
-puts {
-<p>The VACUUM command is an SQLite extension modeled after a similar
-command found in PostgreSQL. If VACUUM is invoked with the name of a
-table or index then it is suppose to clean up the named table or index.
-In version 1.0 of SQLite, the VACUUM command would invoke
-<b>gdbm_reorganize()</b> to clean up the backend database file.</p>
-
-<p>
-VACUUM became a no-op when the GDBM backend was removed from
-SQLITE in version 2.0.0.
-VACUUM was reimplemented in version 2.8.1.
-The index or table name argument is now ignored.
-</p>
-
-<p>When an object (table, index, or trigger) is dropped from the
-database, it leaves behind empty space. This makes the database
-file larger than it needs to be, but can speed up inserts. In time
-inserts and deletes can leave the database file structure fragmented,
-which slows down disk access to the database contents.
-
-The VACUUM command cleans
-the main database by copying its contents to a temporary database file and
-reloading the original database file from the copy. This eliminates
-free pages, aligns table data to be contiguous, and otherwise cleans
-up the database file structure.</p>
-
-<p>The VACUUM command may change the
-<a href="lang_createtable.html#rowid">ROWID</a> of entires in tables that do
-not have an explicit INTEGER PRIMARY KEY.</p>
-
-<p>VACUUM only works on the main database.
-It is not possible to VACUUM an attached database file.</p>
-
-<p>The VACUUM command will fail if there is an active transaction.
-The VACUUM command is a no-op for in-memory databases.</p>
-
-<p>As of SQLite version 3.1, an alternative to using the VACUUM command
-is auto-vacuum mode, enabled using the
-<a href="pragma.html#pragma_auto_vacuum">auto_vacuum pragma</a>.
-When auto-vacuum is enabled for a database, large deletes cause
-the size of the database file to shrink. However, auto-vacuum
-also causes excess fragmentation of the database file. And auto-vacuum
-does not compact partially filled pages of the database as VACUUM
-does.
-</p>
-}
-
-# A list of keywords. A asterisk occurs after the keyword if it is on
-# the fallback list.
-#
-set keyword_list [lsort {
- ABORT*
- ADD
- AFTER*
- ALL
- ALTER
- ANALYZE*
- AND
- AS
- ASC*
- ATTACH*
- AUTOINCREMENT
- BEFORE*
- BEGIN*
- BETWEEN
- BY
- CASCADE*
- CASE
- CAST*
- CHECK
- COLLATE
- COMMIT
- CONFLICT*
- CONSTRAINT
- CREATE
- CROSS
- CURRENT_DATE*
- CURRENT_TIME*
- CURRENT_TIMESTAMP*
- DATABASE*
- DEFAULT
- DEFERRED*
- DEFERRABLE
- DELETE
- DESC*
- DETACH*
- DISTINCT
- DROP
- END*
- EACH*
- ELSE
- ESCAPE
- EXCEPT
- EXCLUSIVE*
- EXPLAIN*
- FAIL*
- FOR*
- FOREIGN
- FROM
- FULL
- GLOB*
- GROUP
- HAVING
- IF*
- IGNORE*
- IMMEDIATE*
- IN
- INDEX
- INITIALLY*
- INNER
- INSERT
- INSTEAD*
- INTERSECT
- INTO
- IS
- ISNULL
- JOIN
- KEY*
- LEFT
- LIKE*
- LIMIT
- MATCH*
- NATURAL
- NOT
- NOTNULL
- NULL
- OF*
- OFFSET*
- ON
- OR
- ORDER
- OUTER
- PLAN*
- PRAGMA*
- PRIMARY
- QUERY*
- RAISE*
- REFERENCES
- REINDEX*
- RENAME*
- REPLACE*
- RESTRICT*
- RIGHT
- ROLLBACK
- ROW*
- SELECT
- SET
- TABLE
- TEMP*
- TEMPORARY*
- THEN
- TO
- TRANSACTION
- TRIGGER*
- UNION
- UNIQUE
- UPDATE
- USING
- VACUUM*
- VALUES
- VIEW*
- VIRTUAL*
- WHEN
- WHERE
-}]
-
-
-
-puts {<DIV class="pdf_section">}
-Section {SQLite Keywords} keywords
-puts {</DIV>}
-
-puts {
-<p>The SQL standard specifies a huge number of keywords which may not
-be used as the names of tables, indices, columns, databases, user-defined
-functions, collations, virtual table modules, or any other named object.
-The list of keywords is so long that few people can remember them all.
-For most SQL code, your safest bet is to never use any English language
-word as the name of a user-defined object.</p>
-
-<p>If you want to use a keyword as a name, you need to quote it. There
-are three ways of quoting keywords in SQLite:</p>
-
-<p>
-<blockquote>
-<table class="pdf_functions">
-<tr> <td valign="top"><b>'keyword'</b></td><td width="20"></td>
- <td>A keyword in single quotes is interpreted as a literal string
- if it occurs in a context where a string literal is allowed, otherwise
- it is understood as an identifier.</td></tr>
-<tr> <td valign="top"><b>"keyword"</b></td><td></td>
- <td>A keyword in double-quotes is interpreted as an identifier if
- it matches a known identifier. Otherwise it is interpreted as a
- string literal.</td></tr>
-<tr> <td valign="top"><b>[keyword]</b></td><td></td>
- <td>A keyword enclosed in square brackets is always understood as
- an identifier. This is not standard SQL. This quoting mechanism
- is used by MS Access and SQL Server and is included in SQLite for
- compatibility.</td></tr>
-</table>
-</blockquote>
-</p>
-
-<p>Quoted keywords are unaesthetic.
-To help you avoid them, SQLite allows many keywords to be used unquoted
-as the names of databases, tables, indices, triggers, views, columns,
-user-defined functions, collations, attached databases, and virtual
-function modules.
-In the list of keywords that follows, those that can be used as identifiers
-are shown in an italic font. Keywords that must be quoted in order to be
-used as identifiers are shown in bold.</p>
-
-<p>
-SQLite adds new keywords from time to time when it take on new features.
-So to prevent your code from being broken by future enhancements, you should
-normally quote any indentifier that is an English language word, even if
-you do not have to.
-</p>
-
-<p>
-The following are the keywords currently recognized by SQLite:
-</p>
-
-<blockquote>
-<table width="100%" class="pdf_keywords">
-<tr>
-<td align="left" valign="top" width="20%">
-}
-
-set n [llength $keyword_list]
-set nCol 5
-set nRow [expr {($n+$nCol-1)/$nCol}]
-set i 0
-foreach word $keyword_list {
- if {[string index $word end]=="*"} {
- set word [string range $word 0 end-1]
- set font i
- } else {
- set font b
- }
- if {$i==$nRow} {
- puts "</td><td valign=\"top\" align=\"left\" width=\"20%\">"
- set i 1
- } else {
- incr i
- }
- puts "<$font>$word</$font><br>"
-}
-
-puts {
-</td></tr></table></blockquote>
-
-<h2>Special names</h2>
-
-<p>The following are not keywords in SQLite, but are used as names of
-system objects. They can be used as an identifier for a different
-type of object.</p>
-
-<blockquote class="pdf_keywords"><b>
- _ROWID_<br>
- MAIN<br>
- OID<br>
- ROWID<br>
- SQLITE_MASTER<br>
- SQLITE_SEQUENCE<br>
- SQLITE_TEMP_MASTER<br>
- TEMP<br>
-</b></blockquote>
-}
-
-puts {<DIV class="pdf_ignore">}
-footer $rcsid
-if {[string length $outputdir]} {
- footer $rcsid
-}
-puts {</DIV>}
+++ /dev/null
-#
-# Run this script to generate the limits.html output file
-#
-set rcsid {$Id: limits.tcl,v 1.5 2007/08/09 00:00:26 drh Exp $}
-source common.tcl
-header {Implementation Limits For SQLite}
-puts {
-<h2>Limits In SQLite</h2>
-
-<p>
-"Limits" in the context of this article means sizes or
-quantities that can not be exceeded. We are concerned
-with things like the maximum number of bytes in a
-BLOB or the maximum number of columns in a table.
-</p>
-
-<p>
-SQLite was originally designed with a policy of avoiding
-arbitrary limits.
-Of course, every program that runs on a machine with finite
-memory and disk space has limits of some kind. But in SQLite,
-those limits
-were not well defined. The policy was that if it would fit
-in memory and you could count it with a 32-bit integer, then
-it should work.
-</p>
-
-<p>
-Unfortunately, the no-limits policy has been shown to create
-problems. Because the upper bounds were not well
-defined, they were not tested, and bugs (including possible
-security exploits) were often found when pushing SQLite to
-extremes. For this reason, newer versions of SQLite have
-well-defined limits and those limits are tested as part of
-the test suite.
-</p>
-
-<p>
-This article defines what the limits of SQLite are and how they
-can be customized for specific applications. The default settings
-for limits are normally quite large and adequate for almost every
-application. Some applications may what to increase a limit here
-or there, but we expect such needs to be rare. More commonly,
-an application might want to recompile SQLite with much lower
-limits to avoid excess resource utilization in the event of
-bug in higher-level SQL statement generators or to help thwart
-attackers who inject malicious SQL statements.
-</p>
-}
-proc limititem {title text} {
- puts "<li><p><b>$title</b></p>\n$text</li>"
-}
-puts {
-<ol>
-}
-
-limititem {Maximum length of a string or BLOB} {
-<p>
-The maximum number of bytes in a string or BLOB in SQLite is defined
-by the preprocessor macro SQLITE_MAX_LENGTH. The default value
-of this macro is 1 billion (1 thousand million or 1,000,000,000).
-You can raise or lower this value at compile-time using a command-line
-option like this:
-</p>
-
-<blockquote>-DSQLITE_MAX_LENGTH=123456789</blockquote>
-
-<p>
-The current implementation will only support a string or BLOB
-length up to 2<small><sup>31</sup></small>-1 or 2147483647. And
-some built-in functions such as hex() might fail well before that
-point. In security-sensitive applications it is best not to
-try to increase the maximum string and blob length. In fact,
-you might do well to lower the maximum string and blob length
-to something more in the range of a few million if that is
-possible.
-</p>
-
-<p>
-During part of SQLite's INSERT and SELECT processing, the complete
-content of each row in the database is encoded as a single BLOB.
-So the SQLITE_MAX_LENGTH parameter also determines the maximum
-number of bytes in a row.
-</p>
-}
-
-limititem {Maximum Number Of Columns} {
-<p>
-The SQLITE_MAX_COLUMN compile-time parameter is used to set an upper
-bound on:
-</p>
-
-<ul>
-<li>The number of columns in a table</li>
-<li>The number of columns in an index</li>
-<li>The number of columns in a view</li>
-<li>The number of terms in the SET clause of an UPDATE statement</li>
-<li>The number of columns in the result set of a SELECT statement</li>
-<li>The number of terms in a GROUP BY or ORDER BY clause</li>
-<li>The number of values in an INSERT statement</li>
-</ul>
-
-<p>
-The default setting for SQLITE_MAX_COLUMN is 2000. You can change it
-at compile time to values as large as 32676. You might be able to
-redefine this value to be as large as billions, though nobody has ever
-tried doing that so we do not know if it will work. On the other hand, there
-are people who will argue that a well-normalized database design
-will never need a value larger than about 100.
-</p>
-
-<p>
-In most applications, the number of columns is small - a few dozen.
-There are places in the SQLite code generator that use algorithms
-that are O(N²) where N is the number of columns.
-So if you redefine SQLITE_MAX_COLUMN to be a
-really huge number and you generate SQL that uses a large number of
-columns, you may find that
-<a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a>
-runs slowly.
-}
-
-limititem {Maximum Length Of An SQL Statement} {
-<p>
-The maximum number of bytes in the text of an SQL statement is
-limited to SQLITE_MAX_SQL_LENGTH which defaults to 1000000. You
-can redefine this limit to be as large as the smaller of SQLITE_MAX_LENGTH
-and 1073741824.
-</p>
-
-<p>
-If an SQL statement is limited to be a million bytes in length, then
-obviously you will not be able to insert multi-million byte strings
-by embedding them as literals inside of INSERT statements. But
-you should not do that anyway. Use host parameters
-for your data. Prepare short SQL statements like this:
-</p>
-
-<blockquote>
-INSERT INTO tab1 VALUES(?,?,?);
-</blockquote>
-
-<p>
-Then use the
-<a href="capi3ref.html#sqlite3_bind_text">sqlite3_bind_XXXX()</a> functions
-to bind your large string values to the SQL statement. The use of binding
-obviates the need to escape quote characters in the string, reducing the
-risk of SQL injection attacks. It is also runs faster since the large
-string does not need to be parsed or copied as much.
-</p>
-}
-
-limititem {Maximum Number Of Tables In A Join} {
-<p>
-SQLite does not support joins containing more than 64 tables.
-This limit arises from the fact that the SQLite code generator
-uses bitmaps with one bit per join-table in the query optimizer.
-</p>
-}
-
-limititem {Maximum Depth Of An Expression Tree} {
-<p>
-SQLite parses expressions into a tree for processing. During
-code generation, SQLite walks this tree recursively. The depth
-of expression trees is therefore limited in order to avoid
-using too much stack space.
-</p>
-
-<p>
-The SQLITE_MAX_EXPR_DEPTH parameter determines the maximum expression
-tree depth. If the value is 0, then no limit is enforced. The
-current implementation has a default value of 1000.
-</p>
-}
-
-limititem {Maximum Number Of Arguments On A Function} {
-<p>
-The SQLITE_MAX_FUNCTION_ARG parameter determines the maximum number
-of parameters that can be passed to an SQL function. The default value
-of this limit is 100. We know of no
-technical reason why SQLite would not work with functions that have
-millions of parameters. However, we suspect that anybody who tries
-to invoke a function with millions of parameters is really
-trying to find security exploits in systems that use SQLite,
-not do useful work,
-and so for that reason we have set this parameter relatively low.
-}
-
-limititem {Maximum Number Of Terms In A Compound SELECT Statement} {
-<p>
-A compound SELECT statement is two or more SELECT statements connected
-by operators UNION, UNION ALL, EXCEPT, or INTERSECT. We call each
-individual SELECT statement within a compound SELECT a "term".
-</p>
-
-<p>
-The code generator in SQLite processes compound SELECT statements using
-a recursive algorithm. In order to limit the size of the stack, we
-therefore limit the number of terms in a compound SELECT. The maximum
-number of terms is SQLITE_MAX_COMPOUND_SELECT which defaults to 500.
-We think this is a generous allotment since in practice we almost
-never see the number of terms in a compound select exceed single digits.
-</p>
-}
-
-limititem {Maximum Length Of A LIKE Or GLOB Pattern} {
-<p>
-The pattern matching algorithm used in the default LIKE and GLOB
-implementation of SQLite can exhibit O(N²) performance (where
-N is the number of characters in the pattern) for certain pathological
-cases. To avoid denial-of-service attacks from miscreants who are able
-to specify their own LIKE or GLOB patterns, the length of the LIKE
-or GLOB pattern is limited to SQLITE_MAX_LIKE_PATTERN_LENGTH bytes.
-The default value of this limit is 50000. A modern workstation can
-evaluate even a pathological LIKE or GLOB pattern of 50000 bytes
-relatively quickly. The denial of service problem only comes into
-play when the pattern length gets into millions of bytes. Nevertheless,
-since most useful LIKE or GLOB patterns are at most a few dozen bytes
-in length, paranoid application developers may want to reduce this
-parameter to something in the range of a few hundred if they know that
-external users are able to generate arbitrary patterns.
-</p>
-}
-
-limititem {Maximum Number Of Host Parameters In A Single SQL Statement} {
-<p>
-A host parameter is a place-holder in an SQL statement that is filled
-in using one of the
-<a href="capi3ref.html#sqlite3_bind_blob">sqlite3_bind_XXXX()</a> interfaces.
-Many SQL programmers are familiar with using a question mark ("?") as a
-host parameter. SQLite also supports named host parameters prefaced
-by ":", "$", or "@" and numbered host parameters of the form "?123".
-</p>
-
-<p>
-Each host parameter in an SQLite statement is assigned a number. The
-numbers normally begin with 1 and increase by one with each new
-parameter. However, when the "?123" form is used, the host parameter
-number is the number that follows the question mark.
-</p>
-
-<p>
-The maximum value of a host parameter number is SQLITE_MAX_VARIABLE_NUMBER.
-This setting defaults to 999.
-</p>
-}
-
-limititem {Maximum Number Of Attached Databases} {
-<p>
-The <a href="lang_attach.html">ATTACH</a> statement is an SQLite extension
-that allows two or more databases to be associated to the same database
-connection and to operate as if they were a single database. The number
-of simulataneously attached databases is limited to SQLITE_MAX_ATTACHED
-which is set to 10 by default.
-The code generator in SQLite uses bitmaps
-to keep track of attached databases. That means that the number of
-attached databases cannot be increased above 30 on a 32-bit machine
-or 62 on a 64-bit machine.
-}
-
-limititem {Maximum Database Page Size} {
-<p>
-An SQLite database file is organized as pages. The size of each
-page is a power of 2 between 512 and SQLITE_MAX_PAGE_SIZE.
-The default value for SQLITE_MAX_PAGE_SIZE is 32768. The current
-implementation will not support a larger value.
-</p>
-
-<p>
-It used to be the case that SQLite would allocate some stack
-structures whose size was proportional to the maximum page size.
-For this reason, SQLite would sometimes be compiled with a smaller
-maximum page size on embedded devices with limited stack memory. But
-more recent versions of SQLite put these large structures on the
-heap, not on the stack, so reducing the maximum page size is no
-longer necessary on embedded devices.
-</p>
-}
-
-limititem {Maximum Number Of Pages In A Database File} {
-<p>
-SQLite is able to limit the size of a database file to prevent
-the database file from growing too large and consuming too much
-disk or flash space.
-The SQLITE_MAX_PAGE_COUNT parameter, which is normally set to
-1073741823, is the maximum number of pages allowed in a single
-database file. An attempt to insert new data that would cause
-the database file to grow larger than this will return
-SQLITE_FULL.
-</p>
-
-<p>
-The <a href="pragma.html#pragma_max_page_count">
-max_page_count PRAGMA</a> can be used to raise or lower this
-limit at run-time.
-</p>
-
-<p>
-Note that the transaction processing in SQLite requires two bits
-of heap memory for every page in the database file. For databases
-of a few megabytes in size, this amounts to only a few hundred
-bytes of heap memory. But for gigabyte-sized databases the amount
-of heap memory required is getting into the kilobyte range and
-for terabyte-sized databases, megabytes of heap memory must be
-allocated and zeroed at each transaction. SQLite will
-support very large databases in theory, but the current implementation
-is optimized for the common SQLite use cases of embedded devices
-and persistent stores for desktop applications. In other words,
-SQLite is designed for use with databases sized in kilobytes or
-megabytes not gigabytes. If you are building an application to
-work with databases that are hundreds of gigabytes or more
-in size, then you should perhaps consider using a different database
-engine that is explicitly designed for such large data sets.
-</p>
-}
-
-puts {</ol>}
-footer $rcsid
+++ /dev/null
-#
-# Run this script to generated a lockingv3.html output file
-#
-set rcsid {$Id: }
-source common.tcl
-header {File Locking And Concurrency In SQLite Version 3}
-
-proc HEADING {level title {label {}}} {
- global pnum
- incr pnum($level)
- foreach i [array names pnum] {
- if {$i>$level} {set pnum($i) 0}
- }
- set h [expr {$level+1}]
- if {$h>6} {set h 6}
- set n $pnum(1).$pnum(2)
- for {set i 3} {$i<=$level} {incr i} {
- append n .$pnum($i)
- }
- if {$label!=""} {
- puts "<a name=\"$label\">"
- }
- puts "<h$h>$n $title</h$h>"
-}
-set pnum(1) 0
-set pnum(2) 0
-set pnum(3) 0
-set pnum(4) 0
-set pnum(5) 0
-set pnum(6) 0
-set pnum(7) 0
-set pnum(8) 0
-
-HEADING 1 {File Locking And Concurrency In SQLite Version 3}
-
-puts {
-<p>Version 3 of SQLite introduces a more complex locking and journaling
-mechanism designed to improve concurrency and reduce the writer starvation
-problem. The new mechanism also allows atomic commits of transactions
-involving multiple database files.
-This document describes the new locking mechanism.
-The intended audience is programmers who want to understand and/or modify
-the pager code and reviewers working to verify the design
-of SQLite version 3.
-</p>
-}
-
-HEADING 1 {Overview} overview
-
-puts {
-<p>
-Locking and concurrency control are handled by the the
-<a href="http://www.sqlite.org/cvstrac/getfile/sqlite/src/pager.c">
-pager module</a>.
-The pager module is responsible for making SQLite "ACID" (Atomic,
-Consistent, Isolated, and Durable). The pager module makes sure changes
-happen all at once, that either all changes occur or none of them do,
-that two or more processes do not try to access the database
-in incompatible ways at the same time, and that once changes have been
-written they persist until explicitly deleted. The pager also provides
-an memory cache of some of the contents of the disk file.</p>
-
-<p>The pager is unconcerned
-with the details of B-Trees, text encodings, indices, and so forth.
-From the point of view of the pager the database consists of
-a single file of uniform-sized blocks. Each block is called a
-"page" and is usually 1024 bytes in size. The pages are numbered
-beginning with 1. So the first 1024 bytes of the database are called
-"page 1" and the second 1024 bytes are call "page 2" and so forth. All
-other encoding details are handled by higher layers of the library.
-The pager communicates with the operating system using one of several
-modules
-(Examples:
-<a href="http://www.sqlite.org/cvstrac/getfile/sqlite/src/os_unix.c">
-os_unix.c</a>,
-<a href="http://www.sqlite.org/cvstrac/getfile/sqlite/src/os_win.c">
-os_win.c</a>)
-that provides a uniform abstraction for operating system services.
-</p>
-
-<p>The pager module effectively controls access for separate threads, or
-separate processes, or both. Throughout this document whenever the
-word "process" is written you may substitute the word "thread" without
-changing the truth of the statement.</p>
-}
-
-HEADING 1 {Locking} locking
-
-puts {
-<p>
-From the point of view of a single process, a database file
-can be in one of five locking states:
-</p>
-
-<p>
-<table cellpadding="20">
-<tr><td valign="top">UNLOCKED</td>
-<td valign="top">
-No locks are held on the database. The database may be neither read nor
-written. Any internally cached data is considered suspect and subject to
-verification against the database file before being used. Other
-processes can read or write the database as their own locking states
-permit. This is the default state.
-</td></tr>
-
-<tr><td valign="top">SHARED</td>
-<td valign="top">
-The database may be read but not written. Any number of
-processes can hold SHARED locks at the same time, hence there can be
-many simultaneous readers. But no other thread or process is allowed
-to write to the database file while one or more SHARED locks are active.
-</td></tr>
-
-<tr><td valign="top">RESERVED</td>
-<td valign="top">
-A RESERVED lock means that the process is planning on writing to the
-database file at some point in the future but that it is currently just
-reading from the file. Only a single RESERVED lock may be active at one
-time, though multiple SHARED locks can coexist with a single RESERVED lock.
-RESERVED differs from PENDING in that new SHARED locks can be acquired
-while there is a RESERVED lock.
-</td></tr>
-
-<tr><td valign="top">PENDING</td>
-<td valign="top">
-A PENDING lock means that the process holding the lock wants to write
-to the database as soon as possible and is just waiting on all current
-SHARED locks to clear so that it can get an EXCLUSIVE lock. No new
-SHARED locks are permitted against the database if
-a PENDING lock is active, though existing SHARED locks are allowed to
-continue.
-</td></tr>
-
-<tr><td valign="top">EXCLUSIVE</td>
-<td valign="top">
-An EXCLUSIVE lock is needed in order to write to the database file.
-Only one EXCLUSIVE lock is allowed on the file and no other locks of
-any kind are allowed to coexist with an EXCLUSIVE lock. In order to
-maximize concurrency, SQLite works to minimize the amount of time that
-EXCLUSIVE locks are held.
-</td></tr>
-</table>
-</p>
-
-<p>
-The operating system interface layer understands and tracks all five
-locking states described above.
-The pager module only tracks four of the five locking states.
-A PENDING lock is always just a temporary
-stepping stone on the path to an EXCLUSIVE lock and so the pager module
-does not track PENDING locks.
-</p>
-}
-
-HEADING 1 {The Rollback Journal} rollback
-
-puts {
-<p>Any time a process wants to make a changes to a database file, it
-first records enough information in the <em>rollback journal</em> to
-restore the database file back to its initial condition. Thus, before
-altering any page of the database, the original contents of that page
-must be written into the journal. The journal also records the initial
-size of the database so that if the database file grows it can be truncated
-back to its original size on a rollback.</p>
-
-<p>The rollback journal is a ordinary disk file that has the same name as
-the database file with the suffix "<tt>-journal</tt>" added.</p>
-
-<p>If SQLite is working with multiple databases at the same time
-(using the ATTACH command) then each database has its own journal.
-But there is also a separate aggregate journal
-called the <em>master journal</em>.
-The master journal does not contain page data used for rolling back
-changes. Instead the master journal contains the names of the
-individual file journals for each of the ATTACHed databases. Each of
-the individual file journals also contain the name of the master journal.
-If there are no ATTACHed databases (or if none of the ATTACHed database
-is participating in the current transaction) no master journal is
-created and the normal rollback journal contains an empty string
-in the place normally reserved for recording the name of the master
-journal.</p>
-
-<p>A individual file journal is said to be <em>hot</em>
-if it needs to be rolled back
-in order to restore the integrity of its database.
-A hot journal is created when a process is in the middle of a database
-update and a program or operating system crash or power failure prevents
-the update from completing.
-Hot journals are an exception condition.
-Hot journals exist to recover from crashes and power failures.
-If everything is working correctly
-(that is, if there are no crashes or power failures)
-you will never get a hot journal.
-</p>
-
-<p>
-If no master journal is involved, then
-a journal is hot if it exists and its corresponding database file
-does not have a RESERVED lock.
-If a master journal is named in the file journal, then the file journal
-is hot if its master journal exists and there is no RESERVED
-lock on the corresponding database file.
-It is important to understand when a journal is hot so the
-preceding rules will be repeated in bullets:
-</p>
-
-<ul>
-<li>A journal is hot if...
- <ul>
- <li>It exists, and</li>
- <li>It's master journal exists or the master journal name is an
- empty string, and</li>
- <li>There is no RESERVED lock on the corresponding database file.</li>
- </ul>
-</li>
-</ul>
-}
-
-HEADING 2 {Dealing with hot journals} hot_journals
-
-puts {
-<p>
-Before reading from a a database file, SQLite always checks to see if that
-database file has a hot journal. If the file does have a hot journal, then
-the journal is rolled back before the file is read. In this way, we ensure
-that the database file is in a consistent state before it is read.
-</p>
-
-<p>When a process wants to read from a database file, it followed
-the following sequence of steps:
-</p>
-
-<ol>
-<li>Open the database file and obtain a SHARED lock. If the SHARED lock
- cannot be obtained, fail immediately and return SQLITE_BUSY.</li>
-<li>Check to see if the database file has a hot journal. If the file
- does not have a hot journal, we are done. Return immediately.
- If there is a hot journal, that journal must be rolled back by
- the subsequent steps of this algorithm.</li>
-<li>Acquire a PENDING lock then an EXCLUSIVE lock on the database file.
- (Note: Do not acquire a RESERVED lock because that would make
- other processes think the journal was no longer hot.) If we
- fail to acquire these locks it means another process
- is already trying to do the rollback. In that case,
- drop all locks, close the database, and return SQLITE_BUSY. </li>
-<li>Read the journal file and roll back the changes.</li>
-<li>Wait for the rolled back changes to be written onto
- the surface of the disk. This protects the integrity of the database
- in case another power failure or crash occurs.</li>
-<li>Delete the journal file.</li>
-<li>Delete the master journal file if it is safe to do so.
- This step is optional. It is here only to prevent stale
- master journals from cluttering up the disk drive.
- See the discussion below for details.</li>
-<li>Drop the EXCLUSIVE and PENDING locks but retain the SHARED lock.</li>
-</ol>
-
-<p>After the algorithm above completes successfully, it is safe to
-read from the database file. Once all reading has completed, the
-SHARED lock is dropped.</p>
-}
-
-HEADING 2 {Deleting stale master journals} stale_master_journals
-
-puts {
-<p>A stale master journal is a master journal that is no longer being
-used for anything. There is no requirement that stale master journals
-be deleted. The only reason for doing so is to free up disk space.</p>
-
-<p>A master journal is stale if no individual file journals are pointing
-to it. To figure out if a master journal is stale, we first read the
-master journal to obtain the names of all of its file journals. Then
-we check each of those file journals. If any of the file journals named
-in the master journal exists and points back to the master journal, then
-the master journal is not stale. If all file journals are either missing
-or refer to other master journals or no master journal at all, then the
-master journal we are testing is stale and can be safely deleted.</p>
-}
-
-HEADING 1 {Writing to a database file} writing
-
-puts {
-<p>To write to a database, a process must first acquire a SHARED lock
-as described above (possibly rolling back incomplete changes if there
-is a hot journal).
-After a SHARED lock is obtained, a RESERVED lock must be acquired.
-The RESERVED lock signals that the process intends to write to the
-database at some point in the future. Only one process at a time
-can hold a RESERVED lock. But other processes can continue to read
-the database while the RESERVED lock is held.
-</p>
-
-<p>If the process that wants to write is unable to obtain a RESERVED
-lock, it must mean that another process already has a RESERVED lock.
-In that case, the write attempt fails and returns SQLITE_BUSY.</p>
-
-<p>After obtaining a RESERVED lock, the process that wants to write
-creates a rollback journal. The header of the journal is initialized
-with the original size of the database file. Space in the journal header
-is also reserved for a master journal name, though the master journal
-name is initially empty.</p>
-
-<p>Before making changes to any page of the database, the process writes
-the original content of that page into the rollback journal. Changes
-to pages are held in memory at first and are not written to the disk.
-The original database file remains unaltered, which means that other
-processes can continue to read the database.</p>
-
-<p>Eventually, the writing process will want to update the database
-file, either because its memory cache has filled up or because it is
-ready to commit its changes. Before this happens, the writer must
-make sure no other process is reading the database and that the rollback
-journal data is safely on the disk surface so that it can be used to
-rollback incomplete changes in the event of a power failure.
-The steps are as follows:</p>
-
-<ol>
-<li>Make sure all rollback journal data has actually been written to
- the surface of the disk (and is not just being held in the operating
- system's or disk controllers cache) so that if a power failure occurs
- the data will still be there after power is restored.</li>
-<li>Obtain a PENDING lock and then an EXCLUSIVE lock on the database file.
- If other processes are still have SHARED locks, the writer might have
- to wait until those SHARED locks clear before it is able to obtain
- an EXCLUSIVE lock.</li>
-<li>Write all page modifications currently held in memory out to the
- original database disk file.</li>
-</ol>
-
-<p>
-If the reason for writing to the database file is because the memory
-cache was full, then the writer will not commit right away. Instead,
-the writer might continue to make changes to other pages. Before
-subsequent changes are written to the database file, the rollback
-journal must be flushed to disk again. Note also that the EXCLUSIVE
-lock that the writer obtained in order to write to the database initially
-must be held until all changes are committed. That means that no other
-processes are able to access the database from the
-time the memory cache first spills to disk until the transaction
-commits.
-</p>
-
-<p>
-When a writer is ready to commit its changes, it executes the following
-steps:
-</p>
-
-<ol>
-<li value="4">
- Obtain an EXCLUSIVE lock on the database file and
- make sure all memory changes have been written to the database file
- using the algorithm of steps 1-3 above.</li>
-<li>Flush all database file changes to the disk. Wait for those changes
- to actually be written onto the disk surface.</li>
-<li>Delete the journal file. This is the instant when the changes are
- committed. Prior to deleting the journal file, if a power failure
- or crash occurs, the next process to open the database will see that
- it has a hot journal and will roll the changes back.
- After the journal is deleted, there will no longer be a hot journal
- and the changes will persist.
- </li>
-<li>Drop the EXCLUSIVE and PENDING locks from the database file.
- </li>
-</ol>
-
-<p>As soon as PENDING lock is released from the database file, other
-processes can begin reading the database again. In the current implementation,
-the RESERVED lock is also released, but that is not essential. Future
-versions of SQLite might provide a "CHECKPOINT" SQL command that will
-commit all changes made so far within a transaction but retain the
-RESERVED lock so that additional changes can be made without given
-any other process an opportunity to write.</p>
-
-<p>If a transaction involves multiple databases, then a more complex
-commit sequence is used, as follows:</p>
-
-<ol>
-<li value="4">
- Make sure all individual database files have an EXCLUSIVE lock and a
- valid journal.
-<li>Create a master-journal. The name of the master-journal is arbitrary.
- (The current implementation appends random suffixes to the name of the
- main database file until it finds a name that does not previously exist.)
- Fill the master journal with the names of all the individual journals
- and flush its contents to disk.
-<li>Write the name of the master journal into
- all individual journals (in space set aside for that purpose in the
- headers of the individual journals) and flush the contents of the
- individual journals to disk and wait for those changes to reach the
- disk surface.
-<li>Flush all database file changes to the disk. Wait for those changes
- to actually be written onto the disk surface.</li>
-<li>Delete the master journal file. This is the instant when the changes are
- committed. Prior to deleting the master journal file, if a power failure
- or crash occurs, the individual file journals will be considered hot
- and will be rolled back by the next process that
- attempts to read them. After the master journal has been deleted,
- the file journals will no longer be considered hot and the changes
- will persist.
- </li>
-<li>Delete all individual journal files.
-<li>Drop the EXCLUSIVE and PENDING locks from all database files.
- </li>
-</ol>
-}
-
-HEADING 2 {Writer starvation} writer_starvation
-
-puts {
-<p>In SQLite version 2, if many processes are reading from the database,
-it might be the case that there is never a time when there are
-no active readers. And if there is always at least one read lock on the
-database, no process would ever be able to make changes to the database
-because it would be impossible to acquire a write lock. This situation
-is called <em>writer starvation</em>.</p>
-
-<p>SQLite version 3 seeks to avoid writer starvation through the use of
-the PENDING lock. The PENDING lock allows existing readers to continue
-but prevents new readers from connecting to the database. So when a
-process wants to write a busy database, it can set a PENDING lock which
-will prevent new readers from coming in. Assuming existing readers do
-eventually complete, all SHARED locks will eventually clear and the
-writer will be given a chance to make its changes.</p>
-}
-
-HEADING 1 {How To Corrupt Your Database Files} how_to_corrupt
-
-puts {
-<p>The pager module is robust but it is not completely failsafe.
-It can be subverted. This section attempts to identify and explain
-the risks.</p>
-
-<p>
-Clearly, a hardware or operating system fault that introduces incorrect data
-into the middle of the database file or journal will cause problems.
-Likewise,
-if a rogue process opens a database file or journal and writes malformed
-data into the middle of it, then the database will become corrupt.
-There is not much that can be done about these kinds of problems
-so they are given no further attention.
-</p>
-
-<p>
-SQLite uses POSIX advisory locks to implement locking on Unix. On
-windows it uses the LockFile(), LockFileEx(), and UnlockFile() system
-calls. SQLite assumes that these system calls all work as advertised. If
-that is not the case, then database corruption can result. One should
-note that POSIX advisory locking is known to be buggy or even unimplemented
-on many NFS implementations (including recent versions of Mac OS X)
-and that there are reports of locking problems
-for network filesystems under windows. Your best defense is to not
-use SQLite for files on a network filesystem.
-</p>
-
-<p>
-SQLite uses the fsync() system call to flush data to the disk under Unix and
-it uses the FlushFileBuffers() to do the same under windows. Once again,
-SQLite assumes that these operating system services function as advertised.
-But it has been reported that fsync() and FlushFileBuffers() do not always
-work correctly, especially with inexpensive IDE disks. Apparently some
-manufactures of IDE disks have defective controller chips that report
-that data has reached the disk surface when in fact the data is still
-in volatile cache memory in the disk drive electronics. There are also
-reports that windows sometimes chooses to ignore FlushFileBuffers() for
-unspecified reasons. The author cannot verify any of these reports.
-But if they are true, it means that database corruption is a possibility
-following an unexpected power loss. These are hardware and/or operating
-system bugs that SQLite is unable to defend against.
-</p>
-
-<p>
-If a crash or power failure occurs and results in a hot journal but that
-journal is deleted, the next process to open the database will not
-know that it contains changes that need to be rolled back. The rollback
-will not occur and the database will be left in an inconsistent state.
-Rollback journals might be deleted for any number of reasons:
-</p>
-
-<ul>
-<li>An administrator might be cleaning up after an OS crash or power failure,
- see the journal file, think it is junk, and delete it.</li>
-<li>Someone (or some process) might rename the database file but fail to
- also rename its associated journal.</li>
-<li>If the database file has aliases (hard or soft links) and the file
- is opened by a different alias than the one used to create the journal,
- then the journal will not be found. To avoid this problem, you should
- not create links to SQLite database files.</li>
-<li>Filesystem corruption following a power failure might cause the
- journal to be renamed or deleted.</li>
-</ul>
-
-<p>
-The last (fourth) bullet above merits additional comment. When SQLite creates
-a journal file on Unix, it opens the directory that contains that file and
-calls fsync() on the directory, in an effort to push the directory information
-to disk. But suppose some other process is adding or removing unrelated
-files to the directory that contains the database and journal at the the
-moment of a power failure. The supposedly unrelated actions of this other
-process might result in the journal file being dropped from the directory and
-moved into "lost+found". This is an unlikely scenario, but it could happen.
-The best defenses are to use a journaling filesystem or to keep the
-database and journal in a directory by themselves.
-</p>
-
-<p>
-For a commit involving multiple databases and a master journal, if the
-various databases were on different disk volumes and a power failure occurs
-during the commit, then when the machine comes back up the disks might
-be remounted with different names. Or some disks might not be mounted
-at all. When this happens the individual file journals and the master
-journal might not be able to find each other. The worst outcome from
-this scenario is that the commit ceases to be atomic.
-Some databases might be rolled back and others might not.
-All databases will continue to be self-consistent.
-To defend against this problem, keep all databases
-on the same disk volume and/or remount disks using exactly the same names
-after a power failure.
-</p>
-}
-
-HEADING 1 {Transaction Control At The SQL Level} transaction_control
-
-puts {
-<p>
-The changes to locking and concurrency control in SQLite version 3 also
-introduce some subtle changes in the way transactions work at the SQL
-language level.
-By default, SQLite version 3 operates in <em>autocommit</em> mode.
-In autocommit mode,
-all changes to the database are committed as soon as all operations associated
-with the current database connection complete.</p>
-
-<p>The SQL command "BEGIN TRANSACTION" (the TRANSACTION keyword
-is optional) is used to take SQLite out of autocommit mode.
-Note that the BEGIN command does not acquire any locks on the database.
-After a BEGIN command, a SHARED lock will be acquired when the first
-SELECT statement is executed. A RESERVED lock will be acquired when
-the first INSERT, UPDATE, or DELETE statement is executed. No EXCLUSIVE
-lock is acquired until either the memory cache fills up and must
-be spilled to disk or until the transaction commits. In this way,
-the system delays blocking read access to the file file until the
-last possible moment.
-</p>
-
-<p>The SQL command "COMMIT" does not actually commit the changes to
-disk. It just turns autocommit back on. Then, at the conclusion of
-the command, the regular autocommit logic takes over and causes the
-actual commit to disk to occur.
-The SQL command "ROLLBACK" also operates by turning autocommit back on,
-but it also sets a flag that tells the autocommit logic to rollback rather
-than commit.</p>
-
-<p>If the SQL COMMIT command turns autocommit on and the autocommit logic
-then tries to commit change but fails because some other process is holding
-a SHARED lock, then autocommit is turned back off automatically. This
-allows the user to retry the COMMIT at a later time after the SHARED lock
-has had an opportunity to clear.</p>
-
-<p>If multiple commands are being executed against the same SQLite database
-connection at the same time, the autocommit is deferred until the very
-last command completes. For example, if a SELECT statement is being
-executed, the execution of the command will pause as each row of the
-result is returned. During this pause other INSERT, UPDATE, or DELETE
-commands can be executed against other tables in the database. But none
-of these changes will commit until the original SELECT statement finishes.
-</p>
-}
-
-
-footer $rcsid
+++ /dev/null
-#
-# Run this Tcl script to generate the mingw.html file.
-#
-set rcsid {$Id: mingw.tcl,v 1.4 2003/03/30 18:58:58 drh Exp $}
-
-puts {<html>
-<head>
- <title>Notes On How To Build MinGW As A Cross-Compiler</title>
-</head>
-<body bgcolor=white>
-<h1 align=center>
-Notes On How To Build MinGW As A Cross-Compiler
-</h1>}
-puts "<p align=center>
-(This page was last modified on [lrange $rcsid 3 4] UTC)
-</p>"
-
-puts {
-<p><a href="http://www.mingw.org/">MinGW</a> or
-<a href="http://www.mingw.org/">Minimalist GNU For Windows</a>
-is a version of the popular GCC compiler that builds Win95/Win98/WinNT
-binaries. See the website for details.</p>
-
-<p>This page describes how you can build MinGW
-from sources as a cross-compiler
-running under Linux. Doing so will allow you to construct
-WinNT binaries from the comfort and convenience of your
-Unix desktop.</p>
-}
-
-proc Link {path {file {}}} {
- if {$file!=""} {
- set path $path/$file
- } else {
- set file $path
- }
- puts "<a href=\"$path\">$file</a>"
-}
-
-puts {
-<p>Here are the steps:</p>
-
-<ol>
-<li>
-<p>Get a copy of source code. You will need the binutils, the
-compiler, and the MinGW runtime. Each are available separately.
-As of this writing, Mumit Khan has collected everything you need
-together in one FTP site:
-}
-set ftpsite \
- ftp://ftp.nanotech.wisc.edu/pub/khan/gnu-win32/mingw32/snapshots/gcc-2.95.2-1
-Link $ftpsite
-puts {
-The three files you will need are:</p>
-<ul>
-<li>}
-Link $ftpsite binutils-19990818-1-src.tar.gz
-puts </li><li>
-Link $ftpsite gcc-2.95.2-1-src.tar.gz
-puts </li><li>
-Link $ftpsite mingw-20000203.zip
-puts {</li>
-</ul>
-
-<p>Put all the downloads in a directory out of the way. The sequel
-will assume all downloads are in a directory named
-<b>~/mingw/download</b>.</p>
-</li>
-
-<li>
-<p>
-Create a directory in which to install the new compiler suite and make
-the new directory writable.
-Depending on what directory you choose, you might need to become
-root. The example shell commands that follow
-will assume the installation directory is
-<b>/opt/mingw</b> and that your user ID is <b>drh</b>.</p>
-<blockquote><pre>
-su
-mkdir /opt/mingw
-chown drh /opt/mingw
-exit
-</pre></blockquote>
-</li>
-
-<li>
-<p>Unpack the source tarballs into a separate directory.</p>
-<blockquote><pre>
-mkdir ~/mingw/src
-cd ~/mingw/src
-tar xzf ../download/binutils-*.tar.gz
-tar xzf ../download/gcc-*.tar.gz
-unzip ../download/mingw-*.zip
-</pre></blockquote>
-</li>
-
-<li>
-<p>Create a directory in which to put all the build products.</p>
-<blockquote><pre>
-mkdir ~/mingw/bld
-</pre></blockquote>
-</li>
-
-<li>
-<p>Configure and build binutils and add the results to your PATH.</p>
-<blockquote><pre>
-mkdir ~/mingw/bld/binutils
-cd ~/mingw/bld/binutils
-../../src/binutils/configure --prefix=/opt/mingw --target=i386-mingw32 -v
-make 2>&1 | tee make.out
-make install 2>&1 | tee make-install.out
-export PATH=$PATH:/opt/mingw/bin
-</pre></blockquote>
-</li>
-
-<li>
-<p>Manually copy the runtime include files into the installation directory
-before trying to build the compiler.</p>
-<blockquote><pre>
-mkdir /opt/mingw/i386-mingw32/include
-cd ~/mingw/src/mingw-runtime*/mingw/include
-cp -r * /opt/mingw/i386-mingw32/include
-</pre></blockquote>
-</li>
-
-<li>
-<p>Configure and build the compiler</p>
-<blockquote><pre>
-mkdir ~/mingw/bld/gcc
-cd ~/mingw/bld/gcc
-../../src/gcc-*/configure --prefix=/opt/mingw --target=i386-mingw32 -v
-cd gcc
-make installdirs
-cd ..
-make 2>&1 | tee make.out
-make install
-</pre></blockquote>
-</li>
-
-<li>
-<p>Configure and build the MinGW runtime</p>
-<blockquote><pre>
-mkdir ~/mingw/bld/runtime
-cd ~/mingw/bld/runtime
-../../src/mingw-runtime*/configure --prefix=/opt/mingw --target=i386-mingw32 -v
-make install-target-w32api
-make install
-</pre></blockquote>
-</li>
-</ol>
-
-<p>And you are done...</p>
-}
-puts {
-<p><hr /></p>
-<p><a href="index.html"><img src="/goback.jpg" border=0 />
-Back to the SQLite Home Page</a>
-</p>
-
-</body></html>}
+++ /dev/null
-#!/usr/bin/tclsh
-#
-# Run this script redirecting the sqlite3.h file as standard
-# inputs and this script will generate API documentation.
-#
-set rcsid {$Id: mkapidoc.tcl,v 1.2 2007/06/20 09:09:48 danielk1977 Exp $}
-source common.tcl
-header {C/C++ Interface For SQLite Version 3}
-puts {
-<h2 class=pdf_section>C/C++ Interface For SQLite Version 3</h2>
-}
-
-# Scan standard input to extract the information we need
-# to build the documentation.
-#
-set title {}
-set type {}
-set body {}
-set code {}
-set phase 0
-set content {}
-while {![eof stdin]} {
- set line [gets stdin]
- if {$phase==0} {
- # Looking for the CAPI3REF: keyword
- if {[regexp {^\*\* CAPI3REF: +(.*)} $line all tx]} {
- set title $tx
- set phase 1
- }
- } elseif {$phase==1} {
- if {[string range $line 0 1]=="**"} {
- set lx [string trim [string range $line 3 end]]
- if {[regexp {^CATEGORY: +([a-z]*)} $lx all cx]} {
- set type $cx
- } elseif {[regexp {^KEYWORDS: +(.*)} $lx all kx]} {
- foreach k $kx {
- set keyword($k) 1
- }
- } else {
- append body $lx\n
- }
- } elseif {[string range $line 0 1]=="*/"} {
- set phase 2
- }
- } elseif {$phase==2} {
- if {$line==""} {
- set kwlist [lsort [array names keyword]]
- unset -nocomplain keyword
- set key $type:$kwlist
- lappend content [list $key $title $type $kwlist $body $code]
- set title {}
- set keywords {}
- set type {}
- set body {}
- set code {}
- set phase 0
- } else {
- if {[regexp {^#define (SQLITE_[A-Z0-9_]+)} $line all kx]} {
- set type constant
- set keyword($kx) 1
- } elseif {[regexp {^typedef .* (sqlite[0-9a-z_]+);} $line all kx]} {
- set type datatype
- set keyword($kx) 1
- } elseif {[regexp {^[a-z].*[ *](sqlite3_[a-z0-9_]+)\(} $line all kx]} {
- set type function
- set keyword($kx) 1
- }
- append code $line\n
- }
- }
-}
-
-# Output HTML that displays the given list in N columns
-#
-proc output_list {N lx} {
- puts {<table width="100%" cellpadding="5"><tr>}
- set len [llength $lx]
- set n [expr {($len + $N - 1)/$N}]
- for {set i 0} {$i<$N} {incr i} {
- set start [expr {$i*$n}]
- set end [expr {($i+1)*$n}]
- puts {<td valign="top"><ul>}
- for {set j $start} {$j<$end} {incr j} {
- set entry [lindex $lx $j]
- if {$entry!=""} {
- foreach {link label} $entry break
- puts "<li><a href=\"#$link\">$label</a></li>"
- }
- }
- puts {</ul></td>}
- }
- puts {</tr></table>}
-}
-
-# Do a table of contents for objects
-#
-set objlist {}
-foreach c $content {
- foreach {key title type keywords body code} $c break
- if {$type!="datatype"} continue
- set keywords [lsort $keywords]
- set k [lindex $keywords 0]
- foreach kw $keywords {
- lappend objlist [list $k $kw]
- }
-}
-puts {<h2>Datatypes:</h2>}
-output_list 3 $objlist
-puts {<hr>}
-
-# Do a table of contents for constants
-#
-set clist {}
-foreach c $content {
- foreach {key title type keywords body code} $c break
- if {$type!="constant"} continue
- set keywords [lsort $keywords]
- set k [lindex $keywords 0]
- foreach kw $keywords {
- lappend clist [list $k $kw]
- }
-}
-puts {<h2>Constants:</h2>}
-set clist [lsort -index 1 $clist]
-output_list 3 $clist
-puts {<hr>}
-
-
-# Do a table of contents for functions
-#
-set funclist {}
-foreach c $content {
- foreach {key title type keywords body code} $c break
- if {$type!="function"} continue
- set keywords [lsort $keywords]
- set k [lindex $keywords 0]
- foreach kw $keywords {
- lappend funclist [list $k $kw]
- }
-}
-puts {<h2>Functions:</h2>}
-set funclist [lsort -index 1 $funclist]
-output_list 3 $funclist
-puts {<hr>}
-
-# Resolve links
-#
-proc resolve_links {args} {
- set tag [lindex $args 0]
- regsub -all {[^a-zA-Z0-9_]} $tag {} tag
- set x "<a href=\"#$tag\">"
- if {[llength $args]>2} {
- append x [lrange $args 2 end]</a>
- } else {
- append x [lindex $args 0]</a>
- }
- return $x
-}
-
-# Output all the records
-#
-foreach c [lsort $content] {
- foreach {key title type keywords body code} $c break
- foreach k $keywords {
- puts "<a name=\"$k\"></a>"
- }
- puts "<h2>$title</h2>"
- puts "<blockquote><pre>"
- puts "$code"
- puts "</pre></blockquote>"
- regsub -all "\n\n+" $body {</p>\1<p>} body
- regsub -all {\[} <p>$body</p> {[resolve_links } body
- set body [subst -novar -noback $body]
- puts "$body"
- puts "<hr>"
-}
+++ /dev/null
-#
-# Run this script to generated a nulls.html output file
-#
-set rcsid {$Id: nulls.tcl,v 1.8 2004/10/10 17:24:55 drh Exp $}
-source common.tcl
-header {NULL Handling in SQLite}
-puts {
-<h2>NULL Handling in SQLite Versus Other Database Engines</h2>
-
-<p>
-The goal is
-to make SQLite handle NULLs in a standards-compliant way.
-But the descriptions in the SQL standards on how to handle
-NULLs seem ambiguous.
-It is not clear from the standards documents exactly how NULLs should
-be handled in all circumstances.
-</p>
-
-<p>
-So instead of going by the standards documents, various popular
-SQL engines were tested to see how they handle NULLs. The idea
-was to make SQLite work like all the other engines.
-A SQL test script was developed and run by volunteers on various
-SQL RDBMSes and the results of those tests were used to deduce
-how each engine processed NULL values.
-The original tests were run in May of 2002.
-A copy of the test script is found at the end of this document.
-</p>
-
-<p>
-SQLite was originally coded in such a way that the answer to
-all questions in the chart below would be "Yes". But the
-experiments run on other SQL engines showed that none of them
-worked this way. So SQLite was modified to work the same as
-Oracle, PostgreSQL, and DB2. This involved making NULLs
-indistinct for the purposes of the SELECT DISTINCT statement and
-for the UNION operator in a SELECT. NULLs are still distinct
-in a UNIQUE column. This seems somewhat arbitrary, but the desire
-to be compatible with other engines outweighted that objection.
-</p>
-
-<p>
-It is possible to make SQLite treat NULLs as distinct for the
-purposes of the SELECT DISTINCT and UNION. To do so, one should
-change the value of the NULL_ALWAYS_DISTINCT #define in the
-<tt>sqliteInt.h</tt> source file and recompile.
-</p>
-
-<blockquote>
-<p>
-<i>Update 2003-07-13:</i>
-Since this document was originally written some of the database engines
-tested have been updated and users have been kind enough to send in
-corrections to the chart below. The original data showed a wide variety
-of behaviors, but over time the range of behaviors has converged toward
-the PostgreSQL/Oracle model. The only significant difference
-is that Informix and MS-SQL both threat NULLs as
-indistinct in a UNIQUE column.
-</p>
-
-<p>
-The fact that NULLs are distinct for UNIQUE columns but are indistinct for
-SELECT DISTINCT and UNION continues to be puzzling. It seems that NULLs
-should be either distinct everywhere or nowhere. And the SQL standards
-documents suggest that NULLs should be distinct everywhere. Yet as of
-this writing, no SQL engine tested treats NULLs as distinct in a SELECT
-DISTINCT statement or in a UNION.
-</p>
-</blockquote>
-
-
-<p>
-The following table shows the results of the NULL handling experiments.
-</p>
-
-<table border=1 cellpadding=3 width="100%">
-<tr><th>  </th>
-<th>SQLite</th>
-<th>PostgreSQL</th>
-<th>Oracle</th>
-<th>Informix</th>
-<th>DB2</th>
-<th>MS-SQL</th>
-<th>OCELOT</th>
-</tr>
-
-<tr><td>Adding anything to null gives null</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-</tr>
-<tr><td>Multiplying null by zero gives null</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-</tr>
-<tr><td>nulls are distinct in a UNIQUE column</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-<td valign="center" align="center" bgcolor="#aaaad2">(Note 4)</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-</tr>
-<tr><td>nulls are distinct in SELECT DISTINCT</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-</tr>
-<tr><td>nulls are distinct in a UNION</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-</tr>
-<tr><td>"CASE WHEN null THEN 1 ELSE 0 END" is 0?</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-</tr>
-<tr><td>"null OR true" is true</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-</tr>
-<tr><td>"not (null AND false)" is true</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-</tr>
-</table>
-
-<table border=1 cellpadding=3 width="100%">
-<tr><th>  </th>
-<th>MySQL<br>3.23.41</th>
-<th>MySQL<br>4.0.16</th>
-<th>Firebird</th>
-<th>SQL<br>Anywhere</th>
-<th>Borland<br>Interbase</th>
-</tr>
-
-<tr><td>Adding anything to null gives null</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-</tr>
-<tr><td>Multiplying null by zero gives null</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-</tr>
-<tr><td>nulls are distinct in a UNIQUE column</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#aaaad2">(Note 4)</td>
-<td valign="center" align="center" bgcolor="#aaaad2">(Note 4)</td>
-</tr>
-<tr><td>nulls are distinct in SELECT DISTINCT</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No (Note 1)</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-</tr>
-<tr><td>nulls are distinct in a UNION</td>
-<td valign="center" align="center" bgcolor="#aaaad2">(Note 3)</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No (Note 1)</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-</tr>
-<tr><td>"CASE WHEN null THEN 1 ELSE 0 END" is 0?</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#aaaad2">(Note 5)</td>
-</tr>
-<tr><td>"null OR true" is true</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-</tr>
-<tr><td>"not (null AND false)" is true</td>
-<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
-</tr>
-</table>
-
-<table border=0 align="right" cellpadding=0 cellspacing=0>
-<tr>
-<td valign="top" rowspan=5>Notes: </td>
-<td>1. </td>
-<td>Older versions of firebird omits all NULLs from SELECT DISTINCT
-and from UNION.</td>
-</tr>
-<tr><td>2. </td>
-<td>Test data unavailable.</td>
-</tr>
-<tr><td>3. </td>
-<td>MySQL version 3.23.41 does not support UNION.</td>
-</tr>
-<tr><td>4. </td>
-<td>DB2, SQL Anywhere, and Borland Interbase
-do not allow NULLs in a UNIQUE column.</td>
-</tr>
-<tr><td>5. </td>
-<td>Borland Interbase does not support CASE expressions.</td>
-</tr>
-</table>
-<br clear="both">
-
-<p> </p>
-<p>
-The following script was used to gather information for the table
-above.
-</p>
-
-<pre>
--- I have about decided that SQL's treatment of NULLs is capricious and cannot be
--- deduced by logic. It must be discovered by experiment. To that end, I have
--- prepared the following script to test how various SQL databases deal with NULL.
--- My aim is to use the information gather from this script to make SQLite as much
--- like other databases as possible.
---
--- If you could please run this script in your database engine and mail the results
--- to me at drh@hwaci.com, that will be a big help. Please be sure to identify the
--- database engine you use for this test. Thanks.
---
--- If you have to change anything to get this script to run with your database
--- engine, please send your revised script together with your results.
---
-
--- Create a test table with data
-create table t1(a int, b int, c int);
-insert into t1 values(1,0,0);
-insert into t1 values(2,0,1);
-insert into t1 values(3,1,0);
-insert into t1 values(4,1,1);
-insert into t1 values(5,null,0);
-insert into t1 values(6,null,1);
-insert into t1 values(7,null,null);
-
--- Check to see what CASE does with NULLs in its test expressions
-select a, case when b<>0 then 1 else 0 end from t1;
-select a+10, case when not b<>0 then 1 else 0 end from t1;
-select a+20, case when b<>0 and c<>0 then 1 else 0 end from t1;
-select a+30, case when not (b<>0 and c<>0) then 1 else 0 end from t1;
-select a+40, case when b<>0 or c<>0 then 1 else 0 end from t1;
-select a+50, case when not (b<>0 or c<>0) then 1 else 0 end from t1;
-select a+60, case b when c then 1 else 0 end from t1;
-select a+70, case c when b then 1 else 0 end from t1;
-
--- What happens when you multiple a NULL by zero?
-select a+80, b*0 from t1;
-select a+90, b*c from t1;
-
--- What happens to NULL for other operators?
-select a+100, b+c from t1;
-
--- Test the treatment of aggregate operators
-select count(*), count(b), sum(b), avg(b), min(b), max(b) from t1;
-
--- Check the behavior of NULLs in WHERE clauses
-select a+110 from t1 where b<10;
-select a+120 from t1 where not b>10;
-select a+130 from t1 where b<10 OR c=1;
-select a+140 from t1 where b<10 AND c=1;
-select a+150 from t1 where not (b<10 AND c=1);
-select a+160 from t1 where not (c=1 AND b<10);
-
--- Check the behavior of NULLs in a DISTINCT query
-select distinct b from t1;
-
--- Check the behavior of NULLs in a UNION query
-select b from t1 union select b from t1;
-
--- Create a new table with a unique column. Check to see if NULLs are considered
--- to be distinct.
-create table t2(a int, b int unique);
-insert into t2 values(1,1);
-insert into t2 values(2,null);
-insert into t2 values(3,null);
-select * from t2;
-
-drop table t1;
-drop table t2;
-</pre>
-}
-
-footer $rcsid
+++ /dev/null
-#!/usr/bin/tclsh
-source common.tcl
-header {SQLite Older News}
-
-proc newsitem {date title text} {
- puts "<h3>$date - $title</h3>"
- regsub -all "\n( *\n)+" $text "</p>\n\n<p>" txt
- puts "<p>$txt</p>"
- puts "<hr width=\"50%\">"
-}
-
-newsitem {2007-Aug-13} {Version 3.4.2} {
- While stress-testing the
- <a href="capi3ref.html#sqlite3_soft_heap_limit">soft_heap_limit</a>
- feature, a bug that could lead to
- <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption">database
- corruption</a> was <a href="http://www.sqlite.org/cvstrac/tktview?tn=2565">
- discovered and fixed</a>.
- Though the consequences of this bug are severe, the chances of hitting
- it in a typical application are remote. Upgrading is recommended
- only if you use the
- <a href="capi3ref.html#sqlite3_soft_heap_limit">sqlite3_soft_heap_limit</a>
- interface.
-}
-
-newsitem {2007-Jly-20} {Version 3.4.1} {
- This release fixes a bug in <a href="lang_vacuum.html">VACUUM</a> that
- can lead to <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption">
- database corruption</a>. The bug was introduced in version
- <a href="changes.html#version_3_3_14">3.3.14</a>.
- Upgrading is recommended for all users. Also included are a slew of
- other more routine
- <a href="changes.html#version_3_4_1">enhancements and bug fixes</a>.
-}
-
-newsitem {2007-Jun-18} {Version 3.4.0} {
- This release fixes two separate bugs either of which
- can lead to database corruption. Upgrading
- is strongly recommended. If you must continue using an older version
- of SQLite, please at least read about how to avoid these bugs
- at
- <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">
- CorruptionFollowingBusyError</a> and
- <a href="http://www.sqlite.org/cvstrac/tktview?tn=2418">ticket #2418</a>
- <p>
- This release also adds explicit <a href="limits.html">limits</a> on the
- sizes and quantities of things SQLite will handle. The new limits might
- causes compatibility problems for existing applications that
- use excessively large strings, BLOBs, tables, or SQL statements.
- The new limits can be increased at compile-time to work around any problems
- that arise. Nevertheless, the version number of this release is
- 3.4.0 instead of 3.3.18 in order to call attention to the possible
- incompatibility.
- </p>
- There are also new features, including
- <a href="capi3ref.html#sqlite3_blob_open">incremental BLOB I/O</a> and
- <a href="pragma.html#pragma_incremental_vacuum">incremental vacuum</a>.
- See the <a href="changes.html#version_3_4_0">change log</a>
- for additional information.
-}
-
-newsitem {2007-Apr-25} {Version 3.3.17} {
- This version fixes a bug in the forwards-compatibility logic of SQLite
- that was causing a database to become unreadable when it should have
- been read-only. Upgrade from 3.3.16 only if you plan to deploy into
- a product that might need to be upgraded in the future. For day to day
- use, it probably does not matter.
-}
-
-newsitem {2007-Apr-18} {Version 3.3.16} {
- Performance improvements added in 3.3.14 but mistakenly turned off
- in 3.3.15 have been reinstated. A bug has been fixed that prevented
- VACUUM from running if a NULL value was in a UNIQUE column.
-}
-
-newsitem {2007-Apr-09} {Version 3.3.15} {
- An annoying bug introduced in 3.3.14 has been fixed. There are
- also many enhancements to the test suite.
-}
-
-newsitem {2007-Apr-02} {Version 3.3.14} {
- This version focuses on performance improvements. If you recompile
- <a href="http://www.sqlite.org/cvstrac/wiki?p=TheAmalgamation">
- the amalgamation</a> using GCC option -O3 (the precompiled binaries
- use -O2) you may see performance
- improvements of 35% or more over version 3.3.13 depending on your
- workload. This version also
- adds support for <a href="pragma.html#pragma_locking_mode">
- exclusive access mode</a>.
-}
-
-newsitem {2007-Feb-13} {Version 3.3.13} {
- This version fixes a subtle bug in the ORDER BY optimizer that can
- occur when using joins. There are also a few minor enhancements.
- Upgrading is recommended.
-}
-
-newsitem {2007-Jan-27} {Version 3.3.12} {
- The first published build of the previous version used the wrong
- set of source files. Consequently, many people downloaded a build
- that was labeled as "3.3.11" but was really 3.3.10. Version 3.3.12
- is released to clear up the ambiguity. A couple more bugs have
- also been fixed and <a href="pragma.html#pragma_integrity_check">
- PRAGMA integrity_check</a> has been enhanced.
-}
-
-newsitem {2007-Jan-22} {Version 3.3.11} {
- Version 3.3.11 fixes for a few more problems in version 3.3.9 that
- version 3.3.10 failed to catch. Upgrading is recommended.
-}
-
-newsitem {2007-Jan-9} {Version 3.3.10} {
- Version 3.3.10 fixes several bugs that were introduced by the previous
- release. Upgrading is recommended.
-}
-
-newsitem {2007-Jan-4} {Version 3.3.9} {
- Version 3.3.9 fixes bugs that can lead to database corruption under
- obscure and difficult to reproduce circumstances. See
- <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption">
- DatabaseCorruption</a> in the
- <a href="http://www.sqlite.org/cvstrac/wiki">wiki</a> for details.
- This release also adds the new
- <a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a>
- API and includes important bug fixes in the command-line
- shell and enhancements to the query optimizer. Upgrading is
- recommended.
-}
-
-newsitem {2006-Oct-9} {Version 3.3.8} {
- Version 3.3.8 adds support for full-text search using the
- <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsOne">FTS1
- module.</a> There are also minor bug fixes. Upgrade only if
- you want to try out the new full-text search capabilities or if
- you are having problems with 3.3.7.
-}
-
-newsitem {2006-Aug-12} {Version 3.3.7} {
- Version 3.3.7 includes support for loadable extensions and virtual
- tables. But both features are still considered "beta" and their
- APIs are subject to change in a future release. This release is
- mostly to make available the minor bug fixes that have accumulated
- since 3.3.6. Upgrading is not necessary. Do so only if you encounter
- one of the obscure bugs that have been fixed or if you want to try
- out the new features.
-}
-
-newsitem {2006-Jun-19} {New Book About SQLite} {
- <a href="http://www.apress.com/book/bookDisplay.html?bID=10130">
- <i>The Definitive Guide to SQLite</i></a>, a new book by
- <a href="http://www.mikesclutter.com">Mike Owens</a>.
- is now available from <a href="http://www.apress.com">Apress</a>.
- The books covers the latest SQLite internals as well as
- the native C interface and bindings for PHP, Python,
- Perl, Ruby, Tcl, and Java. Recommended.
-}
-
-
-newsitem {2006-Jun-6} {Version 3.3.6} {
- Changes include improved tolerance for windows virus scanners
- and faster :memory: databases. There are also fixes for several
- obscure bugs. Upgrade if you are having problems.
-}
-
-newsitem {2006-Apr-5} {Version 3.3.5} {
- This release fixes many minor bugs and documentation typos and
- provides some minor new features and performance enhancements.
- Upgrade only if you are having problems or need one of the new features.
-}
-
-newsitem {2006-Feb-11} {Version 3.3.4} {
- This release fixes several bugs, including a
- a blunder that might cause a deadlock on multithreaded systems.
- Anyone using SQLite in a multithreaded environment should probably upgrade.
-}
-
-newsitem {2006-Jan-31} {Version 3.3.3 stable} {
- There have been no major problems discovered in version 3.3.2, so
- we hereby declare the new APIs and language features to be stable
- and supported.
-}
-
-newsitem {2006-Jan-24} {Version 3.3.2 beta} {
- More bug fixes and performance improvements as we move closer to
- a production-ready version 3.3.x.
-}
-
-newsitem {2006-Jan-16} {Version 3.3.1 alpha} {
- Many bugs found in last week's alpha release have now been fixed and
- the library is running much faster again.
-
- Database connections can now be moved between threads as long as the
- connection holds no locks at the time it is moved. Thus the common
- paradigm of maintaining a pool of database connections and handing
- them off to transient worker threads is now supported.
- Please help test this new feature.
- See <a href="http://www.sqlite.org/cvstrac/wiki?p=MultiThreading">
- the MultiThreading wiki page</a> for additional
- information.
-}
-
-newsitem {2006-Jan-10} {Version 3.3.0 alpha} {
- Version 3.3.0 adds support for CHECK constraints, DESC indices,
- separate REAL and INTEGER column affinities, a new OS interface layer
- design, and many other changes. The code passed a regression
- test but should still be considered alpha. Please report any
- problems.
-
- The file format for version 3.3.0 has changed slightly to support
- descending indices and
- a more efficient encoding of boolean values. SQLite 3.3.0 will read and
- write legacy databases created with any prior version of SQLite 3. But
- databases created by version 3.3.0 will not be readable or writable
- by earlier versions of the SQLite. The older file format can be
- specified at compile-time for those rare cases where it is needed.
-}
-
-newsitem {2005-Dec-19} {Versions 3.2.8 and 2.8.17} {
- These versions contain one-line changes to 3.2.7 and 2.8.16 to fix a bug
- that has been present since March of 2002 and version 2.4.0.
- That bug might possibly cause database corruption if a large INSERT or
- UPDATE statement within a multi-statement transaction fails due to a
- uniqueness constraint but the containing transaction commits.
-}
-
-
-newsitem {2005-Sep-24} {Version 3.2.7} {
- This version fixes several minor and obscure bugs.
- Upgrade only if you are having problems.
-}
-
-newsitem {2005-Sep-16} {Version 3.2.6 - Critical Bug Fix} {
- This version fixes a bug that can result in database
- corruption if a VACUUM of a 1 gibibyte or larger database fails
- (perhaps do to running out of disk space or an unexpected power loss)
- and is later rolled back.
- <p>
- Also in this release:
- The ORDER BY and GROUP BY processing was rewritten to use less memory.
- Support for COUNT(DISTINCT) was added. The LIKE operator can now be
- used by the optimizer on columns with COLLATE NOCASE.
-}
-
-newsitem {2005-Aug-27} {Version 3.2.5} {
- This release fixes a few more lingering bugs in the new code.
- We expect that this release will be stable and ready for production use.
-}
-
-newsitem {2005-Aug-24} {Version 3.2.4} {
- This release fixes a bug in the new optimizer that can lead to segfaults
- when parsing very complex WHERE clauses.
-}
-
-newsitem {2005-Aug-21} {Version 3.2.3} {
- This release adds the <a href="lang_analyze.html">ANALYZE</a> command,
- the <a href="lang_expr.html">CAST</a> operator, and many
- very substantial improvements to the query optimizer. See the
- <a href="changes.html#version_3_2_3">change log</a> for additional
- information.
-}
-
-newsitem {2005-Aug-2} {2005 Open Source Award for SQLite} {
- SQLite and its primary author D. Richard Hipp have been honored with
- a <a href="http://osdir.com/Article6677.phtml">2005 Open Source
- Award</a> from Google and O'Reilly.<br clear="right">
-}
-
-
-newsitem {2005-Jun-13} {Version 3.2.2} {
- This release includes numerous minor bug fixes, speed improvements,
- and code size reductions. There is no reason to upgrade unless you
- are having problems or unless you just want to.
-}
-
-newsitem {2005-Mar-29} {Version 3.2.1} {
- This release fixes a memory allocation problem in the new
- <a href="lang_altertable.html">ALTER TABLE ADD COLUMN</a>
- command.
-}
-
-newsitem {2005-Mar-21} {Version 3.2.0} {
- The primary purpose for version 3.2.0 is to add support for
- <a href="lang_altertable.html">ALTER TABLE ADD COLUMN</a>.
- The new ADD COLUMN capability is made
- possible by AOL developers supporting and embracing great
- open-source software. Thanks, AOL!
-
- Version 3.2.0 also fixes an obscure but serious bug that was discovered
- just prior to release. If you have a multi-statement transaction and
- within that transaction an UPDATE or INSERT statement fails due to a
- constraint, then you try to rollback the whole transaction, the rollback
- might not work correctly. See
- <a href="http://www.sqlite.org/cvstrac/tktview?tn=1171">Ticket #1171</a>
- for details. Upgrading is recommended for all users.
-}
-
-newsitem {2005-Mar-16} {Version 3.1.6} {
- Version 3.1.6 fixes a critical bug that can cause database corruption
- when inserting rows into tables with around 125 columns. This bug was
- introduced in version 3.0.0. See
- <a href="http://www.sqlite.org/cvstrac/tktview?tn=1163">Ticket #1163</a>
- for additional information.
-}
-
-newsitem {2005-Mar-11} {Versions 3.1.4 and 3.1.5 Released} {
- Version 3.1.4 fixes a critical bug that could cause database corruption
- if the autovacuum mode of version 3.1.0 is turned on (it is off by
- default) and a CREATE UNIQUE INDEX is executed within a transaction but
- fails because the indexed columns are not unique. Anyone using the
- autovacuum feature and unique indices should upgrade.
-
- Version 3.1.5 adds the ability to disable
- the F_FULLFSYNC ioctl() in OS-X by setting "PRAGMA synchronous=on" instead
- of the default "PRAGMA synchronous=full". There was an attempt to add
- this capability in 3.1.4 but it did not work due to a spelling error.
-}
-
-newsitem {2005-Feb-19} {Version 3.1.3 Released} {
- Version 3.1.3 cleans up some minor issues discovered in version 3.1.2.
-}
-
-newsitem {2005-Feb-15} {Versions 2.8.16 and 3.1.2 Released} {
- A critical bug in the VACUUM command that can lead to database
- corruption has been fixed in both the 2.x branch and the main
- 3.x line. This bug has existed in all prior versions of SQLite.
- Even though it is unlikely you will ever encounter this bug,
- it is suggested that all users upgrade. See
- <a href="http://www.sqlite.org/cvstrac/tktview?tn=1116">
- ticket #1116</a>. for additional information.
-
- Version 3.1.2 is also the first stable release of the 3.1
- series. SQLite 3.1 features added support for correlated
- subqueries, autovacuum, autoincrement, ALTER TABLE, and
- other enhancements. See the
- <a href="http://www.sqlite.org/releasenotes310.html">release notes
- for version 3.1.0</a> for a detailed description of the
- changes available in the 3.1 series.
-}
-
-newsitem {2005-Feb-01} {Version 3.1.1 (beta) Released} {
- Version 3.1.1 (beta) is now available on the
- website. Verison 3.1.1 is fully backwards compatible with the 3.0 series
- and features many new features including Autovacuum and correlated
- subqueries. The
- <a href="http://www.sqlite.org/releasenotes310.html">release notes</a>
- From version 3.1.0 apply equally to this release beta. A stable release
- is expected within a couple of weeks.
-}
-
-newsitem {2005-Jan-21} {Version 3.1.0 (alpha) Released} {
- Version 3.1.0 (alpha) is now available on the
- website. Verison 3.1.0 is fully backwards compatible with the 3.0 series
- and features many new features including Autovacuum and correlated
- subqueries. See the
- <a href="http://www.sqlite.org/releasenotes310.html">release notes</a>
- for details.
-
- This is an alpha release. A beta release is expected in about a week
- with the first stable release to follow after two more weeks.
-}
-
-newsitem {2004-Nov-09} {SQLite at the 2004 International PHP Conference} {
- There was a talk on the architecture of SQLite and how to optimize
- SQLite queries at the 2004 International PHP Conference in Frankfurt,
- Germany.
- <a href="http://www.sqlite.org/php2004/page-001.html">
- Slides</a> from that talk are available.
-}
-
-newsitem {2004-Oct-11} {Version 3.0.8} {
- Version 3.0.8 of SQLite contains several code optimizations and minor
- bug fixes and adds support for DEFERRED, IMMEDIATE, and EXCLUSIVE
- transactions. This is an incremental release. There is no reason
- to upgrade from version 3.0.7 if that version is working for you.
-}
-
-
-newsitem {2004-Oct-10} {SQLite at the 11<sup><small>th</small></sup>
-Annual Tcl/Tk Conference} {
- There will be a talk on the use of SQLite in Tcl/Tk at the
- 11<sup><small>th</small></sup> Tcl/Tk Conference this week in
- New Orleans. Visit <a href="http://www.tcl.tk/community/tcl2004/">
- http://www.tcl.tk/</a> for details.
- <a href="http://www.sqlite.org/tclconf2004/page-001.html">
- Slides</a> from the talk are available.
-}
-
-newsitem {2004-Sep-18} {Version 3.0.7} {
- Version 3.0 has now been in use by multiple projects for several
- months with no major difficulties. We consider it stable and
- ready for production use.
-}
-
-newsitem {2004-Sep-02} {Version 3.0.6 (beta)} {
- Because of some important changes to sqlite3_step(),
- we have decided to
- do an additional beta release prior to the first "stable" release.
- If no serious problems are discovered in this version, we will
- release version 3.0 "stable" in about a week.
-}
-
-
-newsitem {2004-Aug-29} {Version 3.0.5 (beta)} {
- The fourth beta release of SQLite version 3.0 is now available.
- The next release is expected to be called "stable".
-}
-
-
-newsitem {2004-Aug-08} {Version 3.0.4 (beta)} {
- The third beta release of SQLite version 3.0 is now available.
- This new beta fixes several bugs including a database corruption
- problem that can occur when doing a DELETE while a SELECT is pending.
- Expect at least one more beta before version 3.0 goes final.
-}
-
-newsitem {2004-July-22} {Version 3.0.3 (beta)} {
- The second beta release of SQLite version 3.0 is now available.
- This new beta fixes many bugs and adds support for databases with
- varying page sizes. The next 3.0 release will probably be called
- a final or stable release.
-
- Version 3.0 adds support for internationalization and a new
- more compact file format.
- <a href="version3.html">Details.</a>
- The API and file format have been fixed since 3.0.2. All
- regression tests pass (over 100000 tests) and the test suite
- exercises over 95% of the code.
-
- SQLite version 3.0 is made possible in part by AOL
- developers supporting and embracing great Open-Source Software.
-}
-
-newsitem {2004-Jly-22} {Version 2.8.15} {
- SQLite version 2.8.15 is a maintenance release for the version 2.8
- series. Version 2.8 continues to be maintained with bug fixes, but
- no new features will be added to version 2.8. All the changes in
- this release are minor. If you are not having problems, there is
- there is no reason to upgrade.
-}
-
-newsitem {2004-Jun-30} {Version 3.0.2 (beta) Released} {
- The first beta release of SQLite version 3.0 is now available.
- Version 3.0 adds support for internationalization and a new
- more compact file format.
- <a href="version3.html">Details.</a>
- As of this release, the API and file format are frozen. All
- regression tests pass (over 100000 tests) and the test suite
- exercises over 95% of the code.
-
- SQLite version 3.0 is made possible in part by AOL
- developers supporting and embracing great Open-Source Software.
-}
-
-
-newsitem {2004-Jun-25} {Website hacked} {
- The www.sqlite.org website was hacked sometime around 2004-Jun-22
- because the lead SQLite developer failed to properly patch CVS.
- Evidence suggests that the attacker was unable to elevate privileges
- above user "cvs". Nevertheless, as a precaution the entire website
- has been reconstructed from scratch on a fresh machine. All services
- should be back to normal as of 2004-Jun-28.
-}
-
-
-newsitem {2004-Jun-18} {Version 3.0.0 (alpha) Released} {
- The first alpha release of SQLite version 3.0 is available for
- public review and comment. Version 3.0 enhances internationalization support
- through the use of UTF-16 and user-defined text collating sequences.
- BLOBs can now be stored directly, without encoding.
- A new file format results in databases that are 25% smaller (depending
- on content). The code is also a little faster. In spite of the many
- new features, the library footprint is still less than 240KB
- (x86, gcc -O1).
- <a href="version3.html">Additional information</a>.
-
- Our intent is to freeze the file format and API on 2004-Jul-01.
- Users are encouraged to review and evaluate this alpha release carefully
- and submit any feedback prior to that date.
-
- The 2.8 series of SQLite will continue to be supported with bug
- fixes for the foreseeable future.
-}
-
-newsitem {2004-Jun-09} {Version 2.8.14 Released} {
- SQLite version 2.8.14 is a patch release to the stable 2.8 series.
- There is no reason to upgrade if 2.8.13 is working ok for you.
- This is only a bug-fix release. Most development effort is
- going into version 3.0.0 which is due out soon.
-}
-
-newsitem {2004-May-31} {CVS Access Temporarily Disabled} {
- Anonymous access to the CVS repository will be suspended
- for 2 weeks beginning on 2004-June-04. Everyone will still
- be able to download
- prepackaged source bundles, create or modify trouble tickets, or view
- change logs during the CVS service interruption. Full open access to the
- CVS repository will be restored on 2004-June-18.
-}
-
-newsitem {2004-Apr-23} {Work Begins On SQLite Version 3} {
- Work has begun on version 3 of SQLite. Version 3 is a major
- changes to both the C-language API and the underlying file format
- that will enable SQLite to better support internationalization.
- The first beta is schedule for release on 2004-July-01.
-
- Plans are to continue to support SQLite version 2.8 with
- bug fixes. But all new development will occur in version 3.0.
-}
-footer {$Id: oldnews.tcl,v 1.24 2007/11/05 18:11:18 drh Exp $}
+++ /dev/null
-#
-# Run this script to generated a omitted.html output file
-#
-set rcsid {$Id: omitted.tcl,v 1.10 2005/11/03 00:41:18 drh Exp $}
-source common.tcl
-header {SQL Features That SQLite Does Not Implement}
-puts {
-<h2>SQL Features That SQLite Does Not Implement</h2>
-
-<p>
-Rather than try to list all the features of SQL92 that SQLite does
-support, it is much easier to list those that it does not.
-Unsupported features of SQL92 are shown below.</p>
-
-<p>
-The order of this list gives some hint as to when a feature might
-be added to SQLite. Those features near the top of the list are
-likely to be added in the near future. There are no immediate
-plans to add features near the bottom of the list.
-</p>
-
-<table cellpadding="10">
-}
-
-proc feature {name desc} {
- puts "<tr><td valign=\"top\"><b><nobr>$name</nobr></b></td>"
- puts "<td width=\"10\"> </th>"
- puts "<td valign=\"top\">$desc</td></tr>"
-}
-
-feature {FOREIGN KEY constraints} {
- FOREIGN KEY constraints are parsed but are not enforced.
-}
-
-feature {Complete trigger support} {
- There is some support for triggers but it is not complete. Missing
- subfeatures include FOR EACH STATEMENT triggers (currently all triggers
- must be FOR EACH ROW), INSTEAD OF triggers on tables (currently
- INSTEAD OF triggers are only allowed on views), and recursive
- triggers - triggers that trigger themselves.
-}
-
-feature {Complete ALTER TABLE support} {
- Only the RENAME TABLE and ADD COLUMN variants of the
- ALTER TABLE command are supported. Other kinds of ALTER TABLE operations
- such as
- DROP COLUMN, ALTER COLUMN, ADD CONSTRAINT, and so forth are omitted.
-}
-
-feature {Nested transactions} {
- The current implementation only allows a single active transaction.
-}
-
-feature {RIGHT and FULL OUTER JOIN} {
- LEFT OUTER JOIN is implemented, but not RIGHT OUTER JOIN or
- FULL OUTER JOIN.
-}
-
-feature {Writing to VIEWs} {
- VIEWs in SQLite are read-only. You may not execute a DELETE, INSERT, or
- UPDATE statement on a view. But you can create a trigger
- that fires on an attempt to DELETE, INSERT, or UPDATE a view and do
- what you need in the body of the trigger.
-}
-
-feature {GRANT and REVOKE} {
- Since SQLite reads and writes an ordinary disk file, the
- only access permissions that can be applied are the normal
- file access permissions of the underlying operating system.
- The GRANT and REVOKE commands commonly found on client/server
- RDBMSes are not implemented because they would be meaningless
- for an embedded database engine.
-}
-
-puts {
-</table>
-
-<p>
-If you find other SQL92 features that SQLite does not support, please
-add them to the Wiki page at
-<a href="http://www.sqlite.org/cvstrac/wiki?p=UnsupportedSql">
-http://www.sqlite.org/cvstrac/wiki?p=Unsupported</a>
-</p>
-}
-footer $rcsid
+++ /dev/null
-#
-# Run this Tcl script to generate the sqlite.html file.
-#
-set rcsid {$Id: opcode.tcl,v 1.15 2005/03/09 12:26:51 danielk1977 Exp $}
-source common.tcl
-header {SQLite Virtual Machine Opcodes}
-puts {
-<h2>SQLite Virtual Machine Opcodes</h2>
-}
-
-set fd [open [lindex $argv 0] r]
-set file [read $fd [file size [lindex $argv 0]]]
-close $fd
-set current_op {}
-foreach line [split $file \n] {
- set line [string trim $line]
- if {[string index $line 1]!="*"} {
- set current_op {}
- continue
- }
- if {[regexp {^/\* Opcode: } $line]} {
- set current_op [lindex $line 2]
- set txt [lrange $line 3 end]
- regsub -all {>} $txt {\>} txt
- regsub -all {<} $txt {\<} txt
- set Opcode($current_op:args) $txt
- lappend OpcodeList $current_op
- continue
- }
- if {$current_op==""} continue
- if {[regexp {^\*/} $line]} {
- set current_op {}
- continue
- }
- set line [string trim [string range $line 3 end]]
- if {$line==""} {
- append Opcode($current_op:text) \n<p>
- } else {
- regsub -all {>} $line {\>} line
- regsub -all {<} $line {\<} line
- append Opcode($current_op:text) \n$line
- }
-}
-unset file
-
-puts {
-<h3>Introduction</h3>
-
-<p>In order to execute an SQL statement, the SQLite library first parses
-the SQL, analyzes the statement, then generates a short program to execute
-the statement. The program is generated for a "virtual machine" implemented
-by the SQLite library. This document describes the operation of that
-virtual machine.</p>
-
-<p>This document is intended as a reference, not a tutorial.
-A separate <a href="vdbe.html">Virtual Machine Tutorial</a> is
-available. If you are looking for a narrative description
-of how the virtual machine works, you should read the tutorial
-and not this document. Once you have a basic idea of what the
-virtual machine does, you can refer back to this document for
-the details on a particular opcode.
-Unfortunately, the virtual machine tutorial was written for
-SQLite version 1.0. There are substantial changes in the virtual
-machine for version 2.0 and the document has not been updated.
-</p>
-
-<p>The source code to the virtual machine is in the <b>vdbe.c</b> source
-file. All of the opcode definitions further down in this document are
-contained in comments in the source file. In fact, the opcode table
-in this document
-was generated by scanning the <b>vdbe.c</b> source file
-and extracting the necessary information from comments. So the
-source code comments are really the canonical source of information
-about the virtual machine. When in doubt, refer to the source code.</p>
-
-<p>Each instruction in the virtual machine consists of an opcode and
-up to three operands named P1, P2 and P3. P1 may be an arbitrary
-integer. P2 must be a non-negative integer. P2 is always the
-jump destination in any operation that might cause a jump.
-P3 is a null-terminated
-string or NULL. Some operators use all three operands. Some use
-one or two. Some operators use none of the operands.<p>
-
-<p>The virtual machine begins execution on instruction number 0.
-Execution continues until (1) a Halt instruction is seen, or
-(2) the program counter becomes one greater than the address of
-last instruction, or (3) there is an execution error.
-When the virtual machine halts, all memory
-that it allocated is released and all database cursors it may
-have had open are closed. If the execution stopped due to an
-error, any pending transactions are terminated and changes made
-to the database are rolled back.</p>
-
-<p>The virtual machine also contains an operand stack of unlimited
-depth. Many of the opcodes use operands from the stack. See the
-individual opcode descriptions for details.</p>
-
-<p>The virtual machine can have zero or more cursors. Each cursor
-is a pointer into a single table or index within the database.
-There can be multiple cursors pointing at the same index or table.
-All cursors operate independently, even cursors pointing to the same
-indices or tables.
-The only way for the virtual machine to interact with a database
-file is through a cursor.
-Instructions in the virtual
-machine can create a new cursor (Open), read data from a cursor
-(Column), advance the cursor to the next entry in the table
-(Next) or index (NextIdx), and many other operations.
-All cursors are automatically
-closed when the virtual machine terminates.</p>
-
-<p>The virtual machine contains an arbitrary number of fixed memory
-locations with addresses beginning at zero and growing upward.
-Each memory location can hold an arbitrary string. The memory
-cells are typically used to hold the result of a scalar SELECT
-that is part of a larger expression.</p>
-
-<p>The virtual machine contains a single sorter.
-The sorter is able to accumulate records, sort those records,
-then play the records back in sorted order. The sorter is used
-to implement the ORDER BY clause of a SELECT statement.</p>
-
-<p>The virtual machine contains a single "List".
-The list stores a list of integers. The list is used to hold the
-rowids for records of a database table that needs to be modified.
-The WHERE clause of an UPDATE or DELETE statement scans through
-the table and writes the rowid of every record to be modified
-into the list. Then the list is played back and the table is modified
-in a separate step.</p>
-
-<p>The virtual machine can contain an arbitrary number of "Sets".
-Each set holds an arbitrary number of strings. Sets are used to
-implement the IN operator with a constant right-hand side.</p>
-
-<p>The virtual machine can open a single external file for reading.
-This external read file is used to implement the COPY command.</p>
-
-<p>Finally, the virtual machine can have a single set of aggregators.
-An aggregator is a device used to implement the GROUP BY clause
-of a SELECT. An aggregator has one or more slots that can hold
-values being extracted by the select. The number of slots is the
-same for all aggregators and is defined by the AggReset operation.
-At any point in time a single aggregator is current or "has focus".
-There are operations to read or write to memory slots of the aggregator
-in focus. There are also operations to change the focus aggregator
-and to scan through all aggregators.</p>
-
-<h3>Viewing Programs Generated By SQLite</h3>
-
-<p>Every SQL statement that SQLite interprets results in a program
-for the virtual machine. But if you precede the SQL statement with
-the keyword "EXPLAIN" the virtual machine will not execute the
-program. Instead, the instructions of the program will be returned
-like a query result. This feature is useful for debugging and
-for learning how the virtual machine operates.</p>
-
-<p>You can use the <b>sqlite</b> command-line tool to see the
-instructions generated by an SQL statement. The following is
-an example:</p>}
-
-proc Code {body} {
- puts {<blockquote><tt>}
- regsub -all {&} [string trim $body] {\&} body
- regsub -all {>} $body {\>} body
- regsub -all {<} $body {\<} body
- regsub -all {\(\(\(} $body {<b>} body
- regsub -all {\)\)\)} $body {</b>} body
- regsub -all { } $body {\ } body
- regsub -all \n $body <br>\n body
- puts $body
- puts {</tt></blockquote>}
-}
-
-Code {
-$ (((sqlite ex1)))
-sqlite> (((.explain)))
-sqlite> (((explain delete from tbl1 where two<20;)))
-addr opcode p1 p2 p3
----- ------------ ----- ----- ----------------------------------------
-0 Transaction 0 0
-1 VerifyCookie 219 0
-2 ListOpen 0 0
-3 Open 0 3 tbl1
-4 Rewind 0 0
-5 Next 0 12
-6 Column 0 1
-7 Integer 20 0
-8 Ge 0 5
-9 Recno 0 0
-10 ListWrite 0 0
-11 Goto 0 5
-12 Close 0 0
-13 ListRewind 0 0
-14 OpenWrite 0 3
-15 ListRead 0 19
-16 MoveTo 0 0
-17 Delete 0 0
-18 Goto 0 15
-19 ListClose 0 0
-20 Commit 0 0
-}
-
-puts {
-<p>All you have to do is add the "EXPLAIN" keyword to the front of the
-SQL statement. But if you use the ".explain" command to <b>sqlite</b>
-first, it will set up the output mode to make the program more easily
-viewable.</p>
-
-<p>If <b>sqlite</b> has been compiled without the "-DNDEBUG=1" option
-(that is, with the NDEBUG preprocessor macro not defined) then you
-can put the SQLite virtual machine in a mode where it will trace its
-execution by writing messages to standard output. The non-standard
-SQL "PRAGMA" comments can be used to turn tracing on and off. To
-turn tracing on, enter:
-</p>
-
-<blockquote><pre>
-PRAGMA vdbe_trace=on;
-</pre></blockquote>
-
-<p>
-You can turn tracing back off by entering a similar statement but
-changing the value "on" to "off".</p>
-
-<h3>The Opcodes</h3>
-}
-
-puts "<p>There are currently [llength $OpcodeList] opcodes defined by
-the virtual machine."
-puts {All currently defined opcodes are described in the table below.
-This table was generated automatically by scanning the source code
-from the file <b>vdbe.c</b>.</p>}
-
-puts {
-<p><table cellspacing="1" border="1" cellpadding="10">
-<tr><th>Opcode Name</th><th>Description</th></tr>}
-foreach op [lsort -dictionary $OpcodeList] {
- puts {<tr><td valign="top" align="center">}
- puts "<a name=\"$op\">$op</a>"
- puts "<td>[string trim $Opcode($op:text)]</td></tr>"
-}
-puts {</table></p>}
-footer $rcsid
+++ /dev/null
-#
-# Run this TCL script to generate HTML for the goals.html file.
-#
-set rcsid {$Id: optimizer.tcl,v 1.1 2005/08/30 22:44:06 drh Exp $}
-source common.tcl
-header {The SQLite Query Optimizer}
-
-proc CODE {text} {
- puts "<blockquote><pre>"
- puts $text
- puts "</pre></blockquote>"
-}
-proc IMAGE {name {caption {}}} {
- puts "<center><img src=\"$name\">"
- if {$caption!=""} {
- puts "<br>$caption"
- }
- puts "</center>"
-}
-proc PARAGRAPH {text} {
- puts "<p>$text</p>\n"
-}
-proc HEADING {level name} {
- puts "<h$level>$name</h$level>"
-}
-
-HEADING 1 {The SQLite Query Optimizer}
-
-PARAGRAPH {
- This article describes how the SQLite query optimizer works.
- This is not something you have to know in order to use SQLite - many
- programmers use SQLite successfully without the slightest hint of what
- goes on in the inside.
- But a basic understanding of what SQLite is doing
- behind the scenes will help you to write more efficient SQL. And the
- knowledge gained by studying the SQLite query optimizer has broad
- application since most other relational database engines operate
- similarly.
- A solid understanding of how the query optimizer works is also
- required before making meaningful changes or additions to the SQLite, so
- this article should be read closely by anyone aspiring
- to hack the source code.
-}
-
-HEADING 2 Background
-
-PARAGRAPH {
- It is important to understand that SQL is a programming language.
- SQL is a perculiar programming language in that it
- describes <u>what</u> the programmer wants to compute not <u>how</u>
- to compute it as most other programming languages do.
- But perculiar or not, SQL is still just a programming language.
-}
-
-PARAGRAPH {
- It is very helpful to think of each SQL statement as a separate
- program.
- An important job of the SQL database engine is to translate each
- SQL statement from its descriptive form that specifies what the
- information is desired (the <u>what</u>)
- into a procedural form that specifies how to go
- about acquiring the desired information (the <u>how</u>).
- The task of translating the <u>what</u> into a
- <u>how</u> is assigned to the query optimizer.
-}
-
-PARAGRAPH {
- The beauty of SQL comes from the fact that the optimizer frees the programmer
- from having to worry over the details of <u>how</u>. The programmer
- only has to specify the <u>what</u> and then leave the optimizer
- to deal with all of the minutae of implementing the
- <u>how</u>. Thus the programmer is able to think and work at a
- much higher level and leave the optimizer to stress over the low-level
- work.
-}
-
-HEADING 2 {Database Layout}
-
-PARAGRAPH {
- An SQLite database consists of one or more "b-trees".
- Each b-tree contains zero or more "rows".
- A single row contains a "key" and some "data".
- In general, both the key and the data are arbitrary binary
- data of any length.
- The keys must all be unique within a single b-tree.
- Rows are stored in order of increasing key values - each
- b-tree has a comparision functions for keys that determines
- this order.
-}
-
-PARAGRAPH {
- In SQLite, each SQL table is stored as a b-tree where the
- key is a 64-bit integer and the data is the content of the
- table row. The 64-bit integer key is the ROWID. And, of course,
- if the table has an INTEGER PRIMARY KEY, then that integer is just
- an alias for the ROWID.
-}
-
-PARAGRAPH {
- Consider the following block of SQL code:
-}
-
-CODE {
- CREATE TABLE ex1(
- id INTEGER PRIMARY KEY,
- x VARCHAR(30),
- y INTEGER
- );
- INSERT INTO ex1 VALUES(NULL,'abc',12345);
- INSERT INTO ex1 VALUES(NULL,456,'def');
- INSERT INTO ex1 VALUES(100,'hello','world');
- INSERT INTO ex1 VALUES(-5,'abc','xyz');
- INSERT INTO ex1 VALUES(54321,NULL,987);
-}
-
-PARAGRAPH {
- This code generates a new b-tree (named "ex1") containing 5 rows.
- This table can be visualized as follows:
-}
-IMAGE table-ex1b2.gif
-
-PARAGRAPH {
- Note that the key for each row if the b-tree is the INTEGER PRIMARY KEY
- for that row. (Remember that the INTEGER PRIMARY KEY is just an alias
- for the ROWID.) The other fields of the table form the data for each
- entry in the b-tree. Note also that the b-tree entries are in ROWID order
- which is different from the order that they were originally inserted.
-}
-
-PARAGRAPH {
- Now consider the following SQL query:
-}
-CODE {
- SELECT y FROM ex1 WHERE x=456;
-}
-
-PARAGRAPH {
- When the SQLite parser and query optimizer are handed this query, they
- have to translate it into a procedure that will find the desired result.
- In this case, they do what is call a "full table scan". They start
- at the beginning of the b-tree that contains the table and visit each
- row. Within each row, the value of the "x" column is tested and when it
- is found to match 456, the value of the "y" column is output.
- We can represent this procedure graphically as follows:
-}
-IMAGE fullscanb.gif
-
-PARAGRAPH {
- A full table scan is the access method of last resort. It will always
- work. But if the table contains millions of rows and you are only looking
- a single one, it might take a very long time to find the particular row
- you are interested in.
- In particular, the time needed to access a single row of the table is
- proportional to the total number of rows in the table.
- So a big part of the job of the optimizer is to try to find ways to
- satisfy the query without doing a full table scan.
-}
-PARAGRAPH {
- The usual way to avoid doing a full table scan is use a binary search
- to find the particular row or rows of interest in the table.
- Consider the next query which searches on rowid instead of x:
-}
-CODE {
- SELECT y FROM ex1 WHERE rowid=2;
-}
-
-PARAGRAPH {
- In the previous query, we could not use a binary search for x because
- the values of x were not ordered. But the rowid values are ordered.
- So instead of having to visit every row of the b-tree looking for one
- that has a rowid value of 2, we can do a binary search for that particular
- row and output its corresponding y value. We show this graphically
- as follows:
-}
-IMAGE direct1b.gif
-
-PARAGRAPH {
- When doing a binary search, we only have to look at a number of
- rows with is proportional to the logorithm of the number of entries
- in the table. For a table with just 5 entires as in the example above,
- the difference between a full table scan and a binary search is
- negligible. In fact, the full table scan might be faster. But in
- a database that has 5 million rows, a binary search will be able to
- find the desired row in only about 23 tries, whereas the full table
- scan will need to look at all 5 million rows. So the binary search
- is about 200,000 times faster in that case.
-}
-PARAGRAPH {
- A 200,000-fold speed improvement is huge. So we always want to do
- a binary search rather than a full table scan when we can.
-}
-PARAGRAPH {
- The problem with a binary search is that the it only works if the
- fields you are search for are in sorted order. So we can do a binary
- search when looking up the rowid because the rows of the table are
- sorted by rowid. But we cannot use a binary search when looking up
- x because the values in the x column are in no particular order.
-}
-PARAGRAPH {
- The way to work around this problem and to permit binary searching on
- fields like x is to provide an index.
- An index is another b-tree.
- But in the index b-tree the key is not the rowid but rather the field
- or fields being indexed followed by the rowid.
- The data in an index b-tree is empty - it is not needed or used.
- The following diagram shows an index on the x field of our example table:
-}
-IMAGE index-ex1-x-b.gif
-
-PARAGRAPH {
- An important point to note in the index are that they keys of the
- b-tree are in sorted order. (Recall that NULL values in SQLite sort
- first, followed by numeric values in numerical order, then strings, and
- finally BLOBs.) This is the property that will allow use to do a
- binary search for the field x. The rowid is also included in every
- key for two reasons. First, by including the rowid we guarantee that
- every key will be unique. And second, the rowid will be used to look
- up the actual table entry after doing the binary search. Finally, note
- that the data portion of the index b-tree serves no purpose and is thus
- kept empty to save space in the disk file.
-}
-PARAGRAPH {
- Remember what the original query example looked like:
-}
-CODE {
- SELECT y FROM ex1 WHERE x=456;
-}
-
-PARAGRAPH {
- The first time this query was encountered we had to do a full table
- scan. But now that we have an index on x, we can do a binary search
- on that index for the entry where x==456. Then from that entry we
- can find the rowid value and use the rowid to look up the corresponding
- entry in the original table. From the entry in the original table,
- we can find the value y and return it as our result. The following
- diagram shows this process graphically:
-}
-IMAGE indirect1b1.gif
-
-PARAGRAPH {
- With the index, we are able to look up an entry based on the value of
- x after visiting only a logorithmic number of b-tree entries. Unlike
- the case where we were searching using rowid, we have to do two binary
- searches for each output row. But for a 5-million row table, that is
- still only 46 searches instead of 5 million for a 100,000-fold speedup.
-}
-
-HEADING 3 {Parsing The WHERE Clause}
-
-
-
-# parsing the where clause
-# rowid lookup
-# index lookup
-# index lookup without the table
-# how an index is chosen
-# joins
-# join reordering
-# order by using an index
-# group by using an index
-# OR -> IN optimization
-# Bitmap indices
-# LIKE and GLOB optimization
-# subquery flattening
-# MIN and MAX optimizations
+++ /dev/null
-set rcsid {$Id: optimizing.tcl,v 1.1 2005/01/17 03:42:52 drh Exp $}
-source common.tcl
-header {Hints For Optimizing Queries In SQLite}
-proc section {level tag name} {
- incr level
- if {$level>6} {set level 6}
- puts "\n"<a name=\"tag\" />"
- puts "<h$level>$name</h$level>\n"
-}
-section 1 recompile {Recompile the library for optimal performance}
-section 2 avoidtrans {Minimize the number of transactions}
-section 3 usebind {Use sqlite3_bind to insert large chunks of data}
-section 4 useindices {Use appropriate indices}
-section 5 recordjoin {Reorder the tables in a join}
-footer $rcsid
+++ /dev/null
-#
-# Run this TCL script to generate HTML for the goals.html file.
-#
-set rcsid {$Id: optoverview.tcl,v 1.5 2005/11/24 13:15:34 drh Exp $}
-source common.tcl
-header {The SQLite Query Optimizer Overview}
-
-proc CODE {text} {
- puts "<blockquote><pre>"
- puts $text
- puts "</pre></blockquote>"
-}
-proc SYNTAX {text} {
- puts "<blockquote><pre>"
- set t2 [string map {& & < < > >} $text]
- regsub -all "/(\[^\n/\]+)/" $t2 {</b><i>\1</i><b>} t3
- puts "<b>$t3</b>"
- puts "</pre></blockquote>"
-}
-proc IMAGE {name {caption {}}} {
- puts "<center><img src=\"$name\">"
- if {$caption!=""} {
- puts "<br>$caption"
- }
- puts "</center>"
-}
-proc PARAGRAPH {text} {
- # regsub -all "/(\[a-zA-Z0-9\]+)/" $text {<i>\1</i>} t2
- regsub -all "\\*(\[^\n*\]+)\\*" $text {<tt><b><big>\1</big></b></tt>} t3
- puts "<p>$t3</p>\n"
-}
-set level(0) 0
-set level(1) 0
-proc HEADING {n name {tag {}}} {
- if {$tag!=""} {
- puts "<a name=\"$tag\">"
- }
- global level
- incr level($n)
- for {set i [expr {$n+1}]} {$i<10} {incr i} {
- set level($i) 0
- }
- if {$n==0} {
- set num {}
- } elseif {$n==1} {
- set num $level(1).0
- } else {
- set num $level(1)
- for {set i 2} {$i<=$n} {incr i} {
- append num .$level($i)
- }
- }
- incr n 1
- puts "<h$n>$num $name</h$n>"
-}
-
-HEADING 0 {The SQLite Query Optimizer Overview}
-
-PARAGRAPH {
- This document provides a terse overview of how the query optimizer
- for SQLite works. This is not a tutorial. The reader is likely to
- need some prior knowledge of how database engines operate
- in order to fully understand this text.
-}
-
-HEADING 1 {WHERE clause analysis} where_clause
-
-PARAGRAPH {
- The WHERE clause on a query is broken up into "terms" where each term
- is separated from the others by an AND operator.
-}
-PARAGRAPH {
- All terms of the WHERE clause are analyzed to see if they can be
- satisfied using indices.
- Terms that cannot be satisfied through the use of indices become
- tests that are evaluated against each row of the relevant input
- tables. No tests are done for terms that are completely satisfied by
- indices. Sometimes
- one or more terms will provide hints to indices but still must be
- evaluated against each row of the input tables.
-}
-
-PARAGRAPH {
- The analysis of a term might cause new "virtual" terms to
- be added to the WHERE clause. Virtual terms can be used with
- indices to restrict a search. But virtual terms never generate code
- that is tested against input rows.
-}
-
-PARAGRAPH {
- To be usable by an index a term must be of one of the following
- forms:
-}
-SYNTAX {
- /column/ = /expression/
- /column/ > /expression/
- /column/ >= /expression/
- /column/ < /expression/
- /column/ <= /expression/
- /expression/ = /column/
- /expression/ > /column/
- /expression/ >= /column/
- /expression/ < /column/
- /expression/ <= /column/
- /column/ IN (/expression-list/)
- /column/ IN (/subquery/)
-}
-PARAGRAPH {
- If an index is created using a statement like this:
-}
-CODE {
- CREATE INDEX idx_ex1 ON ex1(a,b,c,d,e,...,y,z);
-}
-PARAGRAPH {
- Then the index might be used if the initial columns of the index
- (columns a, b, and so forth) appear in WHERE clause terms.
- All index columns must be used with
- the *=* or *IN* operators except for
- the right-most column which can use inequalities. For the right-most
- column of an index that is used, there can be up to two inequalities
- that must sandwich the allowed values of the column between two extremes.
-}
-PARAGRAPH {
- It is not necessary for every column of an index to appear in a
- WHERE clause term in order for that index to be used.
- But there can not be gaps in the columns of the index that are used.
- Thus for the example index above, if there is no WHERE clause term
- that constraints column c, then terms that constraint columns a and b can
- be used with the index but not terms that constraint columns d through z.
- Similarly, no index column will be used (for indexing purposes)
- that is to the right of a
- column that is constrained only by inequalities.
- For the index above and WHERE clause like this:
-}
-CODE {
- ... WHERE a=5 AND b IN (1,2,3) AND c>12 AND d='hello'
-}
-PARAGRAPH {
- Only columns a, b, and c of the index would be usable. The d column
- would not be usable because it occurs to the right of c and c is
- constrained only by inequalities.
-}
-
-HEADING 1 {The BETWEEN optimization} between_opt
-
-PARAGRAPH {
- If a term of the WHERE clause is of the following form:
-}
-SYNTAX {
- /expr1/ BETWEEN /expr2/ AND /expr3/
-}
-PARAGRAPH {
- Then two virtual terms are added as follows:
-}
-SYNTAX {
- /expr1/ >= /expr2/ AND /expr1/ <= /expr3/
-}
-PARAGRAPH {
- If both virtual terms end up being used as constraints on an index,
- then the original BETWEEN term is omitted and the corresponding test
- is not performed on input rows.
- Thus if the BETWEEN term ends up being used as an index constraint
- no tests are ever performed on that term.
- On the other hand, the
- virtual terms themselves never causes tests to be performed on
- input rows.
- Thus if the BETWEEN term is not used as an index constraint and
- instead must be used to test input rows, the <i>expr1</i> expression is
- only evaluated once.
-}
-
-HEADING 1 {The OR optimization} or_opt
-
-PARAGRAPH {
- If a term consists of multiple subterms containing a common column
- name and separated by OR, like this:
-}
-SYNTAX {
- /column/ = /expr1/ OR /column/ = /expr2/ OR /column/ = /expr3/ OR ...
-}
-PARAGRAPH {
- Then the term is rewritten as follows:
-}
-SYNTAX {
- /column/ IN (/expr1/,/expr2/,/expr3/,/expr4/,...)
-}
-PARAGRAPH {
- The rewritten term then might go on to constraint an index using the
- normal rules for *IN* operators.
- Note that <i>column</i> must be the same column in every OR-connected subterm,
- although the column can occur on either the left or the right side of
- the *=* operator.
-}
-
-HEADING 1 {The LIKE optimization} like_opt
-
-PARAGRAPH {
- Terms that are composed of the LIKE or GLOB operator
- can sometimes be used to constrain indices.
- There are many conditions on this use:
-}
-PARAGRAPH {
- <ol>
- <li>The left-hand side of the LIKE or GLOB operator must be the name
- of an indexed column.</li>
- <li>The right-hand side of the LIKE or GLOB must be a string literal
- that does not begin with a wildcard character.</li>
- <li>The ESCAPE clause cannot appear on the LIKE operator.</li>
- <li>The build-in functions used to implement LIKE and GLOB must not
- have been overloaded using the sqlite3_create_function() API.</li>
- <li>For the GLOB operator, the column must use the default BINARY
- collating sequence.</li>
- <li>For the LIKE operator, if case_sensitive_like mode is enabled then
- the column must use the default BINARY collating sequence, or if
- case_sensitive_like mode is disabled then the column must use the
- built-in NOCASE collating sequence.</li>
- </ol>
-}
-PARAGRAPH {
- The LIKE operator has two modes that can be set by a pragma. The
- default mode is for LIKE comparisons to be insensitive to differences
- of case for latin1 characters. Thus, by default, the following
- expression is true:
-}
-CODE {
- 'a' LIKE 'A'
-}
-PARAGRAPH {
- By turned on the case_sensitive_like pragma as follows:
-}
-CODE {
- PRAGMA case_sensitive_like=ON;
-}
-PARAGRAPH {
- Then the LIKE operator pays attention to case and the example above would
- evaluate to false. Note that case insensitivity only applies to
- latin1 characters - basically the upper and lower case letters of English
- in the lower 127 byte codes of ASCII. International character sets
- are case sensitive in SQLite unless a user-supplied collating
- sequence is used. But if you employ a user-supplied collating sequence,
- the LIKE optimization describe here will never be taken.
-}
-PARAGRAPH {
- The LIKE operator is case insensitive by default because this is what
- the SQL standard requires. You can change the default behavior at
- compile time by using the -DSQLITE_CASE_SENSITIVE_LIKE command-line option
- to the compiler.
-}
-PARAGRAPH {
- The LIKE optimization might occur if the column named on the left of the
- operator uses the BINARY collating sequence (which is the default) and
- case_sensitive_like is turned on. Or the optimization might occur if
- the column uses the built-in NOCASE collating sequence and the
- case_sensitive_like mode is off. These are the only two combinations
- under which LIKE operators will be optimized. If the column on the
- right-hand side of the LIKE operator uses any collating sequence other
- than the built-in BINARY and NOCASE collating sequences, then no optimizations
- will ever be attempted on the LIKE operator.
-}
-PARAGRAPH {
- The GLOB operator is always case sensitive. The column on the left side
- of the GLOB operator must always use the built-in BINARY collating sequence
- or no attempt will be made to optimize that operator with indices.
-}
-PARAGRAPH {
- The right-hand side of the GLOB or LIKE operator must be a literal string
- value that does not begin with a wildcard. If the right-hand side is a
- parameter that is bound to a string, then no optimization is attempted.
- If the right-hand side begins with a wildcard character then no
- optimization is attempted.
-}
-PARAGRAPH {
- Suppose the initial sequence of non-wildcard characters on the right-hand
- side of the LIKE or GLOB operator is <i>x</i>. We are using a single
- character to denote this non-wildcard prefix but the reader should
- understand that the prefix can consist of more than 1 character.
- Let <i>y</i> the smallest string that is the same length as /x/ but which
- compares greater than <i>x</i>. For example, if <i>x</i> is *hello* then
- <i>y</i> would be *hellp*.
- The LIKE and GLOB optimizations consist of adding two virtual terms
- like this:
-}
-SYNTAX {
- /column/ >= /x/ AND /column/ < /y/
-}
-PARAGRAPH {
- Under most circumstances, the original LIKE or GLOB operator is still
- tested against each input row even if the virtual terms are used to
- constrain an index. This is because we do not know what additional
- constraints may be imposed by characters to the right
- of the <i>x</i> prefix. However, if there is only a single global wildcard
- to the right of <i>x</i>, then the original LIKE or GLOB test is disabled.
- In other words, if the pattern is like this:
-}
-SYNTAX {
- /column/ LIKE /x/%
- /column/ GLOB /x/*
-}
-PARAGRAPH {
- Then the original LIKE or GLOB tests are disabled when the virtual
- terms constrain an index because in that case we know that all of the
- rows selected by the index will pass the LIKE or GLOB test.
-}
-
-HEADING 1 {Joins} joins
-
-PARAGRAPH {
- The current implementation of
- SQLite uses only loop joins. That is to say, joins are implemented as
- nested loops.
-}
-PARAGRAPH {
- The default order of the nested loops in a join is for the left-most
- table in the FROM clause to form the outer loop and the right-most
- table to form the inner loop.
- However, SQLite will nest the loops in a different order if doing so
- will help it to select better indices.
-}
-PARAGRAPH {
- Inner joins can be freely reordered. However a left outer join is
- neither commutative nor associative and hence will not be reordered.
- Inner joins to the left and right of the outer join might be reordered
- if the optimizer thinks that is advantageous but the outer joins are
- always evaluated in the order in which they occur.
-}
-PARAGRAPH {
- When selecting the order of tables in a join, SQLite uses a greedy
- algorithm that runs in polynomial time.
-}
-PARAGRAPH {
- The ON and USING clauses of a join are converted into additional
- terms of the WHERE clause prior to WHERE clause analysis described
- above in paragraph 1.0. Thus
- with SQLite, there is no advantage to use the newer SQL92 join syntax
- over the older SQL89 comma-join syntax. They both end up accomplishing
- exactly the same thing.
-}
-PARAGRAPH {
- Join reordering is automatic and usually works well enough that
- programmer do not have to think about it. But occasionally some
- hints from the programmer are needed. For a description of when
- hints might be necessary and how to provide those hints, see the
- <a href="http://www.sqlite.org/cvstrac/wiki?p=QueryPlans">QueryPlans</a>
- page in the Wiki.
-}
-
-HEADING 1 {Choosing between multiple indices} multi_index
-
-PARAGRAPH {
- Each table in the FROM clause of a query can use at most one index,
- and SQLite strives to use at least one index on each table. Sometimes,
- two or more indices might be candidates for use on a single table.
- For example:
-}
-CODE {
- CREATE TABLE ex2(x,y,z);
- CREATE INDEX ex2i1 ON ex2(x);
- CREATE INDEX ex2i2 ON ex2(y);
- SELECT z FROM ex2 WHERE x=5 AND y=6;
-}
-PARAGRAPH {
- For the SELECT statement above, the optimizer can use the ex2i1 index
- to lookup rows of ex2 that contain x=5 and then test each row against
- the y=6 term. Or it can use the ex2i2 index to lookup rows
- of ex2 that contain y=6 then test each of those rows against the
- x=5 term.
-}
-PARAGRAPH {
- When faced with a choice of two or more indices, SQLite tries to estimate
- the total amount of work needed to perform the query using each option.
- It then selects the option that gives the least estimated work.
-}
-PARAGRAPH {
- To help the optimizer get a more accurate estimate of the work involved
- in using various indices, the user may optional run the ANALYZE command.
- The ANALYZE command scans all indices of database where there might
- be a choice between two or more indices and gathers statistics on the
- selectiveness of those indices. The results of this scan are stored
- in the sqlite_stat1 table.
- The contents of the sqlite_stat1 table are not updated as the database
- changes so after making significant changes it might be prudent to
- rerun ANALYZE.
- The results of an ANALYZE command are only available to database connections
- that are opened after the ANALYZE command completes.
-}
-PARAGRAPH {
- Once created, the sqlite_stat1 table cannot be dropped. But its
- content can be viewed, modified, or erased. Erasing the entire content
- of the sqlite_stat1 table has the effect of undoing the ANALYZE command.
- Changing the content of the sqlite_stat1 table can get the optimizer
- deeply confused and cause it to make silly index choices. Making
- updates to the sqlite_stat1 table (except by running ANALYZE) is
- not recommended.
-}
-PARAGRAPH {
- Terms of the WHERE clause can be manually disqualified for use with
- indices by prepending a unary *+* operator to the column name. The
- unary *+* is a no-op and will not slow down the evaluation of the test
- specified by the term.
- But it will prevent the term from constraining an index.
- So, in the example above, if the query were rewritten as:
-}
-CODE {
- SELECT z FROM ex2 WHERE +x=5 AND y=6;
-}
-PARAGRAPH {
- The *+* operator on the *x* column would prevent that term from
- constraining an index. This would force the use of the ex2i2 index.
-}
-
-HEADING 1 {Avoidance of table lookups} index_only
-
-PARAGRAPH {
- When doing an indexed lookup of a row, the usual procedure is to
- do a binary search on the index to find the index entry, then extract
- the rowid from the index and use that rowid to do a binary search on
- the original table. Thus a typical indexed lookup involves two
- binary searches.
- If, however, all columns that were to be fetched from the table are
- already available in the index itself, SQLite will use the values
- contained in the index and will never look up the original table
- row. This saves one binary search for each row and can make many
- queries run twice as fast.
-}
-
-HEADING 1 {ORDER BY optimizations} order_by
-
-PARAGRAPH {
- SQLite attempts to use an index to satisfy the ORDER BY clause of a
- query when possible.
- When faced with the choice of using an index to satisfy WHERE clause
- constraints or satisfying an ORDER BY clause, SQLite does the same
- work analysis described in section 6.0
- and chooses the index that it believes will result in the fastest answer.
-
-}
-
-HEADING 1 {Subquery flattening} flattening
-
-PARAGRAPH {
- When a subquery occurs in the FROM clause of a SELECT, the default
- behavior is to evaluate the subquery into a transient table, then run
- the outer SELECT against the transient table.
- This is problematic since the transient table will not have any indices
- and the outer query (which is likely a join) will be forced to do a
- full table scan on the transient table.
-}
-PARAGRAPH {
- To overcome this problem, SQLite attempts to flatten subqueries in
- the FROM clause of a SELECT.
- This involves inserting the FROM clause of the subquery into the
- FROM clause of the outer query and rewriting expressions in
- the outer query that refer to the result set of the subquery.
- For example:
-}
-CODE {
- SELECT a FROM (SELECT x+y AS a FROM t1 WHERE z<100) WHERE a>5
-}
-PARAGRAPH {
- Would be rewritten using query flattening as:
-}
-CODE {
- SELECT x+y AS a FROM t1 WHERE z<100 AND a>5
-}
-PARAGRAPH {
- There is a long list of conditions that must all be met in order for
- query flattening to occur.
-}
-PARAGRAPH {
- <ol>
- <li> The subquery and the outer query do not both use aggregates.</li>
- <li> The subquery is not an aggregate or the outer query is not a join. </li>
- <li> The subquery is not the right operand of a left outer join, or
- the subquery is not itself a join. </li>
- <li> The subquery is not DISTINCT or the outer query is not a join. </li>
- <li> The subquery is not DISTINCT or the outer query does not use
- aggregates. </li>
- <li> The subquery does not use aggregates or the outer query is not
- DISTINCT. </li>
- <li> The subquery has a FROM clause. </li>
- <li> The subquery does not use LIMIT or the outer query is not a join. </li>
- <li> The subquery does not use LIMIT or the outer query does not use
- aggregates. </li>
- <li> The subquery does not use aggregates or the outer query does not
- use LIMIT. </li>
- <li> The subquery and the outer query do not both have ORDER BY clauses.</li>
- <li> The subquery is not the right term of a LEFT OUTER JOIN or the
- subquery has no WHERE clause. </li>
- </ol>
-}
-PARAGRAPH {
- The proof that query flattening may safely occur if all of the the
- above conditions are met is left as an exercise to the reader.
-}
-PARAGRAPH {
- Query flattening is an important optimization when views are used as
- each use of a view is translated into a subquery.
-}
-
-HEADING 1 {The MIN/MAX optimization} minmax
-
-PARAGRAPH {
- Queries of the following forms will be optimized to run in logarithmic
- time assuming appropriate indices exist:
-}
-CODE {
- SELECT MIN(x) FROM table;
- SELECT MAX(x) FROM table;
-}
-PARAGRAPH {
- In order for these optimizations to occur, they must appear in exactly
- the form shown above - changing only the name of the table and column.
- It is not permissible to add a WHERE clause or do any arithmetic on the
- result. The result set must contain a single column.
- The column in the MIN or MAX function must be an indexed column.
-}
+++ /dev/null
-#
-# Run this Tcl script to generate the pragma.html file.
-#
-set rcsid {$Id: pragma.tcl,v 1.28 2007/08/28 08:19:49 danielk1977 Exp $}
-source common.tcl
-header {Pragma statements supported by SQLite}
-
-proc Section {name {label {}}} {
- puts "\n<hr />"
- if {$label!=""} {
- puts "<a name=\"$label\"></a>"
- }
- puts "<h1>$name</h1>\n"
-}
-
-puts {
-<p>The <a href="#syntax">PRAGMA command</a> is a special command used to
-modify the operation of the SQLite library or to query the library for
-internal (non-table) data. The PRAGMA command is issued using the same
-interface as other SQLite commands (e.g. SELECT, INSERT) but is
-different in the following important respects:
-</p>
-<ul>
-<li>Specific pragma statements may be removed and others added in future
- releases of SQLite. Use with caution!
-<li>No error messages are generated if an unknown pragma is issued.
- Unknown pragmas are simply ignored. This means if there is a typo in
- a pragma statement the library does not inform the user of the fact.
-<li>Some pragmas take effect during the SQL compilation stage, not the
- execution stage. This means if using the C-language sqlite3_prepare(),
- sqlite3_step(), sqlite3_finalize() API (or similar in a wrapper
- interface), the pragma may be applied to the library during the
- sqlite3_prepare() call.
-<li>The pragma command is unlikely to be compatible with any other SQL
- engine.
-</ul>
-
-<p>The available pragmas fall into four basic categories:</p>
-<ul>
-<li>Pragmas used to <a href="#modify">modify the operation</a> of the
- SQLite library in some manner, or to query for the current mode of
- operation.
-<li>Pragmas used to <a href="#schema">query the schema</a> of the current
- database.
-<li>Pragmas used to <a href="#version">query or modify the databases two
- version values</a>, the schema-version and the user-version.
-<li>Pragmas used to <a href="#debug">debug the library</a> and verify that
- database files are not corrupted.
-</ul>
-}
-
-Section {PRAGMA command syntax} syntax
-
-Syntax {sql-statement} {
-PRAGMA <name> [= <value>] |
-PRAGMA <function>(<arg>)
-}
-
-puts {
-<p>The pragmas that take an integer <b><i>value</i></b> also accept
-symbolic names. The strings "<b>on</b>", "<b>true</b>", and "<b>yes</b>"
-are equivalent to <b>1</b>. The strings "<b>off</b>", "<b>false</b>",
-and "<b>no</b>" are equivalent to <b>0</b>. These strings are case-
-insensitive, and do not require quotes. An unrecognized string will be
-treated as <b>1</b>, and will not generate an error. When the <i>value</i>
-is returned it is as an integer.</p>
-}
-
-Section {Pragmas to modify library operation} modify
-
-puts {
-<ul>
-<a name="pragma_auto_vacuum"></a>
-<li><p><b>PRAGMA auto_vacuum;<br>
- PRAGMA auto_vacuum = </b>
- <i>0 | none | 1 | full | 2 | incremental</i><b>;</b></p>
- <p>Query or set the auto-vacuum flag in the database.</p>
-
- <p>Normally, (that is to say when auto_vacuum is 0 or "none")
- when a transaction that deletes data from a database is
- committed, the database file remains the same size. Unused database file
- pages are added to a "freelist" are reused for subsequent inserts. The
- database file does not shrink.
- In this mode the <a href="lang_vacuum.html">VACUUM</a>
- command can be used to reclaim unused space.</p>
-
- <p>When the auto-vacuum flag is 1 (full), the freelist pages are
- moved to the end of the file and the file is truncated to remove
- the freelist pages at every commit.
- Note, however, that auto-vacuum only truncates the freelist pages
- from the file. Auto-vacuum does not defragment the database nor
- repack individual database pages the way that the
- <a href="lang_vacuum.html">VACUUM</a> command does. In fact, because
- it moves pages around within the file, auto-vacuum can actually
- make fragmentation worse.</p>
-
- <p>Auto-vacuuming is only possible if the database stores some
- additional information that allows each database page to be
- traced backwards to its referer. Therefore, auto-vacuuming must
- be turned on before any tables are created. It is not possible
- to enable or disable auto-vacuum after a table has been created.</p>
-
- <p>When the value of auto-vacuum is 2 (incremental) then the additional
- information needed to do autovacuuming is stored in the database file
- but autovacuuming does not occur automatically at each commit as it
- does with auto_vacuum==full. In incremental mode, the separate
- <a href="#pragma_incremental_vacuum">incremental_vacuum</a> pragma must
- be invoked to cause the vacuum to occur.</p>
-
- <p>The database connection can be changed between full and incremental
- autovacuum mode at will. However, the connection cannot be changed
- in and out of the "none" mode after any table has been created in the
- database.
- </p></li>
-
-<a name="pragma_cache_size"></a>
-<li><p><b>PRAGMA cache_size;
- <br>PRAGMA 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 about 1.5K of memory.
- The default cache size is 2000. If you are doing UPDATEs or DELETEs
- that change many rows of a database and you do not mind if SQLite
- uses more memory, you can increase the cache size for a possible speed
- improvement.</p>
- <p>When you change the cache size using the cache_size pragma, the
- change only endures for the current session. The cache size reverts
- to the default value when the database is closed and reopened. Use
- the <a href="#pragma_default_cache_size"><b>default_cache_size</b></a>
- pragma to check the cache size permanently.</p></li>
-
-<a name="pragma_case_sensitive_like"></a>
-<li><p><b>PRAGMA case_sensitive_like;
- <br>PRAGMA case_sensitive_like = </b><i>0 | 1</i><b>;</b></p>
- <p>The default behavior of the LIKE operator is to ignore case
- for latin1 characters. Hence, by default <b>'a' LIKE 'A'</b> is
- true. The case_sensitive_like pragma can be turned on to change
- this behavior. When case_sensitive_like is enabled,
- <b>'a' LIKE 'A'</b> is false but <b>'a' LIKE 'a'</b> is still true.</p>
- </li>
-
-<a name="pragma_count_changes"></a>
-<li><p><b>PRAGMA count_changes;
- <br>PRAGMA count_changes = </b><i>0 | 1</i><b>;</b></p>
- <p>Query or change the count-changes flag. Normally, when the
- count-changes flag is not set, INSERT, UPDATE and DELETE statements
- return no data. When count-changes is set, each of these commands
- returns a single row of data consisting of one integer value - the
- number of rows inserted, modified or deleted by the command. The
- returned change count does not include any insertions, modifications
- or deletions performed by triggers.</p>
-
-<a name="pragma_default_cache_size"></a>
-<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>
- 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
- every time you reopen the database.</p></li>
-
-<a name="pragma_default_synchronous"></a>
-<li><p><b>PRAGMA default_synchronous;</b></p>
- <p>This pragma was available in version 2.8 but was removed in version
- 3.0. It is a dangerous pragma whose use is discouraged. To help
- dissuide users of version 2.8 from employing this pragma, the documentation
- will not tell you what it does.</p></li>
-
-
-<a name="pragma_empty_result_callbacks"></a>
-<li><p><b>PRAGMA empty_result_callbacks;
- <br>PRAGMA empty_result_callbacks = </b><i>0 | 1</i><b>;</b></p>
- <p>Query or change the empty-result-callbacks flag.</p>
- <p>The empty-result-callbacks flag affects the sqlite3_exec API only.
- Normally, when the empty-result-callbacks flag is cleared, the
- callback function supplied to the sqlite3_exec() call is not invoked
- for commands that return zero rows of data. When empty-result-callbacks
- is set in this situation, the callback function is invoked exactly once,
- with the third parameter set to 0 (NULL). This is to enable programs
- that use the sqlite3_exec() API to retrieve column-names even when
- a query returns no data.
- </p>
-
-<a name="pragma_encoding"></a>
-<li><p><b>PRAGMA encoding;
- <br>PRAGMA encoding = "UTF-8";
- <br>PRAGMA encoding = "UTF-16";
- <br>PRAGMA encoding = "UTF-16le";
- <br>PRAGMA encoding = "UTF-16be";</b></p>
- <p>In first form, if the main database has already been
- created, then this pragma returns the text encoding used by the
- main database, one of "UTF-8", "UTF-16le" (little-endian UTF-16
- encoding) or "UTF-16be" (big-endian UTF-16 encoding). If the main
- database has not already been created, then the value returned is the
- text encoding that will be used to create the main database, if
- it is created by this session.</p>
- <p>The second and subsequent forms of this pragma are only useful if
- the main database has not already been created. In this case the
- pragma sets the encoding that the main database will be created with if
- it is created by this session. The string "UTF-16" is interpreted
- as "UTF-16 encoding using native machine byte-ordering". If the second
- and subsequent forms are used after the database file has already
- been created, they have no effect and are silently ignored.</p>
-
- <p>Once an encoding has been set for a database, it cannot be changed.</p>
-
- <p>Databases created by the ATTACH command always use the same encoding
- as the main database.</p>
-</li>
-
-<a name="pragma_full_column_names"></a>
-<li><p><b>PRAGMA full_column_names;
- <br>PRAGMA full_column_names = </b><i>0 | 1</i><b>;</b></p>
- <p>Query or change the full-column-names flag. This flag affects
- the way SQLite names columns of data returned by SELECT statements
- when the expression for the column is a table-column name or the
- wildcard "*". Normally, such result columns are named
- <table-name/alias><column-name> if the SELECT statement joins
- two or
- more tables together, or simply <column-name> if the SELECT
- statement queries a single table. When the full-column-names flag
- is set, such columns are always named <table-name/alias>
- <column-name> regardless of whether or not a join is performed.
- </p>
- <p>If both the short-column-names and full-column-names are set,
- then the behaviour associated with the full-column-names flag is
- exhibited.
- </p>
-</li>
-
-<a name="pragma_fullfsync"></a>
-<li><p><b>PRAGMA fullfsync
- <br>PRAGMA fullfsync = </b><i>0 | 1</i><b>;</b></p>
- <p>Query or change the fullfsync flag. This flag affects
- determines whether or not the F_FULLFSYNC syncing method is used
- on systems that support it. The default value is off. As of this
- writing (2006-02-10) only Mac OS X supports F_FULLFSYNC.
- </p>
-</li>
-
-<a name="pragma_incremental_vacuum"></a>
-<li><p><b>PRAGMA incremental_vacuum</b><i>(N)</i><b>;</b></p>
- <p>The incremental_vacuum pragma causes up to <i>N</i> pages to
- be removed from the freelist. The database file is truncated by
- the same amount. The incremental_vacuum pragma has no effect if
- the database is not in
- <a href="#pragma_auto_vacuum">auto_vacuum==incremental</a> mode
- or if there are no pages on the freelist. If there are fewer than
- <i>N</i> pages on the freelist, then the entire freelist is cleared.</p>
-
- <p>As of version 3.4.0 (the first version that supports
- incremental_vacuum) this feature is still experimental. Possible
- future changes include enhancing incremental vacuum to do
- defragmentation and node repacking just as the full-blown
- <a href="lang_vacuum.html">VACUUM</a> command does. And
- incremental vacuum may be promoted from a pragma to a separate
- SQL command, or perhaps some variation on the VACUUM command.
- Programmers are cautioned to not become enamored with the
- current syntax or functionality as it is likely to change.</p>
-</li>
-
-
-<a name="pragma_legacy_file_format"></a>
-<li><p><b>PRAGMA legacy_file_format;
- <br>PRAGMA legacy_file_format = <i>ON | OFF</i></b></p>
- <p>This pragma sets or queries the value of the legacy_file_format
- flag. When this flag is on, new SQLite databases are created in
- a file format that is readable and writable by all versions of
- SQLite going back to 3.0.0. When the flag is off, new databases
- are created using the latest file format which might not be
- readable or writable by older versions of SQLite.</p>
-
- <p>This flag only affects newly created databases. It has no
- effect on databases that already exist.</p>
-</li>
-
-<a name="pragma_locking_mode"></a>
-<li><p><b>PRAGMA locking_mode;
- <br>PRAGMA locking_mode = <i>NORMAL | EXCLUSIVE</i></b></p>
- <p>This pragma sets or queries the database connection locking-mode.
- The locking-mode is either NORMAL or EXCLUSIVE.
-
- <p>In NORMAL locking-mode (the default), a database connection
- unlocks the database file at the conclusion of each read or
- write transaction. When the locking-mode is set to EXCLUSIVE, the
- database connection never releases file-locks. The first time the
- database is read in EXCLUSIVE mode, a shared lock is obtained and
- held. The first time the database is written, an exclusive lock is
- obtained and held.</p>
-
- <p>Database locks obtained by a connection in EXCLUSIVE mode may be
- released either by closing the database connection, or by setting the
- locking-mode back to NORMAL using this pragma and then accessing the
- database file (for read or write). Simply setting the locking-mode to
- NORMAL is not enough - locks are not be released until the next time
- the database file is accessed.</p>
-
- <p>There are two reasons to set the locking-mode to EXCLUSIVE. One
- is if the application actually wants to prevent other processes from
- accessing the database file. The other is that a small number of
- filesystem operations are saved by optimizations enabled in this
- mode. This may be significant in embedded environments.</p>
-
- <p>When the locking_mode pragma specifies a particular database,
- for example:</p>
-
- <blockquote>
-PRAGMA <b>main.</b>locking_mode=EXCLUSIVE;
- </blockquote>
-
- <p>Then the locking mode applies only to the named database. If no
- database name qualifier preceeds the "locking_mode" keyword then
- the locking mode is applied to all databases, including any new
- databases added by subsequent <a href="lang_attach.html">ATTACH</a>
- commands.</p>
-
- <p>The "temp" database (in which TEMP tables and indices are stored)
- always uses exclusive locking mode. The locking mode of temp cannot
- be changed. All other databases use the normal locking mode by default
- and are affected by this pragma.</p>
-</li>
-
-<a name="pragma_page_size"></a>
-<li><p><b>PRAGMA page_size;
- <br>PRAGMA page_size = </b><i>bytes</i><b>;</b></p>
- <p>Query or set the page-size of the database. The page-size
- may only be set if the database has not yet been created. The page
- size must be a power of two greater than or equal to 512 and less
- than or equal to 8192. The upper limit may be modified by setting
- the value of macro SQLITE_MAX_PAGE_SIZE during compilation. The
- maximum upper bound is 32768.
- </p>
-</li>
-
-<a name="pragma_max_page_count"></a>
-<li><p><b>PRAGMA max_page_count;
- <br>PRAGMA max_page_count = </b><i>N</i><b>;</b></p>
- <p>Query or set the maximum number of pages in the database file.
- Both forms of the pragma return the maximum page count. The second
- form attempts to modify the maximum page count. The maximum page
- count cannot be reduced below the current database size.
- </p>
-</li>
-
-<a name="pragma_read_uncommitted"></a>
-<li><p><b>PRAGMA read_uncommitted;
- <br>PRAGMA read_uncommitted = </b><i>0 | 1</i><b>;</b></p>
- <p>Query, set, or clear READ UNCOMMITTED isolation. The default isolation
- level for SQLite is SERIALIZABLE. Any process or thread can select
- READ UNCOMMITTED isolation, but SERIALIZABLE will still be used except
- between connections that share a common page and schema cache.
- Cache sharing is enabled using the
- <a href="capi3ref.html#sqlite3_enable_shared_cache">
- sqlite3_enable_shared_cache()</a> API and is only available between
- connections running the same thread. Cache sharing is off by default.
- </p>
-</li>
-
-<a name="pragma_short_column_names"></a>
-<li><p><b>PRAGMA short_column_names;
- <br>PRAGMA short_column_names = </b><i>0 | 1</i><b>;</b></p>
- <p>Query or change the short-column-names flag. This flag affects
- the way SQLite names columns of data returned by SELECT statements
- when the expression for the column is a table-column name or the
- wildcard "*". Normally, such result columns are named
- <table-name/alias>lt;column-name> if the SELECT statement
- joins two or more tables together, or simply <column-name> if
- the SELECT statement queries a single table. When the short-column-names
- flag is set, such columns are always named <column-name>
- regardless of whether or not a join is performed.
- </p>
- <p>If both the short-column-names and full-column-names are set,
- then the behaviour associated with the full-column-names flag is
- exhibited.
- </p>
-</li>
-
-<a name="pragma_synchronous"></a>
-<li><p><b>PRAGMA synchronous;
- <br>PRAGMA synchronous = FULL; </b>(2)<b>
- <br>PRAGMA synchronous = NORMAL; </b>(1)<b>
- <br>PRAGMA synchronous = OFF; </b>(0)</p>
- <p>Query or change the setting of the "synchronous" flag.
- The first (query) form will return the setting as an
- integer. When synchronous is FULL (2), the SQLite database engine will
- pause at critical moments to make sure that data has actually been
- written to the disk surface before continuing. This ensures that if
- the operating system crashes or if there is a power failure, the database
- will be uncorrupted after rebooting. FULL synchronous is very
- safe, but it is also slow.
- When synchronous is NORMAL, the SQLite database
- engine will still pause at the most critical moments, but less often
- than in FULL mode. There is a very small (though non-zero) chance that
- a power failure at just the wrong time could corrupt the database in
- NORMAL mode. But in practice, you are more likely to suffer
- a catastrophic disk failure or some other unrecoverable hardware
- fault.
- With synchronous OFF (0), SQLite continues without pausing
- as soon as it has handed data off to the operating system.
- If the application running SQLite crashes, the data will be safe, but
- the database might become corrupted if the operating system
- crashes or the computer loses power before that data has been written
- to the disk surface. On the other hand, some
- operations are as much as 50 or more times faster with synchronous OFF.
- </p>
- <p>In SQLite version 2, the default value is NORMAL. For version 3, the
- default was changed to FULL.
- </p>
-</li>
-
-
-<a name="pragma_temp_store"></a>
-<li><p><b>PRAGMA temp_store;
- <br>PRAGMA temp_store = DEFAULT;</b> (0)<b>
- <br>PRAGMA temp_store = FILE;</b> (1)<b>
- <br>PRAGMA temp_store = MEMORY;</b> (2)</p>
- <p>Query or change the setting of the "<b>temp_store</b>" parameter.
- When temp_store is DEFAULT (0), the compile-time C preprocessor macro
- TEMP_STORE is used to determine where temporary tables and indices
- are stored. When
- temp_store is MEMORY (2) temporary tables and indices are kept in memory.
- When temp_store is FILE (1) temporary tables and indices are stored
- in a file. The <a href="#pragma_temp_store_directory">
- temp_store_directory</a> pragma can be used to specify the directory
- containing this file.
- <b>FILE</b> is specified. When the temp_store setting is changed,
- all existing temporary tables, indices, triggers, and views are
- immediately deleted.</p>
-
- <p>It is possible for the library compile-time C preprocessor symbol
- TEMP_STORE to override this pragma setting. The following table summarizes
- the interaction of the TEMP_STORE preprocessor macro and the
- temp_store pragma:</p>
-
- <blockquote>
- <table cellpadding="2" border="1">
- <tr><th valign="bottom">TEMP_STORE</th>
- <th valign="bottom">PRAGMA<br>temp_store</th>
- <th>Storage used for<br>TEMP tables and indices</th></tr>
- <tr><td align="center">0</td>
- <td align="center"><em>any</em></td>
- <td align="center">file</td></tr>
- <tr><td align="center">1</td>
- <td align="center">0</td>
- <td align="center">file</td></tr>
- <tr><td align="center">1</td>
- <td align="center">1</td>
- <td align="center">file</td></tr>
- <tr><td align="center">1</td>
- <td align="center">2</td>
- <td align="center">memory</td></tr>
- <tr><td align="center">2</td>
- <td align="center">0</td>
- <td align="center">memory</td></tr>
- <tr><td align="center">2</td>
- <td align="center">1</td>
- <td align="center">file</td></tr>
- <tr><td align="center">2</td>
- <td align="center">2</td>
- <td align="center">memory</td></tr>
- <tr><td align="center">3</td>
- <td align="center"><em>any</em></td>
- <td align="center">memory</td></tr>
- </table>
- </blockquote>
- </li>
- <br>
-
-<a name="pragma_temp_store_directory"></a>
-<li><p><b>PRAGMA temp_store_directory;
- <br>PRAGMA temp_store_directory = 'directory-name';</b></p>
- <p>Query or change the setting of the "temp_store_directory" - the
- directory where files used for storing temporary tables and indices
- are kept. This setting lasts for the duration of the current connection
- only and resets to its default value for each new connection opened.
-
- <p>When the temp_store_directory setting is changed, all existing temporary
- tables, indices, triggers, and viewers are immediately deleted. In
- practice, temp_store_directory should be set immediately after the
- database is opened. </p>
-
- <p>The value <i>directory-name</i> should be enclosed in single quotes.
- To revert the directory to the default, set the <i>directory-name</i> to
- an empty string, e.g., <i>PRAGMA temp_store_directory = ''</i>. An
- error is raised if <i>directory-name</i> is not found or is not
- writable. </p>
-
- <p>The default directory for temporary files depends on the OS. For
- Unix/Linux/OSX, the default is the is the first writable directory found
- in the list of: <b>/var/tmp, /usr/tmp, /tmp,</b> and <b>
- <i>current-directory</i></b>. For Windows NT, the default
- directory is determined by Windows, generally
- <b>C:\Documents and Settings\<i>user-name</i>\Local Settings\Temp\</b>.
- Temporary files created by SQLite are unlinked immediately after
- opening, so that the operating system can automatically delete the
- files when the SQLite process exits. Thus, temporary files are not
- normally visible through <i>ls</i> or <i>dir</i> commands.</p>
-
- </li>
-</ul>
-}
-
-Section {Pragmas to query the database schema} schema
-
-puts {
-<ul>
-<a name="pragma_database_list"></a>
-<li><p><b>PRAGMA database_list;</b></p>
- <p>For each open database, invoke the callback function once with
- information about that database. Arguments include the index and
- the name the database was attached with. The first row will be for
- the main database. The second row will be for the database used to
- store temporary tables.</p></li>
-
-<a name="pragma_foreign_key_list"></a>
-<li><p><b>PRAGMA foreign_key_list(</b><i>table-name</i><b>);</b></p>
- <p>For each foreign key that references a column in the argument
- table, invoke the callback function with information about that
- foreign key. The callback function will be invoked once for each
- column in each foreign key.</p></li>
-
-<a name="pragma_freelist_count"></a>
-<li><p><b>PRAGMA [database].freelist_count;</b></p>
- <p>Return the number of unused pages in the database file. Running
- a <a href="#pragma_incremental_vacuum">"PRAGMA incremental_vaccum(N);"</a>
- command with a large value of N will shrink the database file by this
- number of pages. </p></li>
-
-<a name="pragma_index_info"></a>
-<li><p><b>PRAGMA index_info(</b><i>index-name</i><b>);</b></p>
- <p>For each column that the named index references, invoke the
- callback function
- once with information about that column, including the column name,
- and the column number.</p></li>
-
-<a name="pragma_index_list"></a>
-<li><p><b>PRAGMA index_list(</b><i>table-name</i><b>);</b></p>
- <p>For each index on the named table, invoke the callback function
- once with information about that index. Arguments include the
- index name and a flag to indicate whether or not the index must be
- unique.</p></li>
-
-<a name="pragma_table_info"></a>
-<li><p><b>PRAGMA table_info(</b><i>table-name</i><b>);</b></p>
- <p>For each column in the named table, invoke the callback function
- once with information about that column, including the column name,
- data type, whether or not the column can be NULL, and the default
- value for the column.</p></li>
-</ul>
-}
-
-Section {Pragmas to query/modify version values} version
-
-puts {
-
-<ul>
-<a name="pragma_schema_version"></a>
-<a name="pragma_user_version"></a>
-<li><p><b>PRAGMA [database.]schema_version;
- <br>PRAGMA [database.]schema_version = </b><i>integer </i><b>;
- <br>PRAGMA [database.]user_version;
- <br>PRAGMA [database.]user_version = </b><i>integer </i><b>;</b>
-
-
-<p> The pragmas schema_version and user_version are used to set or get
- the value of the schema-version and user-version, respectively. Both
- the schema-version and the user-version are 32-bit signed integers
- stored in the database header.</p>
-
-<p> The schema-version is usually only manipulated internally by SQLite.
- It is incremented by SQLite whenever the database schema is modified
- (by creating or dropping a table or index). The schema version is
- used by SQLite each time a query is executed to ensure that the
- internal cache of the schema used when compiling the SQL query matches
- the schema of the database against which the compiled query is actually
- executed. Subverting this mechanism by using "PRAGMA schema_version"
- to modify the schema-version is potentially dangerous and may lead
- to program crashes or database corruption. Use with caution!</p>
-
-<p> The user-version is not used internally by SQLite. It may be used by
- applications for any purpose.</p>
-</li>
-</ul>
-}
-
-Section {Pragmas to debug the library} debug
-
-puts {
-<ul>
-<a name="pragma_integrity_check"></a>
-<li><p><b>PRAGMA integrity_check;
- <br>PRAGMA integrity_check(</b><i>integer</i><b>)</b></p>
- <p>The command does an integrity check of the entire database. It
- looks for out-of-order records, missing pages, malformed records, and
- corrupt indices.
- If any problems are found, then strings are returned (as multiple
- rows with a single column per row) which describe
- the problems. At most <i>integer</i> errors will be reported
- before the analysis quits. The default value for <i>integer</i>
- is 100. If no errors are found, a single row with the value "ok" is
- returned.</p></li>
-
-<a name="pragma_parser_trace"></a>
-<li><p><b>PRAGMA parser_trace = ON; </b>(1)<b>
- <br>PRAGMA parser_trace = OFF;</b> (0)</p>
- <p>Turn tracing of the SQL parser inside of the
- SQLite library on and off. This is used for debugging.
- This only works if the library is compiled without the NDEBUG macro.
- </p></li>
-
-<a name="pragma_vdbe_trace"></a>
-<li><p><b>PRAGMA vdbe_trace = ON; </b>(1)<b>
- <br>PRAGMA vdbe_trace = OFF;</b> (0)</p>
- <p>Turn tracing of the virtual database engine inside of the
- SQLite library on and off. This is used for debugging. See the
- <a href="vdbe.html#trace">VDBE documentation</a> for more
- information.</p></li>
-
-<a name="pragma_vdbe_listing"></a>
-<li><p><b>PRAGMA vdbe_listing = ON; </b>(1)<b>
- <br>PRAGMA vdbe_listing = OFF;</b> (0)</p>
- <p>Turn listings of virtual machine programs on and off.
- With listing is on, the entire content of a program is printed
- just prior to beginning execution. This is like automatically
- executing an EXPLAIN prior to each statement. The statement
- executes normally after the listing is printed.
- This is used for debugging. See the
- <a href="vdbe.html#trace">VDBE documentation</a> for more
- information.</p></li>
-</ul>
-
-}
+++ /dev/null
-#
-# Run this TCL script to generate HTML for the quickstart.html file.
-#
-set rcsid {$Id: quickstart.tcl,v 1.8 2006/06/13 11:27:22 drh Exp $}
-source common.tcl
-header {SQLite In 5 Minutes Or Less}
-puts {
-<p>Here is what you do to start experimenting with SQLite without having
-to do a lot of tedious reading and configuration:</p>
-
-<h2>Download The Code</h2>
-
-<ul>
-<li><p>Get a copy of the prebuilt binaries for your machine, or get a copy
-of the sources and compile them yourself. Visit
-the <a href="download.html">download</a> page for more information.</p></li>
-</ul>
-
-<h2>Create A New Database</h2>
-
-<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 TCL program that demonstrates how to use
-the TCL interface to SQLite. The program executes the SQL statements
-given as the second argument on the database defined by the first
-argument. The commands to watch for are the <b>sqlite3</b> command
-on line 7 which opens an SQLite database and creates
-a new TCL command named "<b>db</b>" to access that database, the
-invocation of the <b>db</b> command on line 8 to execute
-SQL commands against the database, and the closing of the database connection
-on the last line of the script.</p>
-
-<blockquote><pre>
-#!/usr/bin/tclsh
-if {$argc!=2} {
- puts stderr "Usage: %s DATABASE SQL-STATEMENT"
- exit 1
-}
-load /usr/lib/tclsqlite3.so Sqlite3
-<b>sqlite3</b> db [lindex $argv 0]
-<b>db</b> eval [lindex $argv 1] x {
- foreach v $x(*) {
- puts "$v = $x($v)"
- }
- puts ""
-}
-<b>db</b> close
-</pre></blockquote>
-</li>
-
-<li><p>Below is a simple C program that demonstrates how to use
-the C/C++ interface to SQLite. The name of a database is given by
-the first argument and the second argument is one or more SQL statements
-to execute against the database. The function calls to pay attention
-to here are the call to <b>sqlite3_open()</b> on line 22 which opens
-the database, <b>sqlite3_exec()</b> on line 27 that executes SQL
-commands against the database, and <b>sqlite3_close()</b> on line 31
-that closes the database connection.</p>
-
-<blockquote><pre>
-#include <stdio.h>
-#include <sqlite3.h>
-
-static int callback(void *NotUsed, int argc, char **argv, char **azColName){
- int i;
- for(i=0; i<argc; i++){
- printf("%s = %s\n", azColName[i], argv[i] ? argv[i] : "NULL");
- }
- printf("\n");
- return 0;
-}
-
-int main(int argc, char **argv){
- sqlite3 *db;
- char *zErrMsg = 0;
- int rc;
-
- if( argc!=3 ){
- fprintf(stderr, "Usage: %s DATABASE SQL-STATEMENT\n", argv[0]);
- exit(1);
- }
- rc = <b>sqlite3_open</b>(argv[1], &db);
- if( rc ){
- fprintf(stderr, "Can't open database: %s\n", sqlite3_errmsg(db));
- sqlite3_close(db);
- exit(1);
- }
- rc = <b>sqlite3_exec</b>(db, argv[2], callback, 0, &zErrMsg);
- if( rc!=SQLITE_OK ){
- fprintf(stderr, "SQL error: %s\n", zErrMsg);
- sqlite3_free(zErrMsg);
- }
- <b>sqlite3_close</b>(db);
- return 0;
-}
-</pre></blockquote>
-</li>
-</ul>
-}
-footer {$Id: quickstart.tcl,v 1.8 2006/06/13 11:27:22 drh Exp $}
+++ /dev/null
-#
-# Run this script to generated a sharedcache.html output file
-#
-set rcsid {$Id: }
-source common.tcl
-header {SQLite Shared-Cache Mode}
-
-proc HEADING {level title} {
- global pnum
- incr pnum($level)
- foreach i [array names pnum] {
- if {$i>$level} {set pnum($i) 0}
- }
- set h [expr {$level+1}]
- if {$h>6} {set h 6}
- set n $pnum(1).$pnum(2)
- for {set i 3} {$i<=$level} {incr i} {
- append n .$pnum($i)
- }
- puts "<h$h>$n $title</h$h>"
-}
-set pnum(1) 0
-set pnum(2) 0
-set pnum(3) 0
-set pnum(4) 0
-set pnum(5) 0
-set pnum(6) 0
-set pnum(7) 0
-set pnum(8) 0
-
-HEADING 1 {SQLite Shared-Cache Mode}
-
-puts {
-<p>Starting with version 3.3.0, SQLite includes a special "shared-cache"
-mode (disabled by default) intended for use in embedded servers. If
-shared-cache mode is enabled and a thread establishes multiple connections
-to the same database, the connections share a single data and schema cache.
-This can significantly reduce the quantity of memory and IO required by
-the system.</p>
-
-<p>Using shared-cache mode imposes some extra restrictions on
-passing database handles between threads and changes the semantics
-of the locking model in some cases. These details are described in full by
-this document. A basic understanding of the normal SQLite locking model (see
-<a href="lockingv3.html">File Locking And Concurrency In SQLite Version 3</a>
-for details) is assumed.</p>
-}
-
-HEADING 1 {Shared-Cache Locking Model}
-
-puts {
-<p>Externally, from the point of view of another process or thread, two
-or more database connections using a shared-cache appear as a single
-connection. The locking protocol used to arbitrate between multiple
-shared-caches or regular database users is described elsewhere.
-</p>
-
-<table style="margin:auto">
-<tr><td>
-<img src="shared.gif">
-<!-- <pre>
- +--------------+ +--------------+
- | Connection 2 | | Connection 3 |
- +--------------+ +--------------+
- | |
- V V
-+--------------+ +--------------+
-| Connection 1 | | Shared cache |
-+--------------+ +--------------+
- | |
- V V
- +----------------+
- | Database |
- +----------------+
-</pre> -->
-</table>
-<p style="font-style:italic;text-align:center">Figure 1</p>
-
-<p>Figure 1 depicts an example runtime configuration where three
-database connections have been established. Connection 1 is a normal
-SQLite database connection. Connections 2 and 3 share a cache (and so must
-have been established by the same process thread). The normal locking
-protocol is used to serialize database access between connection 1 and
-the shared cache. The internal protocol used to serialize (or not, see
-"Read-Uncommitted Isolation Mode" below) access to the shared-cache by
-connections 2 and 3 is described in the remainder of this section.
-</p>
-
-<p>There are three levels to the shared-cache locking model,
-transaction level locking, table level locking and schema level locking.
-They are described in the following three sub-sections.</p>
-
-}
-
-HEADING 2 {Transaction Level Locking}
-
-puts {
-<p>SQLite connections can open two kinds of transactions, read and write
-transactions. This is not done explicitly, a transaction is implicitly a
-read-transaction until it first writes to a database table, at which point
-it becomes a write-transaction.
-</p>
-<p>At most one connection to a single shared cache may open a
-write transaction at any one time. This may co-exist with any number of read
-transactions.
-</p>
-}
-
-HEADING 2 {Table Level Locking}
-
-puts {
-<p>When two or more connections use a shared-cache, locks are used to
-serialize concurrent access attempts on a per-table basis. Tables support
-two types of locks, "read-locks" and "write-locks". Locks are granted to
-connections - at any one time, each database connection has either a
-read-lock, write-lock or no lock on each database table.
-</p>
-
-<p>At any one time, a single table may have any number of active read-locks
-or a single active write lock. To read data a table, a connection must
-first obtain a read-lock. To write to a table, a connection must obtain a
-write-lock on that table. If a required table lock cannot be obtained,
-the query fails and SQLITE_LOCKED is returned to the caller.
-</p>
-
-<p>Once a connection obtains a table lock, it is not released until the
-current transaction (read or write) is concluded.
-</p>
-}
-
-HEADING 3 {Read-Uncommitted Isolation Mode}
-
-puts {
-<p>The behaviour described above may be modified slightly by using the
-<i>read_uncommitted</i> pragma to change the isolation level from serialized
-(the default), to read-uncommitted.</p>
-
-<p> A database connection in read-uncommitted mode does not attempt
-to obtain read-locks before reading from database tables as described
-above. This can lead to inconsistent query results if another database
-connection modifies a table while it is being read, but it also means that
-a read-transaction opened by a connection in read-uncommitted mode can
-neither block nor be blocked by any other connection.</p>
-
-<p>Read-uncommitted mode has no effect on the locks required to write to
-database tables (i.e. read-uncommitted connections must still obtain
-write-locks and hence database writes may still block or be blocked).
-Also, read-uncommitted mode has no effect on the <i>sqlite_master</i>
-locks required by the rules enumerated below (see section
-"Schema (sqlite_master) Level Locking").
-</p>
-
-<pre>
- /* Set the value of the read-uncommitted flag:
- **
- ** True -> Set the connection to read-uncommitted mode.
- ** False -> Set the connectino to serialized (the default) mode.
- */
- PRAGMA read_uncommitted = <boolean>;
-
- /* Retrieve the current value of the read-uncommitted flag */
- PRAGMA read_uncommitted;
-</pre>
-}
-
-HEADING 2 {Schema (sqlite_master) Level Locking}
-
-puts {
-<p>The <i>sqlite_master</i> table supports shared-cache read and write
-locks in the same way as all other database tables (see description
-above). The following special rules also apply:
-</p>
-
-<ul>
-<li>A connection must obtain a read-lock on <i>sqlite_master</i> before
-accessing any database tables or obtaining any other read or write locks.</li>
-<li>Before executing a statement that modifies the database schema (i.e.
-a CREATE or DROP TABLE statement), a connection must obtain a write-lock on
-<i>sqlite_master</i>.
-</li>
-<li>A connection may not compile an SQL statement if any other connection
-is holding a write-lock on the <i>sqlite_master</i> table of any attached
-database (including the default database, "main").
-</li>
-</ul>
-}
-
-HEADING 1 {Thread Related Issues}
-
-puts {
-<p>When shared-cache mode is enabled, a database connection may only be
-used by the thread that called sqlite3_open() to create it. If another
-thread attempts to use the database connection, in most cases an
-SQLITE_MISUSE error is returned. However this is not guaranteed and
-programs should not depend on this behaviour, in some cases a segfault
-may result.
-</p>
-}
-
-HEADING 1 {Enabling Shared-Cache Mode}
-
-puts {
-<p>Shared-cache mode is enabled on a thread-wide basis. Using the C
-interface, the following API can be used to enable or disable shared-cache
-mode for the calling thread:
-</p>
-
-<pre>
-int sqlite3_enable_shared_cache(int);
-</pre>
-
-<p>It is illegal to call sqlite3_enable_shared_cache() if one or more
-open database connections were opened by the calling thread. If the argument
-is non-zero, shared-cache mode is enabled. If the argument is zero,
-shared-cache mode is disabled. The return value is either SQLITE_OK (if the
-operation was successful), SQLITE_NOMEM (if a malloc() failed), or
-SQLITE_MISUSE (if the thread has open database connections).
-</p>
-}
-
-footer $rcsid
+++ /dev/null
-#
-# Run this Tcl script to generate the speed.html file.
-#
-set rcsid {$Id: speed.tcl,v 1.17 2005/03/12 15:55:11 drh Exp $ }
-source common.tcl
-header {SQLite Database Speed Comparison}
-
-puts {
-<h2>Database Speed Comparison</h2>
-
-<font color="red"><b>
-Note: This document is old. It describes a speed comparison between
-an older version of SQLite against archaic versions of MySQL and PostgreSQL.
-Readers are invited to contribute more up-to-date speed comparisons
-on the <a href="http://www.sqlite.org/cvstrac/wiki">SQLite Wiki</a>.
-<p>
-The numbers here are old enough to be nearly meaningless. Until it is
-updated, use this document only as proof that SQLite is not a
-sluggard.
-</b></font>
-
-<h3>Executive Summary</h3>
-
-<p>A series of tests were run to measure the relative performance of
-SQLite 2.7.6, PostgreSQL 7.1.3, and MySQL 3.23.41.
-The following are general
-conclusions drawn from these experiments:
-</p>
-
-<ul>
-<li><p>
- SQLite 2.7.6 is significantly faster (sometimes as much as 10 or
- 20 times faster) than the default PostgreSQL 7.1.3 installation
- on RedHat 7.2 for most common operations.
-</p></li>
-<li><p>
- SQLite 2.7.6 is often faster (sometimes
- more than twice as fast) than MySQL 3.23.41
- for most common operations.
-</p></li>
-<li><p>
- SQLite does not execute CREATE INDEX or DROP TABLE as fast as
- the other databases. But this is not seen as a problem because
- those are infrequent operations.
-</p></li>
-<li><p>
- SQLite works best if you group multiple operations together into
- a single transaction.
-</p></li>
-</ul>
-
-<p>
-The results presented here come with the following caveats:
-</p>
-
-<ul>
-<li><p>
- These tests did not attempt to measure multi-user performance or
- optimization of complex queries involving multiple joins and subqueries.
-</p></li>
-<li><p>
- These tests are on a relatively small (approximately 14 megabyte) database.
- They do not measure how well the database engines scale to larger problems.
-</p></li>
-</ul>
-
-<h3>Test Environment</h3>
-
-<p>
-The platform used for these tests is a 1.6GHz Athlon with 1GB or memory
-and an IDE disk drive. The operating system is RedHat Linux 7.2 with
-a stock kernel.
-</p>
-
-<p>
-The PostgreSQL and MySQL servers used were as delivered by default on
-RedHat 7.2. (PostgreSQL version 7.1.3 and MySQL version 3.23.41.)
-No effort was made to tune these engines. Note in particular
-the the default MySQL configuration on RedHat 7.2 does not support
-transactions. Not having to support transactions gives MySQL a
-big speed advantage, but SQLite is still able to hold its own on most
-tests.
-</p>
-
-<p>
-I am told that the default PostgreSQL configuration in RedHat 7.3
-is unnecessarily conservative (it is designed to
-work on a machine with 8MB of RAM) and that PostgreSQL could
-be made to run a lot faster with some knowledgeable configuration
-tuning.
-Matt Sergeant reports that he has tuned his PostgreSQL installation
-and rerun the tests shown below. His results show that
-PostgreSQL and MySQL run at about the same speed. For Matt's
-results, visit
-</p>
-
-<blockquote>
-<a href="http://www.sergeant.org/sqlite_vs_pgsync.html">
-http://www.sergeant.org/sqlite_vs_pgsync.html</a>
-</blockquote>
-
-<p>
-SQLite was tested in the same configuration that it appears
-on the website. It was compiled with -O6 optimization and with
-the -DNDEBUG=1 switch which disables the many "assert()" statements
-in the SQLite code. The -DNDEBUG=1 compiler option roughly doubles
-the speed of SQLite.
-</p>
-
-<p>
-All tests are conducted on an otherwise quiescent machine.
-A simple Tcl script was used to generate and run all the tests.
-A copy of this Tcl script can be found in the SQLite source tree
-in the file <b>tools/speedtest.tcl</b>.
-</p>
-
-<p>
-The times reported on all tests represent wall-clock time
-in seconds. Two separate time values are reported for SQLite.
-The first value is for SQLite in its default configuration with
-full disk synchronization turned on. With synchronization turned
-on, SQLite executes
-an <b>fsync()</b> system call (or the equivalent) at key points
-to make certain that critical data has
-actually been written to the disk drive surface. Synchronization
-is necessary to guarantee the integrity of the database if the
-operating system crashes or the computer powers down unexpectedly
-in the middle of a database update. The second time reported for SQLite is
-when synchronization is turned off. With synchronization off,
-SQLite is sometimes much faster, but there is a risk that an
-operating system crash or an unexpected power failure could
-damage the database. Generally speaking, the synchronous SQLite
-times are for comparison against PostgreSQL (which is also
-synchronous) and the asynchronous SQLite times are for
-comparison against the asynchronous MySQL engine.
-</p>
-
-<h3>Test 1: 1000 INSERTs</h3>
-<blockquote>
-CREATE TABLE t1(a INTEGER, b INTEGER, c VARCHAR(100));<br>
-INSERT INTO t1 VALUES(1,13153,'thirteen thousand one hundred fifty three');<br>
-INSERT INTO t1 VALUES(2,75560,'seventy five thousand five hundred sixty');<br>
-<i>... 995 lines omitted</i><br>
-INSERT INTO t1 VALUES(998,66289,'sixty six thousand two hundred eighty nine');<br>
-INSERT INTO t1 VALUES(999,24322,'twenty four thousand three hundred twenty two');<br>
-INSERT INTO t1 VALUES(1000,94142,'ninety four thousand one hundred forty two');<br>
-
-</blockquote><table border=0 cellpadding=0 cellspacing=0>
-<tr><td>PostgreSQL:</td><td align="right"> 4.373</td></tr>
-<tr><td>MySQL:</td><td align="right"> 0.114</td></tr>
-<tr><td>SQLite 2.7.6:</td><td align="right"> 13.061</td></tr>
-<tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.223</td></tr>
-</table>
-
-<p>
-Because it does not have a central server to coordinate access,
-SQLite must close and reopen the database file, and thus invalidate
-its cache, for each transaction. In this test, each SQL statement
-is a separate transaction so the database file must be opened and closed
-and the cache must be flushed 1000 times. In spite of this, the asynchronous
-version of SQLite is still nearly as fast as MySQL. Notice how much slower
-the synchronous version is, however. SQLite calls <b>fsync()</b> after
-each synchronous transaction to make sure that all data is safely on
-the disk surface before continuing. For most of the 13 seconds in the
-synchronous test, SQLite was sitting idle waiting on disk I/O to complete.</p>
-
-
-<h3>Test 2: 25000 INSERTs in a transaction</h3>
-<blockquote>
-BEGIN;<br>
-CREATE TABLE t2(a INTEGER, b INTEGER, c VARCHAR(100));<br>
-INSERT INTO t2 VALUES(1,59672,'fifty nine thousand six hundred seventy two');<br>
-<i>... 24997 lines omitted</i><br>
-INSERT INTO t2 VALUES(24999,89569,'eighty nine thousand five hundred sixty nine');<br>
-INSERT INTO t2 VALUES(25000,94666,'ninety four thousand six hundred sixty six');<br>
-COMMIT;<br>
-
-</blockquote><table border=0 cellpadding=0 cellspacing=0>
-<tr><td>PostgreSQL:</td><td align="right"> 4.900</td></tr>
-<tr><td>MySQL:</td><td align="right"> 2.184</td></tr>
-<tr><td>SQLite 2.7.6:</td><td align="right"> 0.914</td></tr>
-<tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.757</td></tr>
-</table>
-
-<p>
-When all the INSERTs are put in a transaction, SQLite no longer has to
-close and reopen the database or invalidate its cache between each statement.
-It also does not
-have to do any fsync()s until the very end. When unshackled in
-this way, SQLite is much faster than either PostgreSQL and MySQL.
-</p>
-
-<h3>Test 3: 25000 INSERTs into an indexed table</h3>
-<blockquote>
-BEGIN;<br>
-CREATE TABLE t3(a INTEGER, b INTEGER, c VARCHAR(100));<br>
-CREATE INDEX i3 ON t3(c);<br>
-<i>... 24998 lines omitted</i><br>
-INSERT INTO t3 VALUES(24999,88509,'eighty eight thousand five hundred nine');<br>
-INSERT INTO t3 VALUES(25000,84791,'eighty four thousand seven hundred ninety one');<br>
-COMMIT;<br>
-
-</blockquote><table border=0 cellpadding=0 cellspacing=0>
-<tr><td>PostgreSQL:</td><td align="right"> 8.175</td></tr>
-<tr><td>MySQL:</td><td align="right"> 3.197</td></tr>
-<tr><td>SQLite 2.7.6:</td><td align="right"> 1.555</td></tr>
-<tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 1.402</td></tr>
-</table>
-
-<p>
-There were reports that SQLite did not perform as well on an indexed table.
-This test was recently added to disprove those rumors. It is true that
-SQLite is not as fast at creating new index entries as the other engines
-(see Test 6 below) but its overall speed is still better.
-</p>
-
-<h3>Test 4: 100 SELECTs without an index</h3>
-<blockquote>
-BEGIN;<br>
-SELECT count(*), avg(b) FROM t2 WHERE b>=0 AND b<1000;<br>
-SELECT count(*), avg(b) FROM t2 WHERE b>=100 AND b<1100;<br>
-<i>... 96 lines omitted</i><br>
-SELECT count(*), avg(b) FROM t2 WHERE b>=9800 AND b<10800;<br>
-SELECT count(*), avg(b) FROM t2 WHERE b>=9900 AND b<10900;<br>
-COMMIT;<br>
-
-</blockquote><table border=0 cellpadding=0 cellspacing=0>
-<tr><td>PostgreSQL:</td><td align="right"> 3.629</td></tr>
-<tr><td>MySQL:</td><td align="right"> 2.760</td></tr>
-<tr><td>SQLite 2.7.6:</td><td align="right"> 2.494</td></tr>
-<tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 2.526</td></tr>
-</table>
-
-
-<p>
-This test does 100 queries on a 25000 entry table without an index,
-thus requiring a full table scan. Prior versions of SQLite used to
-be slower than PostgreSQL and MySQL on this test, but recent performance
-enhancements have increased its speed so that it is now the fastest
-of the group.
-</p>
-
-<h3>Test 5: 100 SELECTs on a string comparison</h3>
-<blockquote>
-BEGIN;<br>
-SELECT count(*), avg(b) FROM t2 WHERE c LIKE '%one%';<br>
-SELECT count(*), avg(b) FROM t2 WHERE c LIKE '%two%';<br>
-<i>... 96 lines omitted</i><br>
-SELECT count(*), avg(b) FROM t2 WHERE c LIKE '%ninety nine%';<br>
-SELECT count(*), avg(b) FROM t2 WHERE c LIKE '%one hundred%';<br>
-COMMIT;<br>
-
-</blockquote><table border=0 cellpadding=0 cellspacing=0>
-<tr><td>PostgreSQL:</td><td align="right"> 13.409</td></tr>
-<tr><td>MySQL:</td><td align="right"> 4.640</td></tr>
-<tr><td>SQLite 2.7.6:</td><td align="right"> 3.362</td></tr>
-<tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 3.372</td></tr>
-</table>
-
-<p>
-This test still does 100 full table scans but it uses
-uses string comparisons instead of numerical comparisons.
-SQLite is over three times faster than PostgreSQL here and about 30%
-faster than MySQL.
-</p>
-
-<h3>Test 6: Creating an index</h3>
-<blockquote>
-CREATE INDEX i2a ON t2(a);<br>CREATE INDEX i2b ON t2(b);
-</blockquote><table border=0 cellpadding=0 cellspacing=0>
-<tr><td>PostgreSQL:</td><td align="right"> 0.381</td></tr>
-<tr><td>MySQL:</td><td align="right"> 0.318</td></tr>
-<tr><td>SQLite 2.7.6:</td><td align="right"> 0.777</td></tr>
-<tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.659</td></tr>
-</table>
-
-<p>
-SQLite is slower at creating new indices. This is not a huge problem
-(since new indices are not created very often) but it is something that
-is being worked on. Hopefully, future versions of SQLite will do better
-here.
-</p>
-
-<h3>Test 7: 5000 SELECTs with an index</h3>
-<blockquote>
-SELECT count(*), avg(b) FROM t2 WHERE b>=0 AND b<100;<br>
-SELECT count(*), avg(b) FROM t2 WHERE b>=100 AND b<200;<br>
-SELECT count(*), avg(b) FROM t2 WHERE b>=200 AND b<300;<br>
-<i>... 4994 lines omitted</i><br>
-SELECT count(*), avg(b) FROM t2 WHERE b>=499700 AND b<499800;<br>
-SELECT count(*), avg(b) FROM t2 WHERE b>=499800 AND b<499900;<br>
-SELECT count(*), avg(b) FROM t2 WHERE b>=499900 AND b<500000;<br>
-
-</blockquote><table border=0 cellpadding=0 cellspacing=0>
-<tr><td>PostgreSQL:</td><td align="right"> 4.614</td></tr>
-<tr><td>MySQL:</td><td align="right"> 1.270</td></tr>
-<tr><td>SQLite 2.7.6:</td><td align="right"> 1.121</td></tr>
-<tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 1.162</td></tr>
-</table>
-
-<p>
-All three database engines run faster when they have indices to work with.
-But SQLite is still the fastest.
-</p>
-
-<h3>Test 8: 1000 UPDATEs without an index</h3>
-<blockquote>
-BEGIN;<br>
-UPDATE t1 SET b=b*2 WHERE a>=0 AND a<10;<br>
-UPDATE t1 SET b=b*2 WHERE a>=10 AND a<20;<br>
-<i>... 996 lines omitted</i><br>
-UPDATE t1 SET b=b*2 WHERE a>=9980 AND a<9990;<br>
-UPDATE t1 SET b=b*2 WHERE a>=9990 AND a<10000;<br>
-COMMIT;<br>
-
-</blockquote><table border=0 cellpadding=0 cellspacing=0>
-<tr><td>PostgreSQL:</td><td align="right"> 1.739</td></tr>
-<tr><td>MySQL:</td><td align="right"> 8.410</td></tr>
-<tr><td>SQLite 2.7.6:</td><td align="right"> 0.637</td></tr>
-<tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.638</td></tr>
-</table>
-
-<p>
-For this particular UPDATE test, MySQL is consistently
-five or ten times
-slower than PostgreSQL and SQLite. I do not know why. MySQL is
-normally a very fast engine. Perhaps this problem has been addressed
-in later versions of MySQL.
-</p>
-
-<h3>Test 9: 25000 UPDATEs with an index</h3>
-<blockquote>
-BEGIN;<br>
-UPDATE t2 SET b=468026 WHERE a=1;<br>
-UPDATE t2 SET b=121928 WHERE a=2;<br>
-<i>... 24996 lines omitted</i><br>
-UPDATE t2 SET b=35065 WHERE a=24999;<br>
-UPDATE t2 SET b=347393 WHERE a=25000;<br>
-COMMIT;<br>
-
-</blockquote><table border=0 cellpadding=0 cellspacing=0>
-<tr><td>PostgreSQL:</td><td align="right"> 18.797</td></tr>
-<tr><td>MySQL:</td><td align="right"> 8.134</td></tr>
-<tr><td>SQLite 2.7.6:</td><td align="right"> 3.520</td></tr>
-<tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 3.104</td></tr>
-</table>
-
-<p>
-As recently as version 2.7.0, SQLite ran at about the same speed as
-MySQL on this test. But recent optimizations to SQLite have more
-than doubled speed of UPDATEs.
-</p>
-
-<h3>Test 10: 25000 text UPDATEs with an index</h3>
-<blockquote>
-BEGIN;<br>
-UPDATE t2 SET c='one hundred forty eight thousand three hundred eighty two' WHERE a=1;<br>
-UPDATE t2 SET c='three hundred sixty six thousand five hundred two' WHERE a=2;<br>
-<i>... 24996 lines omitted</i><br>
-UPDATE t2 SET c='three hundred eighty three thousand ninety nine' WHERE a=24999;<br>
-UPDATE t2 SET c='two hundred fifty six thousand eight hundred thirty' WHERE a=25000;<br>
-COMMIT;<br>
-
-</blockquote><table border=0 cellpadding=0 cellspacing=0>
-<tr><td>PostgreSQL:</td><td align="right"> 48.133</td></tr>
-<tr><td>MySQL:</td><td align="right"> 6.982</td></tr>
-<tr><td>SQLite 2.7.6:</td><td align="right"> 2.408</td></tr>
-<tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 1.725</td></tr>
-</table>
-
-<p>
-Here again, version 2.7.0 of SQLite used to run at about the same speed
-as MySQL. But now version 2.7.6 is over two times faster than MySQL and
-over twenty times faster than PostgreSQL.
-</p>
-
-<p>
-In fairness to PostgreSQL, it started thrashing on this test. A
-knowledgeable administrator might be able to get PostgreSQL to run a lot
-faster here by tweaking and tuning the server a little.
-</p>
-
-<h3>Test 11: INSERTs from a SELECT</h3>
-<blockquote>
-BEGIN;<br>INSERT INTO t1 SELECT b,a,c FROM t2;<br>INSERT INTO t2 SELECT b,a,c FROM t1;<br>COMMIT;
-</blockquote><table border=0 cellpadding=0 cellspacing=0>
-<tr><td>PostgreSQL:</td><td align="right"> 61.364</td></tr>
-<tr><td>MySQL:</td><td align="right"> 1.537</td></tr>
-<tr><td>SQLite 2.7.6:</td><td align="right"> 2.787</td></tr>
-<tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 1.599</td></tr>
-</table>
-
-<p>
-The asynchronous SQLite is just a shade slower than MySQL on this test.
-(MySQL seems to be especially adept at INSERT...SELECT statements.)
-The PostgreSQL engine is still thrashing - most of the 61 seconds it used
-were spent waiting on disk I/O.
-</p>
-
-<h3>Test 12: DELETE without an index</h3>
-<blockquote>
-DELETE FROM t2 WHERE c LIKE '%fifty%';
-</blockquote><table border=0 cellpadding=0 cellspacing=0>
-<tr><td>PostgreSQL:</td><td align="right"> 1.509</td></tr>
-<tr><td>MySQL:</td><td align="right"> 0.975</td></tr>
-<tr><td>SQLite 2.7.6:</td><td align="right"> 4.004</td></tr>
-<tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.560</td></tr>
-</table>
-
-<p>
-The synchronous version of SQLite is the slowest of the group in this test,
-but the asynchronous version is the fastest.
-The difference is the extra time needed to execute fsync().
-</p>
-
-<h3>Test 13: DELETE with an index</h3>
-<blockquote>
-DELETE FROM t2 WHERE a>10 AND a<20000;
-</blockquote><table border=0 cellpadding=0 cellspacing=0>
-<tr><td>PostgreSQL:</td><td align="right"> 1.316</td></tr>
-<tr><td>MySQL:</td><td align="right"> 2.262</td></tr>
-<tr><td>SQLite 2.7.6:</td><td align="right"> 2.068</td></tr>
-<tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.752</td></tr>
-</table>
-
-<p>
-This test is significant because it is one of the few where
-PostgreSQL is faster than MySQL. The asynchronous SQLite is,
-however, faster then both the other two.
-</p>
-
-<h3>Test 14: A big INSERT after a big DELETE</h3>
-<blockquote>
-INSERT INTO t2 SELECT * FROM t1;
-</blockquote><table border=0 cellpadding=0 cellspacing=0>
-<tr><td>PostgreSQL:</td><td align="right"> 13.168</td></tr>
-<tr><td>MySQL:</td><td align="right"> 1.815</td></tr>
-<tr><td>SQLite 2.7.6:</td><td align="right"> 3.210</td></tr>
-<tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 1.485</td></tr>
-</table>
-
-<p>
-Some older versions of SQLite (prior to version 2.4.0)
-would show decreasing performance after a
-sequence of DELETEs followed by new INSERTs. As this test shows, the
-problem has now been resolved.
-</p>
-
-<h3>Test 15: A big DELETE followed by many small INSERTs</h3>
-<blockquote>
-BEGIN;<br>
-DELETE FROM t1;<br>
-INSERT INTO t1 VALUES(1,10719,'ten thousand seven hundred nineteen');<br>
-<i>... 11997 lines omitted</i><br>
-INSERT INTO t1 VALUES(11999,72836,'seventy two thousand eight hundred thirty six');<br>
-INSERT INTO t1 VALUES(12000,64231,'sixty four thousand two hundred thirty one');<br>
-COMMIT;<br>
-
-</blockquote><table border=0 cellpadding=0 cellspacing=0>
-<tr><td>PostgreSQL:</td><td align="right"> 4.556</td></tr>
-<tr><td>MySQL:</td><td align="right"> 1.704</td></tr>
-<tr><td>SQLite 2.7.6:</td><td align="right"> 0.618</td></tr>
-<tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.406</td></tr>
-</table>
-
-<p>
-SQLite is very good at doing INSERTs within a transaction, which probably
-explains why it is so much faster than the other databases at this test.
-</p>
-
-<h3>Test 16: DROP TABLE</h3>
-<blockquote>
-DROP TABLE t1;<br>DROP TABLE t2;<br>DROP TABLE t3;
-</blockquote><table border=0 cellpadding=0 cellspacing=0>
-<tr><td>PostgreSQL:</td><td align="right"> 0.135</td></tr>
-<tr><td>MySQL:</td><td align="right"> 0.015</td></tr>
-<tr><td>SQLite 2.7.6:</td><td align="right"> 0.939</td></tr>
-<tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.254</td></tr>
-</table>
-
-<p>
-SQLite is slower than the other databases when it comes to dropping tables.
-This probably is because when SQLite drops a table, it has to go through and
-erase the records in the database file that deal with that table. MySQL and
-PostgreSQL, on the other hand, use separate files to represent each table
-so they can drop a table simply by deleting a file, which is much faster.
-</p>
-
-<p>
-On the other hand, dropping tables is not a very common operation
-so if SQLite takes a little longer, that is not seen as a big problem.
-</p>
-
-}
-footer $rcsid
+++ /dev/null
-#
-# Run this Tcl script to generate the sqlite.html file.
-#
-set rcsid {$Id: sqlite.tcl,v 1.25 2007/01/08 14:31:36 drh Exp $}
-source common.tcl
-header {sqlite3: A command-line access program for SQLite databases}
-puts {
-<h2>sqlite3: A command-line access program for SQLite databases</h2>
-
-<p>The SQLite library includes a simple command-line utility named
-<b>sqlite3</b> that allows the user to manually enter and execute SQL
-commands against an SQLite database. This document provides a brief
-introduction on how to use <b>sqlite3</b>.
-
-<h3>Getting Started</h3>
-
-<p>To start the <b>sqlite3</b> program, just type "sqlite3" followed by
-the name the file that holds the SQLite database. If the file does
-not exist, a new one is created automatically.
-The <b>sqlite3</b> program will
-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>
-}
-
-proc Code {body} {
- puts {<blockquote><tt>}
- regsub -all {&} [string trim $body] {\&} body
- regsub -all {>} $body {\>} body
- regsub -all {<} $body {\<} body
- regsub -all {\(\(\(} $body {<b>} body
- regsub -all {\)\)\)} $body {</b>} body
- regsub -all { } $body {\ } body
- regsub -all \n $body <br>\n body
- puts $body
- puts {</tt></blockquote>}
-}
-
-Code {
-$ (((sqlite3 ex1)))
-SQLite version 3.3.10
-Enter ".help" for instructions
-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;)))
-hello!|10
-goodbye|20
-sqlite>
-}
-
-puts {
-<p>You can terminate the sqlite3 program by typing your systems
-End-Of-File character (usually a Control-D) or the interrupt
-character (usually a Control-C).</p>
-
-<p>Make sure you type a semicolon at the end of each SQL command!
-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>
-}
-
-Code {
-sqlite> (((CREATE TABLE tbl2 ()))
- ...> ((( f1 varchar(30) primary key,)))
- ...> ((( f2 text,)))
- ...> ((( f3 real)))
- ...> ((();)))
-sqlite>
-}
-
-puts {
-
-<h3>Aside: Querying the SQLITE_MASTER table</h3>
-
-<p>The database schema in an SQLite database is stored in
-a special table named "sqlite_master".
-You can execute "SELECT" statements against the
-special sqlite_master table just like any other table
-in an SQLite database. For example:</p>
-}
-
-Code {
-$ (((sqlite3 ex1)))
-SQlite vresion 3.3.10
-Enter ".help" for instructions
-sqlite> (((select * from sqlite_master;)))
- type = table
- name = tbl1
-tbl_name = tbl1
-rootpage = 3
- sql = create table tbl1(one varchar(10), two smallint)
-sqlite>
-}
-
-puts {
-<p>
-But you cannot execute DROP TABLE, UPDATE, INSERT or DELETE against
-the sqlite_master table. The sqlite_master
-table is updated automatically as you create or drop tables and
-indices from the database. You can not make manual changes
-to the sqlite_master table.
-</p>
-
-<p>
-The schema for TEMPORARY tables is not stored in the "sqlite_master" table
-since TEMPORARY tables are not visible to applications other than the
-application that created the table. The schema for TEMPORARY tables
-is stored in another special table named "sqlite_temp_master". The
-"sqlite_temp_master" table is temporary itself.
-</p>
-
-<h3>Special commands to sqlite3</h3>
-
-<p>
-Most of the time, sqlite3 just reads lines of input and passes them
-on to the SQLite library for execution.
-But if an input line begins with a dot ("."), then
-that line is intercepted and interpreted by the sqlite3 program itself.
-These "dot commands" are typically used to change the output format
-of queries, or to execute certain prepackaged query statements.
-</p>
-
-<p>
-For a listing of the available dot commands, you can enter ".help"
-at any time. For example:
-</p>}
-
-Code {
-sqlite> (((.help)))
-.bail ON|OFF Stop after hitting an error. Default OFF
-.databases List names and files of attached databases
-.dump ?TABLE? ... Dump the database in an SQL text format
-.echo ON|OFF Turn command echo on or off
-.exit Exit this program
-.explain ON|OFF Turn output mode suitable for EXPLAIN on or off.
-.header(s) ON|OFF Turn display of headers on or off
-.help Show this message
-.import FILE TABLE Import data from FILE into TABLE
-.indices TABLE Show names of all indices on TABLE
-.load FILE ?ENTRY? Load an extension library
-.mode MODE ?TABLE? Set output mode where MODE is one of:
- csv Comma-separated values
- column Left-aligned columns. (See .width)
- html HTML <table> code
- insert SQL insert statements for TABLE
- line One value per line
- list Values delimited by .separator string
- tabs Tab-separated values
- tcl TCL list elements
-.nullvalue STRING Print STRING in place of NULL values
-.output FILENAME Send output to FILENAME
-.output stdout Send output to the screen
-.prompt MAIN CONTINUE Replace the standard prompts
-.quit Exit this program
-.read FILENAME Execute SQL in FILENAME
-.schema ?TABLE? Show the CREATE statements
-.separator STRING Change separator used by output mode and .import
-.show Show the current values for various settings
-.tables ?PATTERN? List names of tables matching a LIKE pattern
-.timeout MS Try opening locked tables for MS milliseconds
-.width NUM NUM ... Set column widths for "column" mode
-sqlite>
-}
-
-puts {
-<h3>Changing Output Formats</h3>
-
-<p>The sqlite3 program is able to show the results of a query
-in eight different formats: "csv", "column", "html", "insert",
-"line", "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>}
-
-Code {
-sqlite> (((.mode list)))
-sqlite> (((select * from tbl1;)))
-hello|10
-goodbye|20
-sqlite>
-}
-
-puts {
-<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>}
-
-Code {
-sqlite> (((.separator ", ")))
-sqlite> (((select * from tbl1;)))
-hello, 10
-goodbye, 20
-sqlite>
-}
-
-puts {
-<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>}
-
-Code {
-sqlite> (((.mode line)))
-sqlite> (((select * from tbl1;)))
-one = hello
-two = 10
-
-one = goodbye
-two = 20
-sqlite>
-}
-
-puts {
-<p>In column mode, each record is shown on a separate line with the
-data aligned in columns. For example:</p>}
-
-Code {
-sqlite> (((.mode column)))
-sqlite> (((select * from tbl1;)))
-one two
----------- ----------
-hello 10
-goodbye 20
-sqlite>
-}
-
-puts {
-<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>}
-
-Code {
-sqlite> (((.width 12 6)))
-sqlite> (((select * from tbl1;)))
-one two
------------- ------
-hello 10
-goodbye 20
-sqlite>
-}
-
-puts {
-<p>The ".width" command in the example above sets the width of the first
-column to 12 and the width of the second column to 6. All other column
-widths were unaltered. You can gives as many arguments to ".width" as
-necessary to specify the widths of as many columns as are in your
-query results.</p>
-
-<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>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>}
-
-Code {
-sqlite> (((.header off)))
-sqlite> (((select * from tbl1;)))
-hello 10
-goodbye 20
-sqlite>
-}
-
-puts {
-<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>
-}
-
-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>
-}
-
-puts {
-<p>The last output mode is "html". In this mode, sqlite3 writes
-the results of the query as an XHTML table. The beginning
-<TABLE> and the ending </TABLE> are not written, but
-all of the intervening <TR>s, <TH>s, and <TD>s
-are. The html output mode is envisioned as being useful for
-CGI.</p>
-}
-
-puts {
-<h3>Writing results to a file</h3>
-
-<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>}
-
-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
-goodbye|20
-$
-}
-
-puts {
-<h3>Querying the database schema</h3>
-
-<p>The sqlite3 program provides several convenience commands that
-are useful for looking at the schema of the database. There is
-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>
-}
-
-Code {
-sqlite> (((.tables)))
-tbl1
-tbl2
-sqlite>
-}
-
-puts {
-<p>The ".tables" command is similar to setting list mode then
-executing the following query:</p>
-
-<blockquote><pre>
-SELECT name FROM sqlite_master
-WHERE type IN ('table','view') AND name NOT LIKE 'sqlite_%'
-UNION ALL
-SELECT name FROM sqlite_temp_master
-WHERE type IN ('table','view')
-ORDER BY 1
-</pre></blockquote>
-
-<p>In fact, if you look at the source code to the sqlite3 program
-(found in the source tree in the file src/shell.c) you'll find
-exactly the above query.</p>
-
-<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>}
-
-Code {
-sqlite> (((.schema)))
-create table tbl1(one varchar(10), two smallint)
-CREATE TABLE tbl2 (
- f1 varchar(30) primary key,
- f2 text,
- f3 real
-)
-sqlite> (((.schema tbl2)))
-CREATE TABLE tbl2 (
- f1 varchar(30) primary key,
- f2 text,
- f3 real
-)
-sqlite>
-}
-
-puts {
-<p>The ".schema" command accomplishes the same thing as setting
-list mode, then entering the following query:</p>
-
-<blockquote><pre>
-SELECT sql FROM
- (SELECT * FROM sqlite_master UNION ALL
- SELECT * FROM sqlite_temp_master)
-WHERE type!='meta'
-ORDER BY tbl_name, type DESC, name
-</pre></blockquote>
-
-<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>
-
-<blockquote><pre>
-SELECT sql FROM
- (SELECT * FROM sqlite_master UNION ALL
- SELECT * FROM sqlite_temp_master)
-WHERE type!='meta' AND sql NOT NULL AND name NOT LIKE 'sqlite_%'
-ORDER BY substr(type,2,1), name
-</pre></blockquote>
-
-<p>
-You can supply an argument to the .schema command. If you do, the
-query looks like this:
-</p>
-
-<blockquote><pre>
-SELECT sql FROM
- (SELECT * FROM sqlite_master UNION ALL
- SELECT * FROM sqlite_temp_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
-</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>
-}
-
-Code {
-sqlite> (((.schema %abc%)))
-}
-
-puts {
-<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>}
-
-Code {
-sqlite> (((.databases)))
-}
-
-puts {
-<h3>Converting An Entire Database To An ASCII Text File</h3>
-
-<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>
-}
-
-Code {
-$ (((echo '.dump' | sqlite3 ex1 | gzip -c >ex1.dump.gz)))
-}
-
-puts {
-<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>
-}
-
-Code {
-$ (((zcat ex1.dump.gz | sqlite3 ex2)))
-}
-
-puts {
-<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>
-}
-
-Code {
-$ (((createdb ex2)))
-$ (((sqlite3 ex1 .dump | psql ex2)))
-}
-
-puts {
-<h3>Other Dot Commands</h3>
-
-<p>The ".explain" dot command can be used to set the output mode
-to "column" and to set the column widths to values that are reasonable
-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>}
-
-Code {
-sqlite> (((.explain)))
-sqlite> (((explain delete from tbl1 where two<20;)))
-addr opcode p1 p2 p3
----- ------------ ----- ----- -------------------------------------
-0 ListOpen 0 0
-1 Open 0 1 tbl1
-2 Next 0 9
-3 Field 0 1
-4 Integer 20 0
-5 Ge 0 2
-6 Key 0 0
-7 ListWrite 0 0
-8 Goto 0 2
-9 Noop 0 0
-10 ListRewind 0 0
-11 ListRead 0 14
-12 Delete 0 0
-13 Goto 0 11
-14 ListClose 0 0
-}
-
-puts {
-
-<p>The ".timeout" command sets the amount of time that the <b>sqlite3</b>
-program will wait for locks to clear on files it is trying to access
-before returning an error. The default value of the timeout is zero so
-that an error is returned immediately if any needed database table or
-index is locked.</p>
-
-<p>And finally, we mention the ".exit" command which causes the
-sqlite3 program to exit.</p>
-
-<h3>Using sqlite3 in a shell script</h3>
-
-<p>
-One way to use sqlite3 in a shell script is to use "echo" or
-"cat" to generate a sequence of commands in a file, then invoke sqlite3
-while redirecting input from the generated command file. This
-works fine and is appropriate in many circumstances. But as
-an added convenience, sqlite3 allows a single SQL command to be
-entered on the command line as a second argument after the
-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>}
-
-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
-$
-}
-
-puts {
-<h3>Ending shell commands</h3>
-
-<p>
-SQLite commands are normally terminated by a semicolon. In the shell
-you can also use the word "GO" (case-insensitive) or a slash character
-"/" on a line by itself to end a command. These are used by SQL Server
-and Oracle, respectively. These won't work in <b>sqlite3_exec()</b>,
-because the shell translates these into a semicolon before passing them
-to that function.</p>
-}
-
-puts {
-<h3>Compiling the sqlite3 program from sources</h3>
-
-<p>
-The sqlite3 program is built automatically when you compile the
-SQLite library. Just get a copy of the source tree, run
-"configure" and then "make".</p>
-}
-footer $rcsid
+++ /dev/null
-set rcsid {$Id: support.tcl,v 1.7 2007/06/21 13:30:40 drh Exp $}
-source common.tcl
-header {SQLite Support Options}
-puts {
-<h2>SQLite Support Options</h2>
-
-
-<h3>Mailing List</h3>
-<p>
-A mailing list has been set up for asking questions and
-for open discussion of problems
-and issues by the SQLite user community.
-To subscribe to the mailing list, send an email to
-<a href="mailto:sqlite-users-subscribe@sqlite.org">
-sqlite-users-subscribe@sqlite.org</a>.
-If you would prefer to get digests rather than individual
-emails, send a message to to
-<a href="mailto:sqlite-users-digest-subscribe@sqlite.org">
-sqlite-users-digest-subscribe@sqlite.org</a>.
-For additional information about operating and using this
-mailing list, send a message to
-<a href="mailto:sqlite-users-help@sqlite.org">
-sqlite-users-help@sqlite.org</a> and instructions will be
-sent by to you by return email.
-</p>
-
-<p>
-There are multiple archives of the mailing list:
-</p>
-
-<blockquote>
-<a href="http://www.mail-archive.com/sqlite-users%40sqlite.org/">
-http://www.mail-archive.com/sqlite-users%40sqlite.org</a><br>
-<a href="http://marc.info/?l=sqlite-users&r=1&w=2">
-http://marc.info/?l=sqlite-users&r=1&w=2</a><br>
-<a href="http://news.gmane.org/gmane.comp.db.sqlite.general">
-http://news.gmane.org/gmane.comp.db.sqlite.general</a>
-</blockquote>
-
-</p>
-
-<a name="directemail">
-<h3>Direct E-Mail To The Author</h3>
-
-<p>
-Use the mailing list.
-Please do <b>not</b> send email directly to the author of SQLite
-unless:
-<ul>
-<li>You have or intend to acquire a professional support contract
-as described below, or</li>
-<li>You are working on an open source project.</li>
-</ul>
-You are welcomed to use SQLite in closed source, proprietary, and/or
-commerical projects and to ask questions about such use on the public
-mailing list. But please do not ask to receive free direct technical
-support. The software is free; direct technical support is not.
-</p>
-
-
-<h3>Professional Support</h3>
-
-<p>
-If you would like professional support for SQLite
-or if you want custom modifications to SQLite performed by the
-original author, these services are available for a modest fee.
-For additional information visit
-<a href="http://www.hwaci.com/sw/sqlite/prosupport.html">
-http://www.hwaci.com/sw/sqlite/prosupport.html</a> or contact:</p>
-
-<blockquote>
-D. Richard Hipp <br />
-Hwaci - Applied Software Research <br />
-704.948.4565 <br />
-<a href="mailto:drh@hwaci.com">drh@hwaci.com</a>
-</blockquote>
-
-}
-footer $rcsid
+++ /dev/null
-#
-# Run this Tcl script to generate the tclsqlite.html file.
-#
-set rcsid {$Id: tclsqlite.tcl,v 1.17 2007/06/19 17:48:57 drh Exp $}
-source common.tcl
-header {The Tcl interface to the SQLite library}
-proc METHOD {name text} {
- puts "<a name=\"$name\">\n<h3>The \"$name\" method</h3>\n"
- puts $text
-}
-puts {
-<h2>The Tcl interface to the SQLite library</h2>
-
-<p>The SQLite library is designed to be very easy to use from
-a Tcl or Tcl/Tk script. This document gives an overview of the Tcl
-programming interface.</p>
-
-<h3>The API</h3>
-
-<p>The interface to the SQLite library consists of single
-tcl command named <b>sqlite3</b>
-Because there is only this
-one command, the interface is not placed in a separate
-namespace.</p>
-
-<p>The <b>sqlite3</b> command is used as follows:</p>
-
-<blockquote>
-<b>sqlite3</b> <i>dbcmd database-name</i>
-</blockquote>
-
-<p>
-The <b>sqlite3</b> command opens the database named in the second
-argument. If the database does not already exist, it is
-automatically created.
-The <b>sqlite3</b> command also creates a new Tcl
-command to control the database. The name of the new Tcl command
-is given by the first argument. This approach is similar to the
-way widgets are created in Tk.
-</p>
-
-<p>
-The name of the database is just the name of a disk file in which
-the database is stored. If the name of the database is an empty
-string or the special name ":memory:" then a new database is created
-in memory.
-</p>
-
-<p>
-Once an SQLite database is open, it can be controlled using
-methods of the <i>dbcmd</i>. There are currently 22 methods
-defined.</p>
-
-<p>
-<ul>
-}
-foreach m [lsort {
- authorizer
- busy
- cache
- changes
- close
- collate
- collation_needed
- commit_hook
- complete
- copy
- enable_load_extension
- errorcode
- eval
- exists
- function
- last_insert_rowid
- nullvalue
- onecolumn
- profile
- progress
- rollback_hook
- timeout
- total_changes
- trace
- transaction
- update_hook
- version
-}] {
- puts "<li><a href=\"#$m\">$m</a></li>"
-}
-puts {
-</ul>
-</p>
-
-<p>The use of each of these methods will be explained in the sequel, though
-not in the order shown above.</p>
-
-}
-
-##############################################################################
-METHOD eval {
-<p>
-The most useful <i>dbcmd</i> method is "eval". The eval method is used
-to execute SQL on the database. The syntax of the eval method looks
-like this:</p>
-
-<blockquote>
-<i>dbcmd</i> <b>eval</b> <i>sql</i>
- ?<i>array-name </i>? ?<i>script</i>?
-</blockquote>
-
-<p>
-The job of the eval method is to execute the SQL statement or statements
-given in the second argument. For example, to create a new table in
-a database, you can do this:</p>
-
-<blockquote>
-<b>sqlite3 db1 ./testdb<br>
-db1 eval {CREATE TABLE t1(a int, b text)}</b>
-</blockquote>
-
-<p>The above code creates a new table named <b>t1</b> with columns
-<b>a</b> and <b>b</b>. What could be simpler?</p>
-
-<p>Query results are returned as a list of column values. If a
-query requests 2 columns and there are 3 rows matching the query,
-then the returned list will contain 6 elements. For example:</p>
-
-<blockquote>
-<b>db1 eval {INSERT INTO t1 VALUES(1,'hello')}<br>
-db1 eval {INSERT INTO t1 VALUES(2,'goodbye')}<br>
-db1 eval {INSERT INTO t1 VALUES(3,'howdy!')}<br>
-set x [db1 eval {SELECT * FROM t1 ORDER BY a}]</b>
-</blockquote>
-
-<p>The variable <b>$x</b> is set by the above code to</p>
-
-<blockquote>
-<b>1 hello 2 goodbye 3 howdy!</b>
-</blockquote>
-
-<p>You can also process the results of a query one row at a time
-by specifying the name of an array variable and a script following
-the SQL code. For each row of the query result, the values of all
-columns will be inserted into the array variable and the script will
-be executed. For instance:</p>
-
-<blockquote>
-<b>db1 eval {SELECT * FROM t1 ORDER BY a} values {<br>
- parray values<br>
- puts ""<br>
-}</b>
-</blockquote>
-
-<p>This last code will give the following output:</p>
-
-<blockquote><b>
-values(*) = a b<br>
-values(a) = 1<br>
-values(b) = hello<p>
-
-values(*) = a b<br>
-values(a) = 2<br>
-values(b) = goodbye<p>
-
-values(*) = a b<br>
-values(a) = 3<br>
-values(b) = howdy!</b>
-</blockquote>
-
-<p>
-For each column in a row of the result, the name of that column
-is used as an index in to array. The value of the column is stored
-in the corresponding array entry. The special array index * is
-used to store a list of column names in the order that they appear.
-</p>
-
-<p>
-If the array variable name is omitted or is the empty string, then the value of
-each column is stored in a variable with the same name as the column
-itself. For example:
-</p>
-
-<blockquote>
-<b>db1 eval {SELECT * FROM t1 ORDER BY a} {<br>
- puts "a=$a b=$b"<br>
-}</b>
-</blockquote>
-
-<p>
-From this we get the following output
-</p>
-
-<blockquote><b>
-a=1 b=hello<br>
-a=2 b=goodbye<br>
-a=3 b=howdy!</b>
-</blockquote>
-
-<p>
-Tcl variable names can appear in the SQL statement of the second argument
-in any position where it is legal to put a string or number literal. The
-value of the variable is substituted for the variable name. If the
-variable does not exist a NULL values is used. For example:
-</p>
-
-<blockquote><b>
-db1 eval {INSERT INTO t1 VALUES(5,$bigstring)}
-</b></blockquote>
-
-<p>
-Note that it is not necessary to quote the $bigstring value. That happens
-automatically. If $bigstring is a large string or binary object, this
-technique is not only easier to write, it is also much more efficient
-since it avoids making a copy of the content of $bigstring.
-</p>
-
-<p>
-If the $bigstring variable has both a string and a "bytearray" representation,
-then TCL inserts the value as a string. If it has only a "bytearray"
-representation, then the value is inserted as a BLOB. To force a
-value to be inserted as a BLOB even if it also has a text representation,
-us a "@" character to in place of the "$". Like this:
-</p>
-
-<blockquote><b>
-db1 eval {INSERT INTO t1 VALUES(5,@bigstring)}
-</b></blockquote>
-
-<p>
-If the variable does not have a bytearray representation, then "@" works
-just like "$".
-</p>
-
-}
-
-##############################################################################
-METHOD close {
-
-<p>
-As its name suggests, the "close" method to an SQLite database just
-closes the database. This has the side-effect of deleting the
-<i>dbcmd</i> Tcl command. Here is an example of opening and then
-immediately closing a database:
-</p>
-
-<blockquote>
-<b>sqlite3 db1 ./testdb<br>
-db1 close</b>
-</blockquote>
-
-<p>
-If you delete the <i>dbcmd</i> directly, that has the same effect
-as invoking the "close" method. So the following code is equivalent
-to the previous:</p>
-
-<blockquote>
-<b>sqlite3 db1 ./testdb<br>
-rename db1 {}</b>
-</blockquote>
-}
-
-##############################################################################
-METHOD transaction {
-
-<p>
-The "transaction" method is used to execute a TCL script inside an SQLite
-database transaction. The transaction is committed when the script completes,
-or it rolls back if the script fails. If the transaction occurs within
-another transaction (even one that is started manually using BEGIN) it
-is a no-op.
-</p>
-
-<p>
-The transaction command can be used to group together several SQLite
-commands in a safe way. You can always start transactions manually using
-BEGIN, of
-course. But if an error occurs so that the COMMIT or ROLLBACK are never
-run, then the database will remain locked indefinitely. Also, BEGIN
-does not nest, so you have to make sure no other transactions are active
-before starting a new one. The "transaction" method takes care of
-all of these details automatically.
-</p>
-
-<p>
-The syntax looks like this:
-</p>
-
-<blockquote>
-<i>dbcmd</i> <b>transaction</b> <i>?transaction-type?</i>
- <i>SCRIPT,</i>
-</blockquote>
-
-
-<p>
-The <i>transaction-type</i> can be one of <b>deferred</b>,
-<b>exclusive</b> or <b>immediate</b>. The default is deferred.
-</p>
-}
-
-##############################################################################
-METHOD cache {
-
-<p>
-The "eval" method described <a href="#eval">above</a> keeps a cache of
-<a href="capi3ref.html#sqlite3_prepare">prepared statements</a>
-for recently evaluated SQL commands.
-The "cache" method is used to control this cache.
-The first form of this command is:</p>
-
-<blockquote>
-<i>dbcmd</i> <b>cache size</b> <i>N</i>
-</blockquote>
-
-<p>This sets the maximum number of statements that can be cached.
-The upper limit is 100. The default is 10. If you set the cache size
-to 0, no caching is done.</p>
-
-<p>The second form of the command is this:</p>
-
-
-<blockquote>
-<i>dbcmd</i> <b>cache flush</b>
-</blockquote>
-
-<p>The cache-flush method
-<a href="capi3ref.html#sqlite3_finalize">finalizes</a>
-all prepared statements currently
-in the cache.</p>
-
-}
-
-##############################################################################
-METHOD complete {
-
-<p>
-The "complete" method takes a string of supposed SQL as its only argument.
-It returns TRUE if the string is a complete statement of SQL and FALSE if
-there is more to be entered.</p>
-
-<p>The "complete" method is useful when building interactive applications
-in order to know when the user has finished entering a line of SQL code.
-This is really just an interface to the
-<a href="capi3ref.html#sqlite3_complete"><b>sqlite3_complete()</b></a> C
-function.
-}
-
-##############################################################################
-METHOD copy {
-
-<p>
-The "copy" method copies data from a file into a table.
-It returns the number of rows processed successfully from the file.
-The syntax of the copy method looks like this:</p>
-
-<blockquote>
-<i>dbcmd</i> <b>copy</b> <i>conflict-algorithm</i>
- <i>table-name </i> <i>file-name </i>
- ?<i>column-separator </i>?
- ?<i>null-indicator</i>?
-</blockquote>
-
-<p>Conflict-alogrithm must be one of the SQLite conflict algorithms for
-the INSERT statement: <i>rollback</i>, <i>abort</i>,
-<i>fail</i>,<i>ignore</i>, or <i>replace</i>. See the SQLite Language
-section for <a href="lang.html#conflict">ON CONFLICT</a> for more information.
-The conflict-algorithm must be specified in lower case.
-</p>
-
-<p>Table-name must already exists as a table. File-name must exist, and
-each row must contain the same number of columns as defined in the table.
-If a line in the file contains more or less than the number of columns defined,
-the copy method rollbacks any inserts, and returns an error.</p>
-
-<p>Column-separator is an optional column separator string. The default is
-the ASCII tab character \t. </p>
-
-<p>Null-indicator is an optional string that indicates a column value is null.
-The default is an empty string. Note that column-separator and
-null-indicator are optional positional arguments; if null-indicator
-is specified, a column-separator argument must be specifed and
-precede the null-indicator argument.</p>
-
-<p>The copy method implements similar functionality to the <b>.import</b>
-SQLite shell command.
-The SQLite 2.x <a href="lang.html#copy"><b>COPY</b></a> statement
-(using the PostgreSQL COPY file format)
-can be implemented with this method as:</p>
-
-<blockquote>
-dbcmd copy $conflictalgo
- $tablename $filename
- \t
- \\N
-</blockquote>
-
-}
-
-##############################################################################
-METHOD timeout {
-
-<p>The "timeout" method is used to control how long the SQLite library
-will wait for locks to clear before giving up on a database transaction.
-The default timeout is 0 millisecond. (In other words, the default behavior
-is not to wait at all.)</p>
-
-<p>The SQLite database allows multiple simultaneous
-readers or a single writer but not both. If any process is writing to
-the database no other process is allows to read or write. If any process
-is reading the database other processes are allowed to read but not write.
-The entire database shared a single lock.</p>
-
-<p>When SQLite tries to open a database and finds that it is locked, it
-can optionally delay for a short while and try to open the file again.
-This process repeats until the query times out and SQLite returns a
-failure. The timeout is adjustable. It is set to 0 by default so that
-if the database is locked, the SQL statement fails immediately. But you
-can use the "timeout" method to change the timeout value to a positive
-number. For example:</p>
-
-<blockquote><b>db1 timeout 2000</b></blockquote>
-
-<p>The argument to the timeout method is the maximum number of milliseconds
-to wait for the lock to clear. So in the example above, the maximum delay
-would be 2 seconds.</p>
-}
-
-##############################################################################
-METHOD busy {
-
-<p>The "busy" method, like "timeout", only comes into play when the
-database is locked. But the "busy" method gives the programmer much more
-control over what action to take. The "busy" method specifies a callback
-Tcl procedure that is invoked whenever SQLite tries to open a locked
-database. This callback can do whatever is desired. Presumably, the
-callback will do some other useful work for a short while (such as service
-GUI events) then return
-so that the lock can be tried again. The callback procedure should
-return "0" if it wants SQLite to try again to open the database and
-should return "1" if it wants SQLite to abandon the current operation.
-}
-
-##############################################################################
-METHOD exists {
-
-<p>The "exists" method is similar to "onecolumn" and "eval" in that
-it executes SQL statements. The difference is that the "exists" method
-always returns a boolean value which is TRUE if a query in the SQL
-statement it executes returns one or more rows and FALSE if the SQL
-returns an empty set.</p>
-
-<p>The "exists" method is often used to test for the existance of
-rows in a table. For example:</p>
-
-<blockquote><b>
-if {[db exists {SELECT 1 FROM table1 WHERE user=$user}]} {<br>
- # Processing if $user exists<br>
-} else {<br>
- # Processing if $user does not exist<br>
-}
-</b></blockquote>
-}
-
-
-##############################################################################
-METHOD last_insert_rowid {
-
-<p>The "last_insert_rowid" method returns an integer which is the ROWID
-of the most recently inserted database row.</p>
-}
-
-##############################################################################
-METHOD function {
-
-<p>The "function" method registers new SQL functions with the SQLite engine.
-The arguments are the name of the new SQL function and a TCL command that
-implements that function. Arguments to the function are appended to the
-TCL command before it is invoked.</p>
-
-<p>
-The following example creates a new SQL function named "hex" that converts
-its numeric argument in to a hexadecimal encoded string:
-</p>
-
-<blockquote><b>
-db function hex {format 0x%X}
-</b></blockquote>
-
-}
-
-##############################################################################
-METHOD nullvalue {
-
-<p>
-The "nullvalue" method changes the representation for NULL returned
-as result of the "eval" method.</p>
-
-<blockquote><b>
-db1 nullvalue NULL
-</b></blockquote>
-
-<p>The "nullvalue" method is useful to differ between NULL and empty
-column values as Tcl lacks a NULL representation. The default
-representation for NULL values is an empty string.</p>
-}
-
-
-
-##############################################################################
-METHOD onecolumn {
-
-<p>The "onecolumn" method works like
-"<a href="#eval">eval</a>" in that it evaluates the
-SQL query statement given as its argument. The difference is that
-"onecolumn" returns a single element which is the first column of the
-first row of the query result.</p>
-
-<p>This is a convenience method. It saves the user from having to
-do a "<tt>[lindex ... 0]</tt>" on the results of an "eval"
-in order to extract a single column result.</p>
-}
-
-##############################################################################
-METHOD changes {
-
-<p>The "changes" method returns an integer which is the number of rows
-in the database that were inserted, deleted, and/or modified by the most
-recent "eval" method.</p>
-}
-
-##############################################################################
-METHOD total_changes {
-
-<p>The "total_changes" method returns an integer which is the number of rows
-in the database that were inserted, deleted, and/or modified since the
-current database connection was first opened.</p>
-}
-
-##############################################################################
-METHOD authorizer {
-
-<p>The "authorizer" method provides access to the
-<a href="capi3ref.html#sqlite3_set_authorizer">sqlite3_set_authorizer</a>
-C/C++ interface. The argument to authorizer is the name of a procedure that
-is called when SQL statements are being compiled in order to authorize
-certain operations. The callback procedure takes 5 arguments which describe
-the operation being coded. If the callback returns the text string
-"SQLITE_OK", then the operation is allowed. If it returns "SQLITE_IGNORE",
-then the operation is silently disabled. If the return is "SQLITE_DENY"
-then the compilation fails with an error.
-</p>
-
-<p>If the argument is an empty string then the authorizer is disabled.
-If the argument is omitted, then the current authorizer is returned.</p>
-}
-
-##############################################################################
-METHOD progress {
-
-<p>This method registers a callback that is invoked periodically during
-query processing. There are two arguments: the number of SQLite virtual
-machine opcodes between invocations, and the TCL command to invoke.
-Setting the progress callback to an empty string disables it.</p>
-
-<p>The progress callback can be used to display the status of a lengthy
-query or to process GUI events during a lengthy query.</p>
-}
-
-
-##############################################################################
-METHOD collate {
-
-<p>This method registers new text collating sequences. There are
-two arguments: the name of the collating sequence and the name of a
-TCL procedure that implements a comparison function for the collating
-sequence.
-</p>
-
-<p>For example, the following code implements a collating sequence called
-"NOCASE" that sorts in text order without regard to case:
-</p>
-
-<blockquote><b>
-proc nocase_compare {a b} {<br>
- return [string compare [string tolower $a] [string tolower $b]]<br>
-}<br>
-db collate NOCASE nocase_compare<br>
-</b></blockquote>
-}
-
-##############################################################################
-METHOD collation_needed {
-
-<p>This method registers a callback routine that is invoked when the SQLite
-engine needs a particular collating sequence but does not have that
-collating sequence registered. The callback can register the collating
-sequence. The callback is invoked with a single parameter which is the
-name of the needed collating sequence.</p>
-}
-
-##############################################################################
-METHOD commit_hook {
-
-<p>This method registers a callback routine that is invoked just before
-SQLite tries to commit changes to a database. If the callback throws
-an exception or returns a non-zero result, then the transaction rolls back
-rather than commit.</p>
-}
-
-##############################################################################
-METHOD rollback_hook {
-
-<p>This method registers a callback routine that is invoked just before
-SQLite tries to do a rollback. The script argument is run without change.</p>
-}
-
-##############################################################################
-METHOD update_hook {
-
-<p>This method registers a callback routine that is invoked just before
-each row is modified by an UPDATE, INSERT, or DELETE statement. Four
-arguments are appended to the callback before it is invoked:</p>
-
-<ul>
-<li>The keyword "INSERT", "UPDATE", or "DELETE", as appropriate</li>
-<li>The name of the database which is being changed</li>
-<li>The table that is being changed</li>
-<li>The rowid of the row in the table being changed</li>
-</ul>
-}
-
-##############################################################################
-METHOD incrblob {
-
-<p>This method opens a TCL channel that can be used to read or write
-into a preexisting BLOB in the database. The syntax is like this:</p>
-
-<blockquote>
-<i>dbcmd</i> <b>incrblob</b> <b>?-readonly??</b>
- <i>?DB? TABLE COLUMN ROWID</i>
-</blockquote>
-
-<p>
-The command returns a new TCL channel for reading or writing to the BLOB.
-The channel is opened using the underlying
-<a href="/capi3ref.html#sqlite3_blob_open">sqlite3_blob_open()</a> C-langauge
-interface. Close the channel using the <b>close</b> command of TCL.
-</p>
-}
-
-##############################################################################
-METHOD errorcode {
-
-<p>This method returns the numeric error code that resulted from the most
-recent SQLite operation.</p>
-}
-
-##############################################################################
-METHOD trace {
-
-<p>The "trace" method registers a callback that is invoked as each SQL
-statement is compiled. The text of the SQL is appended as a single string
-to the command before it is invoked. This can be used (for example) to
-keep a log of all SQL operations that an application performs.
-</p>
-}
-
-
-footer $rcsid
+++ /dev/null
-#
-# Run this Tcl script to generate the vdbe.html file.
-#
-set rcsid {$Id: vdbe.tcl,v 1.14 2005/03/12 15:55:11 drh Exp $}
-source common.tcl
-header {The Virtual Database Engine of SQLite}
-puts {
-<h2>The Virtual Database Engine of SQLite</h2>
-
-<blockquote><b>
-This document describes the virtual machine used in SQLite version 2.8.0.
-The virtual machine in SQLite version 3.0 and 3.1 is very similar in
-concept but many of the opcodes have changed and the algorithms are
-somewhat different. Use this document as a rough guide to the idea
-behind the virtual machine in SQLite version 3, not as a reference on
-how the virtual machine works.
-</b></blockquote>
-}
-
-puts {
-<p>If you want to know how the SQLite library works internally,
-you need to begin with a solid understanding of the Virtual Database
-Engine or VDBE. The VDBE occurs right in the middle of the
-processing stream (see the <a href="arch.html">architecture diagram</a>)
-and so it seems to touch most parts of the library. Even
-parts of the code that do not directly interact with the VDBE
-are usually in a supporting role. The VDBE really is the heart of
-SQLite.</p>
-
-<p>This article is a brief introduction to how the VDBE
-works and in particular how the various VDBE instructions
-(documented <a href="opcode.html">here</a>) work together
-to do useful things with the database. The style is tutorial,
-beginning with simple tasks and working toward solving more
-complex problems. Along the way we will visit most
-submodules in the SQLite library. After completeing this tutorial,
-you should have a pretty good understanding of how SQLite works
-and will be ready to begin studying the actual source code.</p>
-
-<h2>Preliminaries</h2>
-
-<p>The VDBE implements a virtual computer that runs a program in
-its virtual machine language. The goal of each program is to
-interrogate or change the database. Toward this end, the machine
-language that the VDBE implements is specifically designed to
-search, read, and modify databases.</p>
-
-<p>Each instruction of the VDBE language contains an opcode and
-three operands labeled P1, P2, and P3. Operand P1 is an arbitrary
-integer. P2 is a non-negative integer. P3 is a pointer to a data
-structure or null-terminated string, possibly null. Only a few VDBE
-instructions use all three operands. Many instructions use only
-one or two operands. A significant number of instructions use
-no operands at all but instead take their data and store their results
-on the execution stack. The details of what each instruction
-does and which operands it uses are described in the separate
-<a href="opcode.html">opcode description</a> document.</p>
-
-<p>A VDBE program begins
-execution on instruction 0 and continues with successive instructions
-until it either (1) encounters a fatal error, (2) executes a
-Halt instruction, or (3) advances the program counter past the
-last instruction of the program. When the VDBE completes execution,
-all open database cursors are closed, all memory is freed, and
-everything is popped from the stack.
-So there are never any worries about memory leaks or
-undeallocated resources.</p>
-
-<p>If you have done any assembly language programming or have
-worked with any kind of abstract machine before, all of these
-details should be familiar to you. So let's jump right in and
-start looking as some code.</p>
-
-<a name="insert1">
-<h2>Inserting Records Into The Database</h2>
-
-<p>We begin with a problem that can be solved using a VDBE program
-that is only a few instructions long. Suppose we have an SQL
-table that was created like this:</p>
-
-<blockquote><pre>
-CREATE TABLE examp(one text, two int);
-</pre></blockquote>
-
-<p>In words, we have a database table named "examp" that has two
-columns of data named "one" and "two". Now suppose we want to insert a single
-record into this table. Like this:</p>
-
-<blockquote><pre>
-INSERT INTO examp VALUES('Hello, World!',99);
-</pre></blockquote>
-
-<p>We can see the VDBE program that SQLite uses to implement this
-INSERT using the <b>sqlite</b> command-line utility. First start
-up <b>sqlite</b> on a new, empty database, then create the table.
-Next change the output format of <b>sqlite</b> to a form that
-is designed to work with VDBE program dumps by entering the
-".explain" command.
-Finally, enter the INSERT statement shown above, but precede the
-INSERT with the special keyword "EXPLAIN". The EXPLAIN keyword
-will cause <b>sqlite</b> to print the VDBE program rather than
-execute it. We have:</p>
-}
-proc Code {body} {
- puts {<blockquote><tt>}
- regsub -all {&} [string trim $body] {\&} body
- regsub -all {>} $body {\>} body
- regsub -all {<} $body {\<} body
- regsub -all {\(\(\(} $body {<b>} body
- regsub -all {\)\)\)} $body {</b>} body
- regsub -all { } $body {\ } body
- regsub -all \n $body <br>\n body
- puts $body
- puts {</tt></blockquote>}
-}
-
-Code {
-$ (((sqlite test_database_1)))
-sqlite> (((CREATE TABLE examp(one text, two int);)))
-sqlite> (((.explain)))
-sqlite> (((EXPLAIN INSERT INTO examp VALUES('Hello, World!',99);)))
-addr opcode p1 p2 p3
----- ------------ ----- ----- -----------------------------------
-0 Transaction 0 0
-1 VerifyCookie 0 81
-2 Transaction 1 0
-3 Integer 0 0
-4 OpenWrite 0 3 examp
-5 NewRecno 0 0
-6 String 0 0 Hello, World!
-7 Integer 99 0 99
-8 MakeRecord 2 0
-9 PutIntKey 0 1
-10 Close 0 0
-11 Commit 0 0
-12 Halt 0 0
-}
-
-puts {<p>As you can see above, our simple insert statement is
-implemented in 12 instructions. The first 3 and last 2 instructions are
-a standard prologue and epilogue, so the real work is done in the middle
-7 instructions. There are no jumps, so the program executes once through
-from top to bottom. Let's now look at each instruction in detail.<p>
-}
-
-Code {
-0 Transaction 0 0
-1 VerifyCookie 0 81
-2 Transaction 1 0
-}
-puts {
-<p>The instruction <a href="opcode.html#Transaction">Transaction</a>
-begins a transaction. The transaction ends when a Commit or Rollback
-opcode is encountered. P1 is the index of the database file on which
-the transaction is started. Index 0 is the main database file. A write
-lock is obtained on the database file when a transaction is started.
-No other process can read or write the file while the transaction is
-underway. Starting a transaction also creates a rollback journal. A
-transaction must be started before any changes can be made to the
-database.</p>
-
-<p>The instruction <a href="opcode.html#VerifyCookie">VerifyCookie</a>
-checks cookie 0 (the database schema version) to make sure it is equal
-to P2 (the value obtained when the database schema was last read).
-P1 is the database number (0 for the main database). This is done to
-make sure the database schema hasn't been changed by another thread, in
-which case it has to be reread.</p>
-
-<p> The second <a href="opcode.html#Transaction">Transaction</a>
-instruction begins a transaction and starts a rollback journal for
-database 1, the database used for temporary tables.</p>
-}
-
-proc stack args {
- puts "<blockquote><table border=2>"
- foreach elem $args {
- puts "<tr><td align=left>$elem</td></tr>"
- }
- puts "</table></blockquote>"
-}
-
-Code {
-3 Integer 0 0
-4 OpenWrite 0 3 examp
-}
-puts {
-<p> The instruction <a href="opcode.html#Integer">Integer</a> pushes
-the integer value P1 (0) onto the stack. Here 0 is the number of the
-database to use in the following OpenWrite instruction. If P3 is not
-NULL then it is a string representation of the same integer. Afterwards
-the stack looks like this:</p>
-}
-stack {(integer) 0}
-
-puts {
-<p> The instruction <a href="opcode.html#OpenWrite">OpenWrite</a> opens
-a new read/write cursor with handle P1 (0 in this case) on table "examp",
-whose root page is P2 (3, in this database file). Cursor handles can be
-any non-negative integer. But the VDBE allocates cursors in an array
-with the size of the array being one more than the largest cursor. So
-to conserve memory, it is best to use handles beginning with zero and
-working upward consecutively. Here P3 ("examp") is the name of the
-table being opened, but this is unused, and only generated to make the
-code easier to read. This instruction pops the database number to use
-(0, the main database) from the top of the stack, so afterwards the
-stack is empty again.</p>
-}
-
-Code {
-5 NewRecno 0 0
-}
-puts {
-<p> The instruction <a href="opcode.html#NewRecno">NewRecno</a> creates
-a new integer record number for the table pointed to by cursor P1. The
-record number is one not currently used as a key in the table. The new
-record number is pushed onto the stack. Afterwards the stack looks like
-this:</p>
-}
-stack {(integer) new record key}
-
-Code {
-6 String 0 0 Hello, World!
-}
-puts {
-<p> The instruction <a href="opcode.html#String">String</a> pushes its
-P3 operand onto the stack. Afterwards the stack looks like this:</p>
-}
-stack {(string) "Hello, World!"} \
- {(integer) new record key}
-
-Code {
-7 Integer 99 0 99
-}
-puts {
-<p> The instruction <a href="opcode.html#Integer">Integer</a> pushes
-its P1 operand (99) onto the stack. Afterwards the stack looks like
-this:</p>
-}
-stack {(integer) 99} \
- {(string) "Hello, World!"} \
- {(integer) new record key}
-
-Code {
-8 MakeRecord 2 0
-}
-puts {
-<p> The instruction <a href="opcode.html#MakeRecord">MakeRecord</a> pops
-the top P1 elements off the stack (2 in this case) and converts them into
-the binary format used for storing records in a database file.
-(See the <a href="fileformat.html">file format</a> description for
-details.) The new record generated by the MakeRecord instruction is
-pushed back onto the stack. Afterwards the stack looks like this:</p>
-</ul>
-}
-stack {(record) "Hello, World!", 99} \
- {(integer) new record key}
-
-Code {
-9 PutIntKey 0 1
-}
-puts {
-<p> The instruction <a href="opcode.html#PutIntKey">PutIntKey</a> uses
-the top 2 stack entries to write an entry into the table pointed to by
-cursor P1. A new entry is created if it doesn't already exist or the
-data for an existing entry is overwritten. The record data is the top
-stack entry, and the key is the next entry down. The stack is popped
-twice by this instruction. Because operand P2 is 1 the row change count
-is incremented and the rowid is stored for subsequent return by the
-sqlite_last_insert_rowid() function. If P2 is 0 the row change count is
-unmodified. This instruction is where the insert actually occurs.</p>
-}
-
-Code {
-10 Close 0 0
-}
-puts {
-<p> The instruction <a href="opcode.html#Close">Close</a> closes a
-cursor previously opened as P1 (0, the only open cursor). If P1 is not
-currently open, this instruction is a no-op.</p>
-}
-
-Code {
-11 Commit 0 0
-}
-puts {
-<p> The instruction <a href="opcode.html#Commit">Commit</a> causes all
-modifications to the database that have been made since the last
-Transaction to actually take effect. No additional modifications are
-allowed until another transaction is started. The Commit instruction
-deletes the journal file and releases the write lock on the database.
-A read lock continues to be held if there are still cursors open.</p>
-}
-
-Code {
-12 Halt 0 0
-}
-puts {
-<p> The instruction <a href="opcode.html#Halt">Halt</a> causes the VDBE
-engine to exit immediately. All open cursors, Lists, Sorts, etc are
-closed automatically. P1 is the result code returned by sqlite_exec().
-For a normal halt, this should be SQLITE_OK (0). For errors, it can be
-some other value. The operand P2 is only used when there is an error.
-There is an implied "Halt 0 0 0" instruction at the end of every
-program, which the VDBE appends when it prepares a program to run.</p>
-
-
-<a name="trace">
-<h2>Tracing VDBE Program Execution</h2>
-
-<p>If the SQLite library is compiled without the NDEBUG preprocessor
-macro, then the PRAGMA <a href="pragma.html#pragma_vdbe_trace">vdbe_trace
-</a> causes the VDBE to trace the execution of programs. Though this
-feature was originally intended for testing and debugging, it can also
-be useful in learning about how the VDBE operates.
-Use "<tt>PRAGMA vdbe_trace=ON;</tt>" to turn tracing on and
-"<tt>PRAGMA vdbe_trace=OFF</tt>" to turn tracing back off.
-Like this:</p>
-}
-
-Code {
-sqlite> (((PRAGMA vdbe_trace=ON;)))
- 0 Halt 0 0
-sqlite> (((INSERT INTO examp VALUES('Hello, World!',99);)))
- 0 Transaction 0 0
- 1 VerifyCookie 0 81
- 2 Transaction 1 0
- 3 Integer 0 0
-Stack: i:0
- 4 OpenWrite 0 3 examp
- 5 NewRecno 0 0
-Stack: i:2
- 6 String 0 0 Hello, World!
-Stack: t[Hello,.World!] i:2
- 7 Integer 99 0 99
-Stack: si:99 t[Hello,.World!] i:2
- 8 MakeRecord 2 0
-Stack: s[...Hello,.World!.99] i:2
- 9 PutIntKey 0 1
- 10 Close 0 0
- 11 Commit 0 0
- 12 Halt 0 0
-}
-
-puts {
-<p>With tracing mode on, the VDBE prints each instruction prior
-to executing it. After the instruction is executed, the top few
-entries in the stack are displayed. The stack display is omitted
-if the stack is empty.</p>
-
-<p>On the stack display, most entries are shown with a prefix
-that tells the datatype of that stack entry. Integers begin
-with "<tt>i:</tt>". Floating point values begin with "<tt>r:</tt>".
-(The "r" stands for "real-number".) Strings begin with either
-"<tt>s:</tt>", "<tt>t:</tt>", "<tt>e:</tt>" or "<tt>z:</tt>".
-The difference among the string prefixes is caused by how their
-memory is allocated. The z: strings are stored in memory obtained
-from <b>malloc()</b>. The t: strings are statically allocated.
-The e: strings are ephemeral. All other strings have the s: prefix.
-This doesn't make any difference to you,
-the observer, but it is vitally important to the VDBE since the
-z: strings need to be passed to <b>free()</b> when they are
-popped to avoid a memory leak. Note that only the first 10
-characters of string values are displayed and that binary
-values (such as the result of the MakeRecord instruction) are
-treated as strings. The only other datatype that can be stored
-on the VDBE stack is a NULL, which is display without prefix
-as simply "<tt>NULL</tt>". If an integer has been placed on the
-stack as both an integer and a string, its prefix is "<tt>si:</tt>".
-
-
-<a name="query1">
-<h2>Simple Queries</h2>
-
-<p>At this point, you should understand the basics of how the VDBE
-writes to a database. Now let's look at how it does queries.
-We will use the following simple SELECT statement as our example:</p>
-
-<blockquote><pre>
-SELECT * FROM examp;
-</pre></blockquote>
-
-<p>The VDBE program generated for this SQL statement is as follows:</p>
-}
-
-Code {
-sqlite> (((EXPLAIN SELECT * FROM examp;)))
-addr opcode p1 p2 p3
----- ------------ ----- ----- -----------------------------------
-0 ColumnName 0 0 one
-1 ColumnName 1 0 two
-2 Integer 0 0
-3 OpenRead 0 3 examp
-4 VerifyCookie 0 81
-5 Rewind 0 10
-6 Column 0 0
-7 Column 0 1
-8 Callback 2 0
-9 Next 0 6
-10 Close 0 0
-11 Halt 0 0
-}
-
-puts {
-<p>Before we begin looking at this problem, let's briefly review
-how queries work in SQLite so that we will know what we are trying
-to accomplish. For each row in the result of a query,
-SQLite will invoke a callback function with the following
-prototype:</p>
-
-<blockquote><pre>
-int Callback(void *pUserData, int nColumn, char *azData[], char *azColumnName[]);
-</pre></blockquote>
-
-<p>The SQLite library supplies the VDBE with a pointer to the callback function
-and the <b>pUserData</b> pointer. (Both the callback and the user data were
-originally passed in as arguments to the <b>sqlite_exec()</b> API function.)
-The job of the VDBE is to
-come up with values for <b>nColumn</b>, <b>azData[]</b>,
-and <b>azColumnName[]</b>.
-<b>nColumn</b> is the number of columns in the results, of course.
-<b>azColumnName[]</b> is an array of strings where each string is the name
-of one of the result columns. <b>azData[]</b> is an array of strings holding
-the actual data.</p>
-}
-
-Code {
-0 ColumnName 0 0 one
-1 ColumnName 1 0 two
-}
-puts {
-<p>The first two instructions in the VDBE program for our query are
-concerned with setting up values for <b>azColumn</b>.
-The <a href="opcode.html#ColumnName">ColumnName</a> instructions tell
-the VDBE what values to fill in for each element of the <b>azColumnName[]</b>
-array. Every query will begin with one ColumnName instruction for each
-column in the result, and there will be a matching Column instruction for
-each one later in the query.
-</p>
-}
-
-Code {
-2 Integer 0 0
-3 OpenRead 0 3 examp
-4 VerifyCookie 0 81
-}
-puts {
-<p>Instructions 2 and 3 open a read cursor on the database table that is
-to be queried. This works the same as the OpenWrite instruction in the
-INSERT example except that the cursor is opened for reading this time
-instead of for writing. Instruction 4 verifies the database schema as
-in the INSERT example.</p>
-}
-
-Code {
-5 Rewind 0 10
-}
-puts {
-<p> The <a href="opcode.html#Rewind">Rewind</a> instruction initializes
-a loop that iterates over the "examp" table. It rewinds the cursor P1
-to the first entry in its table. This is required by the the Column and
-Next instructions, which use the cursor to iterate through the table.
-If the table is empty, then jump to P2 (10), which is the instruction just
-past the loop. If the table is not empty, fall through to the following
-instruction at 6, which is the beginning of the loop body.</p>
-}
-
-Code {
-6 Column 0 0
-7 Column 0 1
-8 Callback 2 0
-}
-puts {
-<p> The instructions 6 through 8 form the body of the loop that will
-execute once for each record in the database file.
-
-The <a href="opcode.html#Column">Column</a> instructions at addresses 6
-and 7 each take the P2-th column from the P1-th cursor and push it onto
-the stack. In this example, the first Column instruction is pushing the
-value for the column "one" onto the stack and the second Column
-instruction is pushing the value for column "two".
-
-The <a href="opcode.html#Callback">Callback</a> instruction at address 8
-invokes the callback() function. The P1 operand to Callback becomes the
-value for <b>nColumn</b>. The Callback instruction pops P1 values from
-the stack and uses them to fill the <b>azData[]</b> array.</p>
-}
-
-Code {
-9 Next 0 6
-}
-puts {
-<p>The instruction at address 9 implements the branching part of the
-loop. Together with the Rewind at address 5 it forms the loop logic.
-This is a key concept that you should pay close attention to.
-The <a href="opcode.html#Next">Next</a> instruction advances the cursor
-P1 to the next record. If the cursor advance was successful, then jump
-immediately to P2 (6, the beginning of the loop body). If the cursor
-was at the end, then fall through to the following instruction, which
-ends the loop.</p>
-}
-
-Code {
-10 Close 0 0
-11 Halt 0 0
-}
-puts {
-<p>The Close instruction at the end of the program closes the
-cursor that points into the table "examp". It is not really necessary
-to call Close here since all cursors will be automatically closed
-by the VDBE when the program halts. But we needed an instruction
-for the Rewind to jump to so we might as well go ahead and have that
-instruction do something useful.
-The Halt instruction ends the VDBE program.</p>
-
-<p>Note that the program for this SELECT query didn't contain the
-Transaction and Commit instructions used in the INSERT example. Because
-the SELECT is a read operation that doesn't alter the database, it
-doesn't require a transaction.</p>
-}
-
-
-puts {
-<a name="query2">
-<h2>A Slightly More Complex Query</h2>
-
-<p>The key points of the previous example were the use of the Callback
-instruction to invoke the callback function, and the use of the Next
-instruction to implement a loop over all records of the database file.
-This example attempts to drive home those ideas by demonstrating a
-slightly more complex query that involves more columns of
-output, some of which are computed values, and a WHERE clause that
-limits which records actually make it to the callback function.
-Consider this query:</p>
-
-<blockquote><pre>
-SELECT one, two, one || two AS 'both'
-FROM examp
-WHERE one LIKE 'H%'
-</pre></blockquote>
-
-<p>This query is perhaps a bit contrived, but it does serve to
-illustrate our points. The result will have three column with
-names "one", "two", and "both". The first two columns are direct
-copies of the two columns in the table and the third result
-column is a string formed by concatenating the first and
-second columns of the table.
-Finally, the
-WHERE clause says that we will only chose rows for the
-results where the "one" column begins with an "H".
-Here is what the VDBE program looks like for this query:</p>
-}
-
-Code {
-addr opcode p1 p2 p3
----- ------------ ----- ----- -----------------------------------
-0 ColumnName 0 0 one
-1 ColumnName 1 0 two
-2 ColumnName 2 0 both
-3 Integer 0 0
-4 OpenRead 0 3 examp
-5 VerifyCookie 0 81
-6 Rewind 0 18
-7 String 0 0 H%
-8 Column 0 0
-9 Function 2 0 ptr(0x7f1ac0)
-10 IfNot 1 17
-11 Column 0 0
-12 Column 0 1
-13 Column 0 0
-14 Column 0 1
-15 Concat 2 0
-16 Callback 3 0
-17 Next 0 7
-18 Close 0 0
-19 Halt 0 0
-}
-
-puts {
-<p>Except for the WHERE clause, the structure of the program for
-this example is very much like the prior example, just with an
-extra column. There are now 3 columns, instead of 2 as before,
-and there are three ColumnName instructions.
-A cursor is opened using the OpenRead instruction, just like in the
-prior example. The Rewind instruction at address 6 and the
-Next at address 17 form a loop over all records of the table.
-The Close instruction at the end is there to give the
-Rewind instruction something to jump to when it is done. All of
-this is just like in the first query demonstration.</p>
-
-<p>The Callback instruction in this example has to generate
-data for three result columns instead of two, but is otherwise
-the same as in the first query. When the Callback instruction
-is invoked, the left-most column of the result should be
-the lowest in the stack and the right-most result column should
-be the top of the stack. We can see the stack being set up
-this way at addresses 11 through 15. The Column instructions at
-11 and 12 push the values for the first two columns in the result.
-The two Column instructions at 13 and 14 pull in the values needed
-to compute the third result column and the Concat instruction at
-15 joins them together into a single entry on the stack.</p>
-
-<p>The only thing that is really new about the current example
-is the WHERE clause which is implemented by instructions at
-addresses 7 through 10. Instructions at address 7 and 8 push
-onto the stack the value of the "one" column from the table
-and the literal string "H%".
-The <a href="opcode.html#Function">Function</a> instruction at address 9
-pops these two values from the stack and pushes the result of the LIKE()
-function back onto the stack.
-The <a href="opcode.html#IfNot">IfNot</a> instruction pops the top stack
-value and causes an immediate jump forward to the Next instruction if the
-top value was false (<em>not</em> not like the literal string "H%").
-Taking this jump effectively skips the callback, which is the whole point
-of the WHERE clause. If the result
-of the comparison is true, the jump is not taken and control
-falls through to the Callback instruction below.</p>
-
-<p>Notice how the LIKE operator is implemented. It is a user-defined
-function in SQLite, so the address of its function definition is
-specified in P3. The operand P1 is the number of function arguments for
-it to take from the stack. In this case the LIKE() function takes 2
-arguments. The arguments are taken off the stack in reverse order
-(right-to-left), so the pattern to match is the top stack element, and
-the next element is the data to compare. The return value is pushed
-onto the stack.</p>
-
-
-<a name="pattern1">
-<h2>A Template For SELECT Programs</h2>
-
-<p>The first two query examples illustrate a kind of template that
-every SELECT program will follow. Basically, we have:</p>
-
-<p>
-<ol>
-<li>Initialize the <b>azColumnName[]</b> array for the callback.</li>
-<li>Open a cursor into the table to be queried.</li>
-<li>For each record in the table, do:
- <ol type="a">
- <li>If the WHERE clause evaluates to FALSE, then skip the steps that
- follow and continue to the next record.</li>
- <li>Compute all columns for the current row of the result.</li>
- <li>Invoke the callback function for the current row of the result.</li>
- </ol>
-<li>Close the cursor.</li>
-</ol>
-</p>
-
-<p>This template will be expanded considerably as we consider
-additional complications such as joins, compound selects, using
-indices to speed the search, sorting, and aggregate functions
-with and without GROUP BY and HAVING clauses.
-But the same basic ideas will continue to apply.</p>
-
-<h2>UPDATE And DELETE Statements</h2>
-
-<p>The UPDATE and DELETE statements are coded using a template
-that is very similar to the SELECT statement template. The main
-difference, of course, is that the end action is to modify the
-database rather than invoke a callback function. Because it modifies
-the database it will also use transactions. Let's begin
-by looking at a DELETE statement:</p>
-
-<blockquote><pre>
-DELETE FROM examp WHERE two<50;
-</pre></blockquote>
-
-<p>This DELETE statement will remove every record from the "examp"
-table where the "two" column is less than 50.
-The code generated to do this is as follows:</p>
-}
-
-Code {
-addr opcode p1 p2 p3
----- ------------ ----- ----- -----------------------------------
-0 Transaction 1 0
-1 Transaction 0 0
-2 VerifyCookie 0 178
-3 Integer 0 0
-4 OpenRead 0 3 examp
-5 Rewind 0 12
-6 Column 0 1
-7 Integer 50 0 50
-8 Ge 1 11
-9 Recno 0 0
-10 ListWrite 0 0
-11 Next 0 6
-12 Close 0 0
-13 ListRewind 0 0
-14 Integer 0 0
-15 OpenWrite 0 3
-16 ListRead 0 20
-17 NotExists 0 19
-18 Delete 0 1
-19 Goto 0 16
-20 ListReset 0 0
-21 Close 0 0
-22 Commit 0 0
-23 Halt 0 0
-}
-
-puts {
-<p>Here is what the program must do. First it has to locate all of
-the records in the table "examp" that are to be deleted. This is
-done using a loop very much like the loop used in the SELECT examples
-above. Once all records have been located, then we can go back through
-and delete them one by one. Note that we cannot delete each record
-as soon as we find it. We have to locate all records first, then
-go back and delete them. This is because the SQLite database
-backend might change the scan order after a delete operation.
-And if the scan
-order changes in the middle of the scan, some records might be
-visited more than once and other records might not be visited at all.</p>
-
-<p>So the implemention of DELETE is really in two loops. The first loop
-(instructions 5 through 11) locates the records that are to be deleted
-and saves their keys onto a temporary list, and the second loop
-(instructions 16 through 19) uses the key list to delete the records one
-by one. </p>
-}
-
-
-Code {
-0 Transaction 1 0
-1 Transaction 0 0
-2 VerifyCookie 0 178
-3 Integer 0 0
-4 OpenRead 0 3 examp
-}
-puts {
-<p>Instructions 0 though 4 are as in the INSERT example. They start
-transactions for the main and temporary databases, verify the database
-schema for the main database, and open a read cursor on the table
-"examp". Notice that the cursor is opened for reading, not writing. At
-this stage of the program we are only going to be scanning the table,
-not changing it. We will reopen the same table for writing later, at
-instruction 15.</p>
-}
-
-Code {
-5 Rewind 0 12
-}
-puts {
-<p>As in the SELECT example, the <a href="opcode.html#Rewind">Rewind</a>
-instruction rewinds the cursor to the beginning of the table, readying
-it for use in the loop body.</p>
-}
-
-Code {
-6 Column 0 1
-7 Integer 50 0 50
-8 Ge 1 11
-}
-puts {
-<p>The WHERE clause is implemented by instructions 6 through 8.
-The job of the where clause is to skip the ListWrite if the WHERE
-condition is false. To this end, it jumps ahead to the Next instruction
-if the "two" column (extracted by the Column instruction) is
-greater than or equal to 50.</p>
-
-<p>As before, the Column instruction uses cursor P1 and pushes the data
-record in column P2 (1, column "two") onto the stack. The Integer
-instruction pushes the value 50 onto the top of the stack. After these
-two instructions the stack looks like:</p>
-}
-stack {(integer) 50} \
- {(record) current record for column "two" }
-
-puts {
-<p>The <a href="opcode.html#Ge">Ge</a> operator compares the top two
-elements on the stack, pops them, and then branches based on the result
-of the comparison. If the second element is >= the top element, then
-jump to address P2 (the Next instruction at the end of the loop).
-Because P1 is true, if either operand is NULL (and thus the result is
-NULL) then take the jump. If we don't jump, just advance to the next
-instruction.</p>
-}
-
-Code {
-9 Recno 0 0
-10 ListWrite 0 0
-}
-puts {
-<p>The <a href="opcode.html#Recno">Recno</a> instruction pushes onto the
-stack an integer which is the first 4 bytes of the the key to the current
-entry in a sequential scan of the table pointed to by cursor P1.
-The <a href="opcode.html#ListWrite">ListWrite</a> instruction writes the
-integer on the top of the stack into a temporary storage list and pops
-the top element. This is the important work of this loop, to store the
-keys of the records to be deleted so we can delete them in the second
-loop. After this ListWrite instruction the stack is empty again.</p>
-}
-
-Code {
-11 Next 0 6
-12 Close 0 0
-}
-puts {
-<p> The Next instruction increments the cursor to point to the next
-element in the table pointed to by cursor P0, and if it was successful
-branches to P2 (6, the beginning of the loop body). The Close
-instruction closes cursor P1. It doesn't affect the temporary storage
-list because it isn't associated with cursor P1; it is instead a global
-working list (which can be saved with ListPush).</p>
-}
-
-Code {
-13 ListRewind 0 0
-}
-puts {
-<p> The <a href="opcode.html#ListRewind">ListRewind</a> instruction
-rewinds the temporary storage list to the beginning. This prepares it
-for use in the second loop.</p>
-}
-
-Code {
-14 Integer 0 0
-15 OpenWrite 0 3
-}
-puts {
-<p> As in the INSERT example, we push the database number P1 (0, the main
-database) onto the stack and use OpenWrite to open the cursor P1 on table
-P2 (base page 3, "examp") for modification.</p>
-}
-
-Code {
-16 ListRead 0 20
-17 NotExists 0 19
-18 Delete 0 1
-19 Goto 0 16
-}
-puts {
-<p>This loop does the actual deleting. It is organized differently from
-the one in the UPDATE example. The ListRead instruction plays the role
-that the Next did in the INSERT loop, but because it jumps to P2 on
-failure, and Next jumps on success, we put it at the start of the loop
-instead of the end. This means that we have to put a Goto at the end of
-the loop to jump back to the the loop test at the beginning. So this
-loop has the form of a C while(){...} loop, while the loop in the INSERT
-example had the form of a do{...}while() loop. The Delete instruction
-fills the role that the callback function did in the preceding examples.
-</p>
-<p>The <a href="opcode.html#ListRead">ListRead</a> instruction reads an
-element from the temporary storage list and pushes it onto the stack.
-If this was successful, it continues to the next instruction. If this
-fails because the list is empty, it branches to P2, which is the
-instruction just after the loop. Afterwards the stack looks like:</p>
-}
-stack {(integer) key for current record}
-
-puts {
-<p>Notice the similarity between the ListRead and Next instructions.
-Both operations work according to this rule:
-</p>
-<blockquote>
-Push the next "thing" onto the stack and fall through OR jump to P2,
-depending on whether or not there is a next "thing" to push.
-</blockquote>
-<p>One difference between Next and ListRead is their idea of a "thing".
-The "things" for the Next instruction are records in a database file.
-"Things" for ListRead are integer keys in a list. Another difference
-is whether to jump or fall through if there is no next "thing". In this
-case, Next falls through, and ListRead jumps. Later on, we will see
-other looping instructions (NextIdx and SortNext) that operate using the
-same principle.</p>
-
-<p>The <a href="opcode.html#NotExists">NotExists</a> instruction pops
-the top stack element and uses it as an integer key. If a record with
-that key does not exist in table P1, then jump to P2. If a record does
-exist, then fall thru to the next instruction. In this case P2 takes
-us to the Goto at the end of the loop, which jumps back to the ListRead
-at the beginning. This could have been coded to have P2 be 16, the
-ListRead at the start of the loop, but the SQLite parser which generated
-this code didn't make that optimization.</p>
-<p>The <a href="opcode.html#Delete">Delete</a> does the work of this
-loop; it pops an integer key off the stack (placed there by the
-preceding ListRead) and deletes the record of cursor P1 that has that key.
-Because P2 is true, the row change counter is incremented.</p>
-<p>The <a href="opcode.html#Goto">Goto</a> jumps back to the beginning
-of the loop. This is the end of the loop.</p>
-}
-
-Code {
-20 ListReset 0 0
-21 Close 0 0
-22 Commit 0 0
-23 Halt 0 0
-}
-puts {
-<p>This block of instruction cleans up the VDBE program. Three of these
-instructions aren't really required, but are generated by the SQLite
-parser from its code templates, which are designed to handle more
-complicated cases.</p>
-<p>The <a href="opcode.html#ListReset">ListReset</a> instruction empties
-the temporary storage list. This list is emptied automatically when the
-VDBE program terminates, so it isn't necessary in this case. The Close
-instruction closes the cursor P1. Again, this is done by the VDBE
-engine when it is finished running this program. The Commit ends the
-current transaction successfully, and causes all changes that occurred
-in this transaction to be saved to the database. The final Halt is also
-unneccessary, since it is added to every VDBE program when it is
-prepared to run.</p>
-
-
-<p>UPDATE statements work very much like DELETE statements except
-that instead of deleting the record they replace it with a new one.
-Consider this example:
-</p>
-
-<blockquote><pre>
-UPDATE examp SET one= '(' || one || ')' WHERE two < 50;
-</pre></blockquote>
-
-<p>Instead of deleting records where the "two" column is less than
-50, this statement just puts the "one" column in parentheses
-The VDBE program to implement this statement follows:</p>
-}
-
-Code {
-addr opcode p1 p2 p3
----- ------------ ----- ----- -----------------------------------
-0 Transaction 1 0
-1 Transaction 0 0
-2 VerifyCookie 0 178
-3 Integer 0 0
-4 OpenRead 0 3 examp
-5 Rewind 0 12
-6 Column 0 1
-7 Integer 50 0 50
-8 Ge 1 11
-9 Recno 0 0
-10 ListWrite 0 0
-11 Next 0 6
-12 Close 0 0
-13 Integer 0 0
-14 OpenWrite 0 3
-15 ListRewind 0 0
-16 ListRead 0 28
-17 Dup 0 0
-18 NotExists 0 16
-19 String 0 0 (
-20 Column 0 0
-21 Concat 2 0
-22 String 0 0 )
-23 Concat 2 0
-24 Column 0 1
-25 MakeRecord 2 0
-26 PutIntKey 0 1
-27 Goto 0 16
-28 ListReset 0 0
-29 Close 0 0
-30 Commit 0 0
-31 Halt 0 0
-}
-
-puts {
-<p>This program is essentially the same as the DELETE program except
-that the body of the second loop has been replace by a sequence of
-instructions (at addresses 17 through 26) that update the record rather
-than delete it. Most of this instruction sequence should already be
-familiar to you, but there are a couple of minor twists so we will go
-over it briefly. Also note that the order of some of the instructions
-before and after the 2nd loop has changed. This is just the way the
-SQLite parser chose to output the code using a different template.</p>
-
-<p>As we enter the interior of the second loop (at instruction 17)
-the stack contains a single integer which is the key of the
-record we want to modify. We are going to need to use this
-key twice: once to fetch the old value of the record and
-a second time to write back the revised record. So the first instruction
-is a Dup to make a duplicate of the key on the top of the stack. The
-Dup instruction will duplicate any element of the stack, not just the top
-element. You specify which element to duplication using the
-P1 operand. When P1 is 0, the top of the stack is duplicated.
-When P1 is 1, the next element down on the stack duplication.
-And so forth.</p>
-
-<p>After duplicating the key, the next instruction, NotExists,
-pops the stack once and uses the value popped as a key to
-check the existence of a record in the database file. If there is no record
-for this key, it jumps back to the ListRead to get another key.</p>
-
-<p>Instructions 19 through 25 construct a new database record
-that will be used to replace the existing record. This is
-the same kind of code that we saw
-in the description of INSERT and will not be described further.
-After instruction 25 executes, the stack looks like this:</p>
-}
-
-stack {(record) new data record} {(integer) key}
-
-puts {
-<p>The PutIntKey instruction (also described
-during the discussion about INSERT) writes an entry into the
-database file whose data is the top of the stack and whose key
-is the next on the stack, and then pops the stack twice. The
-PutIntKey instruction will overwrite the data of an existing record
-with the same key, which is what we want here. Overwriting was not
-an issue with INSERT because with INSERT the key was generated
-by the NewRecno instruction which is guaranteed to provide a key
-that has not been used before.</p>
-}
-
-if 0 {<p>(By the way, since keys must
-all be unique and each key is a 32-bit integer, a single
-SQLite database table can have no more than 2<sup>32</sup>
-rows. Actually, the Key instruction starts to become
-very inefficient as you approach this upper bound, so it
-is best to keep the number of entries below 2<sup>31</sup>
-or so. Surely a couple billion records will be enough for
-most applications!)</p>
-}
-
-puts {
-<h2>CREATE and DROP</h2>
-
-<p>Using CREATE or DROP to create or destroy a table or index is
-really the same as doing an INSERT or DELETE from the special
-"sqlite_master" table, at least from the point of view of the VDBE.
-The sqlite_master table is a special table that is automatically
-created for every SQLite database. It looks like this:</p>
-
-<blockquote><pre>
-CREATE TABLE sqlite_master (
- type TEXT, -- either "table" or "index"
- name TEXT, -- name of this table or index
- tbl_name TEXT, -- for indices: name of associated table
- sql TEXT -- SQL text of the original CREATE statement
-)
-</pre></blockquote>
-
-<p>Every table (except the "sqlite_master" table itself)
-and every named index in an SQLite database has an entry
-in the sqlite_master table. You can query this table using
-a SELECT statement just like any other table. But you are
-not allowed to directly change the table using UPDATE, INSERT,
-or DELETE. Changes to sqlite_master have to occur using
-the CREATE and DROP commands because SQLite also has to update
-some of its internal data structures when tables and indices
-are added or destroyed.</p>
-
-<p>But from the point of view of the VDBE, a CREATE works
-pretty much like an INSERT and a DROP works like a DELETE.
-When the SQLite library opens to an existing database,
-the first thing it does is a SELECT to read the "sql"
-columns from all entries of the sqlite_master table.
-The "sql" column contains the complete SQL text of the
-CREATE statement that originally generated the index or
-table. This text is fed back into the SQLite parser
-and used to reconstruct the
-internal data structures describing the index or table.</p>
-
-<h2>Using Indexes To Speed Searching</h2>
-
-<p>In the example queries above, every row of the table being
-queried must be loaded off of the disk and examined, even if only
-a small percentage of the rows end up in the result. This can
-take a long time on a big table. To speed things up, SQLite
-can use an index.</p>
-
-<p>An SQLite file associates a key with some data. For an SQLite
-table, the database file is set up so that the key is an integer
-and the data is the information for one row of the table.
-Indices in SQLite reverse this arrangement. The index key
-is (some of) the information being stored and the index data
-is an integer.
-To access a table row that has some particular
-content, we first look up the content in the index table to find
-its integer index, then we use that integer to look up the
-complete record in the table.</p>
-
-<p>Note that SQLite uses b-trees, which are a sorted data structure,
-so indices can be used when the WHERE clause of the SELECT statement
-contains tests for equality or inequality. Queries like the following
-can use an index if it is available:</p>
-
-<blockquote><pre>
-SELECT * FROM examp WHERE two==50;
-SELECT * FROM examp WHERE two<50;
-SELECT * FROM examp WHERE two IN (50, 100);
-</pre></blockquote>
-
-<p>If there exists an index that maps the "two" column of the "examp"
-table into integers, then SQLite will use that index to find the integer
-keys of all rows in examp that have a value of 50 for column two, or
-all rows that are less than 50, etc.
-But the following queries cannot use the index:</p>
-
-<blockquote><pre>
-SELECT * FROM examp WHERE two%50 == 10;
-SELECT * FROM examp WHERE two&127 == 3;
-</pre></blockquote>
-
-<p>Note that the SQLite parser will not always generate code to use an
-index, even if it is possible to do so. The following queries will not
-currently use the index:</p>
-
-<blockquote><pre>
-SELECT * FROM examp WHERE two+10 == 50;
-SELECT * FROM examp WHERE two==50 OR two==100;
-</pre></blockquote>
-
-<p>To understand better how indices work, lets first look at how
-they are created. Let's go ahead and put an index on the two
-column of the examp table. We have:</p>
-
-<blockquote><pre>
-CREATE INDEX examp_idx1 ON examp(two);
-</pre></blockquote>
-
-<p>The VDBE code generated by the above statement looks like the
-following:</p>
-}
-
-Code {
-addr opcode p1 p2 p3
----- ------------ ----- ----- -----------------------------------
-0 Transaction 1 0
-1 Transaction 0 0
-2 VerifyCookie 0 178
-3 Integer 0 0
-4 OpenWrite 0 2
-5 NewRecno 0 0
-6 String 0 0 index
-7 String 0 0 examp_idx1
-8 String 0 0 examp
-9 CreateIndex 0 0 ptr(0x791380)
-10 Dup 0 0
-11 Integer 0 0
-12 OpenWrite 1 0
-13 String 0 0 CREATE INDEX examp_idx1 ON examp(tw
-14 MakeRecord 5 0
-15 PutIntKey 0 0
-16 Integer 0 0
-17 OpenRead 2 3 examp
-18 Rewind 2 24
-19 Recno 2 0
-20 Column 2 1
-21 MakeIdxKey 1 0 n
-22 IdxPut 1 0 indexed columns are not unique
-23 Next 2 19
-24 Close 2 0
-25 Close 1 0
-26 Integer 333 0
-27 SetCookie 0 0
-28 Close 0 0
-29 Commit 0 0
-30 Halt 0 0
-}
-
-puts {
-<p>Remember that every table (except sqlite_master) and every named
-index has an entry in the sqlite_master table. Since we are creating
-a new index, we have to add a new entry to sqlite_master. This is
-handled by instructions 3 through 15. Adding an entry to sqlite_master
-works just like any other INSERT statement so we will not say anymore
-about it here. In this example, we want to focus on populating the
-new index with valid data, which happens on instructions 16 through
-23.</p>
-}
-
-Code {
-16 Integer 0 0
-17 OpenRead 2 3 examp
-}
-puts {
-<p>The first thing that happens is that we open the table being
-indexed for reading. In order to construct an index for a table,
-we have to know what is in that table. The index has already been
-opened for writing using cursor 0 by instructions 3 and 4.</p>
-}
-
-Code {
-18 Rewind 2 24
-19 Recno 2 0
-20 Column 2 1
-21 MakeIdxKey 1 0 n
-22 IdxPut 1 0 indexed columns are not unique
-23 Next 2 19
-}
-puts {
-<p>Instructions 18 through 23 implement a loop over every row of the
-table being indexed. For each table row, we first extract the integer
-key for that row using Recno in instruction 19, then get the value of
-the "two" column using Column in instruction 20.
-The <a href="opcode.html#MakeIdxKey">MakeIdxKey</a> instruction at 21
-converts data from the "two" column (which is on the top of the stack)
-into a valid index key. For an index on a single column, this is
-basically a no-op. But if the P1 operand to MakeIdxKey had been
-greater than one multiple entries would have been popped from the stack
-and converted into a single index key.
-The <a href="opcode.html#IdxPut">IdxPut</a> instruction at 22 is what
-actually creates the index entry. IdxPut pops two elements from the
-stack. The top of the stack is used as a key to fetch an entry from the
-index table. Then the integer which was second on stack is added to the
-set of integers for that index and the new record is written back to the
-database file. Note
-that the same index entry can store multiple integers if there
-are two or more table entries with the same value for the two
-column.
-</p>
-
-<p>Now let's look at how this index will be used. Consider the
-following query:</p>
-
-<blockquote><pre>
-SELECT * FROM examp WHERE two==50;
-</pre></blockquote>
-
-<p>SQLite generates the following VDBE code to handle this query:</p>
-}
-
-Code {
-addr opcode p1 p2 p3
----- ------------ ----- ----- -----------------------------------
-0 ColumnName 0 0 one
-1 ColumnName 1 0 two
-2 Integer 0 0
-3 OpenRead 0 3 examp
-4 VerifyCookie 0 256
-5 Integer 0 0
-6 OpenRead 1 4 examp_idx1
-7 Integer 50 0 50
-8 MakeKey 1 0 n
-9 MemStore 0 0
-10 MoveTo 1 19
-11 MemLoad 0 0
-12 IdxGT 1 19
-13 IdxRecno 1 0
-14 MoveTo 0 0
-15 Column 0 0
-16 Column 0 1
-17 Callback 2 0
-18 Next 1 11
-19 Close 0 0
-20 Close 1 0
-21 Halt 0 0
-}
-
-puts {
-<p>The SELECT begins in a familiar fashion. First the column
-names are initialized and the table being queried is opened.
-Things become different beginning with instructions 5 and 6 where
-the index file is also opened. Instructions 7 and 8 make
-a key with the value of 50.
-The <a href="opcode.html#MemStore">MemStore</a> instruction at 9 stores
-the index key in VDBE memory location 0. The VDBE memory is used to
-avoid having to fetch a value from deep in the stack, which can be done,
-but makes the program harder to generate. The following instruction
-<a href="opcode.html#MoveTo">MoveTo</a> at address 10 pops the key off
-the stack and moves the index cursor to the first row of the index with
-that key. This initializes the cursor for use in the following loop.</p>
-
-<p>Instructions 11 through 18 implement a loop over all index records
-with the key that was fetched by instruction 8. All of the index
-records with this key will be contiguous in the index table, so we walk
-through them and fetch the corresponding table key from the index.
-This table key is then used to move the cursor to that row in the table.
-The rest of the loop is the same as the loop for the non-indexed SELECT
-query.</p>
-
-<p>The loop begins with the <a href="opcode.html#MemLoad">MemLoad</a>
-instruction at 11 which pushes a copy of the index key back onto the
-stack. The instruction <a href="opcode.html#IdxGT">IdxGT</a> at 12
-compares the key to the key in the current index record pointed to by
-cursor P1. If the index key at the current cursor location is greater
-than the the index we are looking for, then jump out of the loop.</p>
-
-<p>The instruction <a href="opcode.html#IdxRecno">IdxRecno</a> at 13
-pushes onto the stack the table record number from the index. The
-following MoveTo pops it and moves the table cursor to that row. The
-next 3 instructions select the column data the same way as in the non-
-indexed case. The Column instructions fetch the column data and the
-callback function is invoked. The final Next instruction advances the
-index cursor, not the table cursor, to the next row, and then branches
-back to the start of the loop if there are any index records left.</p>
-
-<p>Since the index is used to look up values in the table,
-it is important that the index and table be kept consistent.
-Now that there is an index on the examp table, we will have
-to update that index whenever data is inserted, deleted, or
-changed in the examp table. Remember the first example above
-where we were able to insert a new row into the "examp" table using
-12 VDBE instructions. Now that this table is indexed, 19
-instructions are required. The SQL statement is this:</p>
-
-<blockquote><pre>
-INSERT INTO examp VALUES('Hello, World!',99);
-</pre></blockquote>
-
-<p>And the generated code looks like this:</p>
-}
-
-Code {
-addr opcode p1 p2 p3
----- ------------ ----- ----- -----------------------------------
-0 Transaction 1 0
-1 Transaction 0 0
-2 VerifyCookie 0 256
-3 Integer 0 0
-4 OpenWrite 0 3 examp
-5 Integer 0 0
-6 OpenWrite 1 4 examp_idx1
-7 NewRecno 0 0
-8 String 0 0 Hello, World!
-9 Integer 99 0 99
-10 Dup 2 1
-11 Dup 1 1
-12 MakeIdxKey 1 0 n
-13 IdxPut 1 0
-14 MakeRecord 2 0
-15 PutIntKey 0 1
-16 Close 0 0
-17 Close 1 0
-18 Commit 0 0
-19 Halt 0 0
-}
-
-puts {
-<p>At this point, you should understand the VDBE well enough to
-figure out on your own how the above program works. So we will
-not discuss it further in this text.</p>
-
-<h2>Joins</h2>
-
-<p>In a join, two or more tables are combined to generate a single
-result. The result table consists of every possible combination
-of rows from the tables being joined. The easiest and most natural
-way to implement this is with nested loops.</p>
-
-<p>Recall the query template discussed above where there was a
-single loop that searched through every record of the table.
-In a join we have basically the same thing except that there
-are nested loops. For example, to join two tables, the query
-template might look something like this:</p>
-
-<p>
-<ol>
-<li>Initialize the <b>azColumnName[]</b> array for the callback.</li>
-<li>Open two cursors, one to each of the two tables being queried.</li>
-<li>For each record in the first table, do:
- <ol type="a">
- <li>For each record in the second table do:
- <ol type="i">
- <li>If the WHERE clause evaluates to FALSE, then skip the steps that
- follow and continue to the next record.</li>
- <li>Compute all columns for the current row of the result.</li>
- <li>Invoke the callback function for the current row of the result.</li>
- </ol></li>
- </ol>
-<li>Close both cursors.</li>
-</ol>
-</p>
-
-<p>This template will work, but it is likely to be slow since we
-are now dealing with an O(N<sup>2</sup>) loop. But it often works
-out that the WHERE clause can be factored into terms and that one or
-more of those terms will involve only columns in the first table.
-When this happens, we can factor part of the WHERE clause test out of
-the inner loop and gain a lot of efficiency. So a better template
-would be something like this:</p>
-
-<p>
-<ol>
-<li>Initialize the <b>azColumnName[]</b> array for the callback.</li>
-<li>Open two cursors, one to each of the two tables being queried.</li>
-<li>For each record in the first table, do:
- <ol type="a">
- <li>Evaluate terms of the WHERE clause that only involve columns from
- the first table. If any term is false (meaning that the whole
- WHERE clause must be false) then skip the rest of this loop and
- continue to the next record.</li>
- <li>For each record in the second table do:
- <ol type="i">
- <li>If the WHERE clause evaluates to FALSE, then skip the steps that
- follow and continue to the next record.</li>
- <li>Compute all columns for the current row of the result.</li>
- <li>Invoke the callback function for the current row of the result.</li>
- </ol></li>
- </ol>
-<li>Close both cursors.</li>
-</ol>
-</p>
-
-<p>Additional speed-up can occur if an index can be used to speed
-the search of either or the two loops.</p>
-
-<p>SQLite always constructs the loops in the same order as the
-tables appear in the FROM clause of the SELECT statement. The
-left-most table becomes the outer loop and the right-most table
-becomes the inner loop. It is possible, in theory, to reorder
-the loops in some circumstances to speed the evaluation of the
-join. But SQLite does not attempt this optimization.</p>
-
-<p>You can see how SQLite constructs nested loops in the following
-example:</p>
-
-<blockquote><pre>
-CREATE TABLE examp2(three int, four int);
-SELECT * FROM examp, examp2 WHERE two<50 AND four==two;
-</pre></blockquote>
-}
-
-Code {
-addr opcode p1 p2 p3
----- ------------ ----- ----- -----------------------------------
-0 ColumnName 0 0 examp.one
-1 ColumnName 1 0 examp.two
-2 ColumnName 2 0 examp2.three
-3 ColumnName 3 0 examp2.four
-4 Integer 0 0
-5 OpenRead 0 3 examp
-6 VerifyCookie 0 909
-7 Integer 0 0
-8 OpenRead 1 5 examp2
-9 Rewind 0 24
-10 Column 0 1
-11 Integer 50 0 50
-12 Ge 1 23
-13 Rewind 1 23
-14 Column 1 1
-15 Column 0 1
-16 Ne 1 22
-17 Column 0 0
-18 Column 0 1
-19 Column 1 0
-20 Column 1 1
-21 Callback 4 0
-22 Next 1 14
-23 Next 0 10
-24 Close 0 0
-25 Close 1 0
-26 Halt 0 0
-}
-
-puts {
-<p>The outer loop over table examp is implement by instructions
-7 through 23. The inner loop is instructions 13 through 22.
-Notice that the "two<50" term of the WHERE expression involves
-only columns from the first table and can be factored out of
-the inner loop. SQLite does this and implements the "two<50"
-test in instructions 10 through 12. The "four==two" test is
-implement by instructions 14 through 16 in the inner loop.</p>
-
-<p>SQLite does not impose any arbitrary limits on the tables in
-a join. It also allows a table to be joined with itself.</p>
-
-<h2>The ORDER BY clause</h2>
-
-<p>For historical reasons, and for efficiency, all sorting is currently
-done in memory.</p>
-
-<p>SQLite implements the ORDER BY clause using a special
-set of instructions to control an object called a sorter. In the
-inner-most loop of the query, where there would normally be
-a Callback instruction, instead a record is constructed that
-contains both callback parameters and a key. This record
-is added to the sorter (in a linked list). After the query loop
-finishes, the list of records is sorted and this list is walked. For
-each record on the list, the callback is invoked. Finally, the sorter
-is closed and memory is deallocated.</p>
-
-<p>We can see the process in action in the following query:</p>
-
-<blockquote><pre>
-SELECT * FROM examp ORDER BY one DESC, two;
-</pre></blockquote>
-}
-
-Code {
-addr opcode p1 p2 p3
----- ------------ ----- ----- -----------------------------------
-0 ColumnName 0 0 one
-1 ColumnName 1 0 two
-2 Integer 0 0
-3 OpenRead 0 3 examp
-4 VerifyCookie 0 909
-5 Rewind 0 14
-6 Column 0 0
-7 Column 0 1
-8 SortMakeRec 2 0
-9 Column 0 0
-10 Column 0 1
-11 SortMakeKey 2 0 D+
-12 SortPut 0 0
-13 Next 0 6
-14 Close 0 0
-15 Sort 0 0
-16 SortNext 0 19
-17 SortCallback 2 0
-18 Goto 0 16
-19 SortReset 0 0
-20 Halt 0 0
-}
-
-puts {
-<p>There is only one sorter object, so there are no instructions to open
-or close it. It is opened automatically when needed, and it is closed
-when the VDBE program halts.</p>
-
-<p>The query loop is built from instructions 5 through 13. Instructions
-6 through 8 build a record that contains the azData[] values for a single
-invocation of the callback. A sort key is generated by instructions
-9 through 11. Instruction 12 combines the invocation record and the
-sort key into a single entry and puts that entry on the sort list.<p>
-
-<p>The P3 argument of instruction 11 is of particular interest. The
-sort key is formed by prepending one character from P3 to each string
-and concatenating all the strings. The sort comparison function will
-look at this character to determine whether the sort order is
-ascending or descending, and whether to sort as a string or number.
-In this example, the first column should be sorted as a string
-in descending order so its prefix is "D" and the second column should
-sorted numerically in ascending order so its prefix is "+". Ascending
-string sorting uses "A", and descending numeric sorting uses "-".</p>
-
-<p>After the query loop ends, the table being queried is closed at
-instruction 14. This is done early in order to allow other processes
-or threads to access that table, if desired. The list of records
-that was built up inside the query loop is sorted by the instruction
-at 15. Instructions 16 through 18 walk through the record list
-(which is now in sorted order) and invoke the callback once for
-each record. Finally, the sorter is closed at instruction 19.</p>
-
-<h2>Aggregate Functions And The GROUP BY and HAVING Clauses</h2>
-
-<p>To compute aggregate functions, the VDBE implements a special
-data structure and instructions for controlling that data structure.
-The data structure is an unordered set of buckets, where each bucket
-has a key and one or more memory locations. Within the query
-loop, the GROUP BY clause is used to construct a key and the bucket
-with that key is brought into focus. A new bucket is created with
-the key if one did not previously exist. Once the bucket is in
-focus, the memory locations of the bucket are used to accumulate
-the values of the various aggregate functions. After the query
-loop terminates, each bucket is visited once to generate a
-single row of the results.</p>
-
-<p>An example will help to clarify this concept. Consider the
-following query:</p>
-
-<blockquote><pre>
-SELECT three, min(three+four)+avg(four)
-FROM examp2
-GROUP BY three;
-</pre></blockquote>
-
-
-<p>The VDBE code generated for this query is as follows:</p>
-}
-
-Code {
-addr opcode p1 p2 p3
----- ------------ ----- ----- -----------------------------------
-0 ColumnName 0 0 three
-1 ColumnName 1 0 min(three+four)+avg(four)
-2 AggReset 0 3
-3 AggInit 0 1 ptr(0x7903a0)
-4 AggInit 0 2 ptr(0x790700)
-5 Integer 0 0
-6 OpenRead 0 5 examp2
-7 VerifyCookie 0 909
-8 Rewind 0 23
-9 Column 0 0
-10 MakeKey 1 0 n
-11 AggFocus 0 14
-12 Column 0 0
-13 AggSet 0 0
-14 Column 0 0
-15 Column 0 1
-16 Add 0 0
-17 Integer 1 0
-18 AggFunc 0 1 ptr(0x7903a0)
-19 Column 0 1
-20 Integer 2 0
-21 AggFunc 0 1 ptr(0x790700)
-22 Next 0 9
-23 Close 0 0
-24 AggNext 0 31
-25 AggGet 0 0
-26 AggGet 0 1
-27 AggGet 0 2
-28 Add 0 0
-29 Callback 2 0
-30 Goto 0 24
-31 Noop 0 0
-32 Halt 0 0
-}
-
-puts {
-<p>The first instruction of interest is the
-<a href="opcode.html#AggReset">AggReset</a> at 2.
-The AggReset instruction initializes the set of buckets to be the
-empty set and specifies the number of memory slots available in each
-bucket as P2. In this example, each bucket will hold 3 memory slots.
-It is not obvious, but if you look closely at the rest of the program
-you can figure out what each of these slots is intended for.</p>
-
-<blockquote><table border="2" cellpadding="5">
-<tr><th>Memory Slot</th><th>Intended Use Of This Memory Slot</th></tr>
-<tr><td>0</td><td>The "three" column -- the key to the bucket</td></tr>
-<tr><td>1</td><td>The minimum "three+four" value</td></tr>
-<tr><td>2</td><td>The sum of all "four" values. This is used to compute
- "avg(four)".</td></tr>
-</table></blockquote>
-
-<p>The query loop is implemented by instructions 8 through 22.
-The aggregate key specified by the GROUP BY clause is computed
-by instructions 9 and 10. Instruction 11 causes the appropriate
-bucket to come into focus. If a bucket with the given key does
-not already exists, a new bucket is created and control falls
-through to instructions 12 and 13 which initialize the bucket.
-If the bucket does already exist, then a jump is made to instruction
-14. The values of aggregate functions are updated by the instructions
-between 11 and 21. Instructions 14 through 18 update memory
-slot 1 to hold the next value "min(three+four)". Then the sum of the
-"four" column is updated by instructions 19 through 21.</p>
-
-<p>After the query loop is finished, the table "examp2" is closed at
-instruction 23 so that its lock will be released and it can be
-used by other threads or processes. The next step is to loop
-over all aggregate buckets and output one row of the result for
-each bucket. This is done by the loop at instructions 24
-through 30. The AggNext instruction at 24 brings the next bucket
-into focus, or jumps to the end of the loop if all buckets have
-been examined already. The 3 columns of the result are fetched from
-the aggregator bucket in order at instructions 25 through 27.
-Finally, the callback is invoked at instruction 29.</p>
-
-<p>In summary then, any query with aggregate functions is implemented
-by two loops. The first loop scans the input table and computes
-aggregate information into buckets and the second loop scans through
-all the buckets to compute the final result.</p>
-
-<p>The realization that an aggregate query is really two consequtive
-loops makes it much easier to understand the difference between
-a WHERE clause and a HAVING clause in SQL query statement. The
-WHERE clause is a restriction on the first loop and the HAVING
-clause is a restriction on the second loop. You can see this
-by adding both a WHERE and a HAVING clause to our example query:</p>
-
-
-<blockquote><pre>
-SELECT three, min(three+four)+avg(four)
-FROM examp2
-WHERE three>four
-GROUP BY three
-HAVING avg(four)<10;
-</pre></blockquote>
-}
-
-Code {
-addr opcode p1 p2 p3
----- ------------ ----- ----- -----------------------------------
-0 ColumnName 0 0 three
-1 ColumnName 1 0 min(three+four)+avg(four)
-2 AggReset 0 3
-3 AggInit 0 1 ptr(0x7903a0)
-4 AggInit 0 2 ptr(0x790700)
-5 Integer 0 0
-6 OpenRead 0 5 examp2
-7 VerifyCookie 0 909
-8 Rewind 0 26
-9 Column 0 0
-10 Column 0 1
-11 Le 1 25
-12 Column 0 0
-13 MakeKey 1 0 n
-14 AggFocus 0 17
-15 Column 0 0
-16 AggSet 0 0
-17 Column 0 0
-18 Column 0 1
-19 Add 0 0
-20 Integer 1 0
-21 AggFunc 0 1 ptr(0x7903a0)
-22 Column 0 1
-23 Integer 2 0
-24 AggFunc 0 1 ptr(0x790700)
-25 Next 0 9
-26 Close 0 0
-27 AggNext 0 37
-28 AggGet 0 2
-29 Integer 10 0 10
-30 Ge 1 27
-31 AggGet 0 0
-32 AggGet 0 1
-33 AggGet 0 2
-34 Add 0 0
-35 Callback 2 0
-36 Goto 0 27
-37 Noop 0 0
-38 Halt 0 0
-}
-
-puts {
-<p>The code generated in this last example is the same as the
-previous except for the addition of two conditional jumps used
-to implement the extra WHERE and HAVING clauses. The WHERE
-clause is implemented by instructions 9 through 11 in the query
-loop. The HAVING clause is implemented by instruction 28 through
-30 in the output loop.</p>
-
-<h2>Using SELECT Statements As Terms In An Expression</h2>
-
-<p>The very name "Structured Query Language" tells us that SQL should
-support nested queries. And, in fact, two different kinds of nesting
-are supported. Any SELECT statement that returns a single-row, single-column
-result can be used as a term in an expression of another SELECT statement.
-And, a SELECT statement that returns a single-column, multi-row result
-can be used as the right-hand operand of the IN and NOT IN operators.
-We will begin this section with an example of the first kind of nesting,
-where a single-row, single-column SELECT is used as a term in an expression
-of another SELECT. Here is our example:</p>
-
-<blockquote><pre>
-SELECT * FROM examp
-WHERE two!=(SELECT three FROM examp2
- WHERE four=5);
-</pre></blockquote>
-
-<p>The way SQLite deals with this is to first run the inner SELECT
-(the one against examp2) and store its result in a private memory
-cell. SQLite then substitutes the value of this private memory
-cell for the inner SELECT when it evaluates the outer SELECT.
-The code looks like this:</p>
-}
-
-Code {
-addr opcode p1 p2 p3
----- ------------ ----- ----- -----------------------------------
-0 String 0 0
-1 MemStore 0 1
-2 Integer 0 0
-3 OpenRead 1 5 examp2
-4 VerifyCookie 0 909
-5 Rewind 1 13
-6 Column 1 1
-7 Integer 5 0 5
-8 Ne 1 12
-9 Column 1 0
-10 MemStore 0 1
-11 Goto 0 13
-12 Next 1 6
-13 Close 1 0
-14 ColumnName 0 0 one
-15 ColumnName 1 0 two
-16 Integer 0 0
-17 OpenRead 0 3 examp
-18 Rewind 0 26
-19 Column 0 1
-20 MemLoad 0 0
-21 Eq 1 25
-22 Column 0 0
-23 Column 0 1
-24 Callback 2 0
-25 Next 0 19
-26 Close 0 0
-27 Halt 0 0
-}
-
-puts {
-<p>The private memory cell is initialized to NULL by the first
-two instructions. Instructions 2 through 13 implement the inner
-SELECT statement against the examp2 table. Notice that instead of
-sending the result to a callback or storing the result on a sorter,
-the result of the query is pushed into the memory cell by instruction
-10 and the loop is abandoned by the jump at instruction 11.
-The jump at instruction at 11 is vestigial and never executes.</p>
-
-<p>The outer SELECT is implemented by instructions 14 through 25.
-In particular, the WHERE clause that contains the nested select
-is implemented by instructions 19 through 21. You can see that
-the result of the inner select is loaded onto the stack by instruction
-20 and used by the conditional jump at 21.</p>
-
-<p>When the result of a sub-select is a scalar, a single private memory
-cell can be used, as shown in the previous
-example. But when the result of a sub-select is a vector, such
-as when the sub-select is the right-hand operand of IN or NOT IN,
-a different approach is needed. In this case,
-the result of the sub-select is
-stored in a transient table and the contents of that table
-are tested using the Found or NotFound operators. Consider this
-example:</p>
-
-<blockquote><pre>
-SELECT * FROM examp
-WHERE two IN (SELECT three FROM examp2);
-</pre></blockquote>
-
-<p>The code generated to implement this last query is as follows:</p>
-}
-
-Code {
-addr opcode p1 p2 p3
----- ------------ ----- ----- -----------------------------------
-0 OpenTemp 1 1
-1 Integer 0 0
-2 OpenRead 2 5 examp2
-3 VerifyCookie 0 909
-4 Rewind 2 10
-5 Column 2 0
-6 IsNull -1 9
-7 String 0 0
-8 PutStrKey 1 0
-9 Next 2 5
-10 Close 2 0
-11 ColumnName 0 0 one
-12 ColumnName 1 0 two
-13 Integer 0 0
-14 OpenRead 0 3 examp
-15 Rewind 0 25
-16 Column 0 1
-17 NotNull -1 20
-18 Pop 1 0
-19 Goto 0 24
-20 NotFound 1 24
-21 Column 0 0
-22 Column 0 1
-23 Callback 2 0
-24 Next 0 16
-25 Close 0 0
-26 Halt 0 0
-}
-
-puts {
-<p>The transient table in which the results of the inner SELECT are
-stored is created by the <a href="opcode.html#OpenTemp">OpenTemp</a>
-instruction at 0. This opcode is used for tables that exist for the
-duration of a single SQL statement only. The transient cursor is always
-opened read/write even if the main database is read-only. The transient
-table is deleted automatically when the cursor is closed. The P2 value
-of 1 means the cursor points to a BTree index, which has no data but can
-have an arbitrary key.</p>
-
-<p>The inner SELECT statement is implemented by instructions 1 through 10.
-All this code does is make an entry in the temporary table for each
-row of the examp2 table with a non-NULL value for the "three" column.
-The key for each temporary table entry is the "three" column of examp2
-and the data is an empty string since it is never used.</p>
-
-<p>The outer SELECT is implemented by instructions 11 through 25. In
-particular, the WHERE clause containing the IN operator is implemented
-by instructions at 16, 17, and 20. Instruction 16 pushes the value of
-the "two" column for the current row onto the stack and instruction 17
-checks to see that it is non-NULL. If this is successful, execution
-jumps to 20, where it tests to see if top of the stack matches any key
-in the temporary table. The rest of the code is the same as what has
-been shown before.</p>
-
-<h2>Compound SELECT Statements</h2>
-
-<p>SQLite also allows two or more SELECT statements to be joined as
-peers using operators UNION, UNION ALL, INTERSECT, and EXCEPT. These
-compound select statements are implemented using transient tables.
-The implementation is slightly different for each operator, but the
-basic ideas are the same. For an example we will use the EXCEPT
-operator.</p>
-
-<blockquote><pre>
-SELECT two FROM examp
-EXCEPT
-SELECT four FROM examp2;
-</pre></blockquote>
-
-<p>The result of this last example should be every unique value
-of the "two" column in the examp table, except any value that is
-in the "four" column of examp2 is removed. The code to implement
-this query is as follows:</p>
-}
-
-Code {
-addr opcode p1 p2 p3
----- ------------ ----- ----- -----------------------------------
-0 OpenTemp 0 1
-1 KeyAsData 0 1
-2 Integer 0 0
-3 OpenRead 1 3 examp
-4 VerifyCookie 0 909
-5 Rewind 1 11
-6 Column 1 1
-7 MakeRecord 1 0
-8 String 0 0
-9 PutStrKey 0 0
-10 Next 1 6
-11 Close 1 0
-12 Integer 0 0
-13 OpenRead 2 5 examp2
-14 Rewind 2 20
-15 Column 2 1
-16 MakeRecord 1 0
-17 NotFound 0 19
-18 Delete 0 0
-19 Next 2 15
-20 Close 2 0
-21 ColumnName 0 0 four
-22 Rewind 0 26
-23 Column 0 0
-24 Callback 1 0
-25 Next 0 23
-26 Close 0 0
-27 Halt 0 0
-}
-
-puts {
-<p>The transient table in which the result is built is created by
-instruction 0. Three loops then follow. The loop at instructions
-5 through 10 implements the first SELECT statement. The second
-SELECT statement is implemented by the loop at instructions 14 through
-19. Finally, a loop at instructions 22 through 25 reads the transient
-table and invokes the callback once for each row in the result.</p>
-
-<p>Instruction 1 is of particular importance in this example. Normally,
-the Column instruction extracts the value of a column from a larger
-record in the data of an SQLite file entry. Instruction 1 sets a flag on
-the transient table so that Column will instead treat the key of the
-SQLite file entry as if it were data and extract column information from
-the key.</p>
-
-<p>Here is what is going to happen: The first SELECT statement
-will construct rows of the result and save each row as the key of
-an entry in the transient table. The data for each entry in the
-transient table is a never used so we fill it in with an empty string.
-The second SELECT statement also constructs rows, but the rows
-constructed by the second SELECT are removed from the transient table.
-That is why we want the rows to be stored in the key of the SQLite file
-instead of in the data -- so they can be easily located and deleted.</p>
-
-<p>Let's look more closely at what is happening here. The first
-SELECT is implemented by the loop at instructions 5 through 10.
-Instruction 5 intializes the loop by rewinding its cursor.
-Instruction 6 extracts the value of the "two" column from "examp"
-and instruction 7 converts this into a row. Instruction 8 pushes
-an empty string onto the stack. Finally, instruction 9 writes the
-row into the temporary table. But remember, the PutStrKey opcode uses
-the top of the stack as the record data and the next on stack as the
-key. For an INSERT statement, the row generated by the
-MakeRecord opcode is the record data and the record key is an integer
-created by the NewRecno opcode. But here the roles are reversed and
-the row created by MakeRecord is the record key and the record data is
-just an empty string.</p>
-
-<p>The second SELECT is implemented by instructions 14 through 19.
-Instruction 14 intializes the loop by rewinding its cursor.
-A new result row is created from the "four" column of table "examp2"
-by instructions 15 and 16. But instead of using PutStrKey to write this
-new row into the temporary table, we instead call Delete to remove
-it from the temporary table if it exists.</p>
-
-<p>The result of the compound select is sent to the callback routine
-by the loop at instructions 22 through 25. There is nothing new
-or remarkable about this loop, except for the fact that the Column
-instruction at 23 will be extracting a column out of the record key
-rather than the record data.</p>
-
-<h2>Summary</h2>
-
-<p>This article has reviewed all of the major techniques used by
-SQLite's VDBE to implement SQL statements. What has not been shown
-is that most of these techniques can be used in combination to
-generate code for an appropriately complex query statement. For
-example, we have shown how sorting is accomplished on a simple query
-and we have shown how to implement a compound query. But we did
-not give an example of sorting in a compound query. This is because
-sorting a compound query does not introduce any new concepts: it
-merely combines two previous ideas (sorting and compounding)
-in the same VDBE program.</p>
-
-<p>For additional information on how the SQLite library
-functions, the reader is directed to look at the SQLite source
-code directly. If you understand the material in this article,
-you should not have much difficulty in following the sources.
-Serious students of the internals of SQLite will probably
-also what to make a careful study of the VDBE opcodes
-as documented <a href="opcode.html">here</a>. Most of the
-opcode documentation is extracted from comments in the source
-code using a script so you can also get information about the
-various opcodes directly from the <b>vdbe.c</b> source file.
-If you have successfully read this far, you should have little
-difficulty understanding the rest.</p>
-
-<p>If you find errors in either the documentation or the code,
-feel free to fix them and/or contact the author at
-<a href="mailto:drh@hwaci.com">drh@hwaci.com</a>. Your bug fixes or
-suggestions are always welcomed.</p>
-}
-footer $rcsid
+++ /dev/null
-#!/usr/bin/tclsh
-source common.tcl
-header {SQLite Version 3 Overview}
-puts {
-<h2>SQLite Version 3 Overview</h2>
-
-<p>
-SQLite version 3.0 introduces important changes to the library, including:
-</p>
-
-<ul>
-<li>A more compact format for database files.</li>
-<li>Manifest typing and BLOB support.</li>
-<li>Support for both UTF-8 and UTF-16 text.</li>
-<li>User-defined text collating sequences.</li>
-<li>64-bit ROWIDs.</li>
-<li>Improved Concurrency.</li>
-</ul>
-
-<p>
-This document is a quick introduction to the changes for SQLite 3.0
-for users who are already familiar with SQLite version 2.8.
-</p>
-
-<h3>Naming Changes</h3>
-
-<p>
-SQLite version 2.8 will continue to be supported with bug fixes
-for the foreseeable future. In order to allow SQLite version 2.8
-and SQLite version 3.0 to peacefully coexist, the names of key files
-and APIs in SQLite version 3.0 have been changed to include the
-character "3". For example, the include file used by C programs
-has been changed from "sqlite.h" to "sqlite3.h". And the name of
-the shell program used to interact with databases has been changed
-from "sqlite.exe" to "sqlite3.exe". With these changes, it is possible
-to have both SQLite 2.8 and SQLite 3.0 installed on the same system at
-the same time. And it is possible for the same C program to link
-against both SQLite 2.8 and SQLite 3.0 at the same time and to use
-both libraries at the same time.
-</p>
-
-<h3>New File Format</h3>
-
-<p>
-The format used by SQLite database files has been completely revised.
-The old version 2.1 format and the new 3.0 format are incompatible with
-one another. Version 2.8 of SQLite will not read a version 3.0 database
-files and version 3.0 of SQLite will not read a version 2.8 database file.
-</p>
-
-<p>
-To convert an SQLite 2.8 database into an SQLite 3.0 database, have
-ready the command-line shells for both version 2.8 and 3.0. Then
-enter a command like the following:
-</p>
-
-<blockquote><pre>
-sqlite OLD.DB .dump | sqlite3 NEW.DB
-</pre></blockquote>
-
-<p>
-The new database file format uses B+trees for tables. In a B+tree, all
-data is stored in the leaves of the tree instead of in both the leaves and
-the intermediate branch nodes. The use of B+trees for tables allows for
-better scalability and the storage of larger data fields without the use of
-overflow pages. Traditional B-trees are still used for indices.</p>
-
-<p>
-The new file format also supports variable pages sizes between 512 and
-32768 bytes. The size of a page is stored in the file header so the
-same library can read databases with different pages sizes, in theory,
-though this feature has not yet been implemented in practice.
-</p>
-
-<p>
-The new file format omits unused fields from its disk images. For example,
-indices use only the key part of a B-tree record and not the data. So
-for indices, the field that records the length of the data is omitted.
-Integer values such as the length of key and data are stored using
-a variable-length encoding so that only one or two bytes are required to
-store the most common cases but up to 64-bits of information can be encoded
-if needed.
-Integer and floating point data is stored on the disk in binary rather
-than being converted into ASCII as in SQLite version 2.8.
-These changes taken together result in database files that are typically
-25% to 35% smaller than the equivalent files in SQLite version 2.8.
-</p>
-
-<p>
-Details of the low-level B-tree format used in SQLite version 3.0 can
-be found in header comments to the
-<a href="http://www.sqlite.org/cvstrac/getfile/sqlite/src/btree.c">btree.c</a>
-source file.
-</p>
-
-<h3>Manifest Typing and BLOB Support</h3>
-
-<p>
-SQLite version 2.8 will deal with data in various formats internally,
-but when writing to the disk or interacting through its API, SQLite 2.8
-always converts data into ASCII text. SQLite 3.0, in contrast, exposes
-its internal data representations to the user and stores binary representations
-to disk when appropriate. The exposing of non-ASCII representations was
-added in order to support BLOBs.
-</p>
-
-<p>
-SQLite version 2.8 had the feature that any type of data could be stored
-in any table column regardless of the declared type of that column. This
-feature is retained in version 3.0, though in a slightly modified form.
-Each table column will store any type of data, though columns have an
-affinity for the format of data defined by their declared datatype.
-When data is inserted into a column, that column will make at attempt
-to convert the data format into the columns declared type. All SQL
-database engines do this. The difference is that SQLite 3.0 will
-still store the data even if a format conversion is not possible.
-</p>
-
-<p>
-For example, if you have a table column declared to be of type "INTEGER"
-and you try to insert a string, the column will look at the text string
-and see if it looks like a number. If the string does look like a number
-it is converted into a number and into an integer if the number does not
-have a fractional part, and stored that way. But if the string is not
-a well-formed number it is still stored as a string. A column with a
-type of "TEXT" tries to convert numbers into an ASCII-Text representation
-before storing them. But BLOBs are stored in TEXT columns as BLOBs because
-you cannot in general convert a BLOB into text.
-</p>
-
-<p>
-In most other SQL database engines the datatype is associated with
-the table column that holds the data - with the data container.
-In SQLite 3.0, the datatype is associated with the data itself, not
-with its container.
-<a href="http://www.paulgraham.com/">Paul Graham</a> in his book
-<a href="http://www.paulgraham.com/acl.html"><i>ANSI Common Lisp</i></a>
-calls this property "Manifest Typing".
-Other writers have other definitions for the term "manifest typing",
-so beware of confusion. But by whatever name, that is the datatype
-model supported by SQLite 3.0.
-</p>
-
-<p>
-Additional information about datatypes in SQLite version 3.0 is
-available
-<a href="datatype3.html">separately</a>.
-</p>
-
-<h3>Support for UTF-8 and UTF-16</h3>
-
-<p>
-The new API for SQLite 3.0 contains routines that accept text as
-both UTF-8 and UTF-16 in the native byte order of the host machine.
-Each database file manages text as either UTF-8, UTF-16BE (big-endian),
-or UTF-16LE (little-endian). Internally and in the disk file, the
-same text representation is used everywhere. If the text representation
-specified by the database file (in the file header) does not match
-the text representation required by the interface routines, then text
-is converted on-the-fly.
-Constantly converting text from one representation to another can be
-computationally expensive, so it is suggested that programmers choose a
-single representation and stick with it throughout their application.
-</p>
-
-<p>
-In the current implementation of SQLite, the SQL parser only works
-with UTF-8 text. So if you supply UTF-16 text it will be converted.
-This is just an implementation issue and there is nothing to prevent
-future versions of SQLite from parsing UTF-16 encoded SQL natively.
-</p>
-
-<p>
-When creating new user-defined SQL functions and collating sequences,
-each function or collating sequence can specify it if works with
-UTF-8, UTF-16be, or UTF-16le. Separate implementations can be registered
-for each encoding. If an SQL function or collating sequences is required
-but a version for the current text encoding is not available, then
-the text is automatically converted. As before, this conversion takes
-computation time, so programmers are advised to pick a single
-encoding and stick with it in order to minimize the amount of unnecessary
-format juggling.
-</p>
-
-<p>
-SQLite is not particular about the text it receives and is more than
-happy to process text strings that are not normalized or even
-well-formed UTF-8 or UTF-16. Thus, programmers who want to store
-IS08859 data can do so using the UTF-8 interfaces. As long as no
-attempts are made to use a UTF-16 collating sequence or SQL function,
-the byte sequence of the text will not be modified in any way.
-</p>
-
-<h3>User-defined Collating Sequences</h3>
-
-<p>
-A collating sequence is just a defined order for text. When SQLite 3.0
-sorts (or uses a comparison operator like "<" or ">=") the sort order
-is first determined by the data type.
-</p>
-
-<ul>
-<li>NULLs sort first</li>
-<li>Numeric values sort next in numerical order</li>
-<li>Text values come after numerics</li>
-<li>BLOBs sort last</li>
-</ul>
-
-<p>
-Collating sequences are used for comparing two text strings.
-The collating sequence does not change the ordering of NULLs, numbers,
-or BLOBs, only text.
-</p>
-
-<p>
-A collating sequence is implemented as a function that takes the
-two strings being compared as inputs and returns negative, zero, or
-positive if the first string is less than, equal to, or greater than
-the second.
-SQLite 3.0 comes with a single built-in collating sequence named "BINARY"
-which is implemented using the memcmp() routine from the standard C library.
-The BINARY collating sequence works well for English text. For other
-languages or locales, alternative collating sequences may be preferred.
-</p>
-
-<p>
-The decision of which collating sequence to use is controlled by the
-COLLATE clause in SQL. A COLLATE clause can occur on a table definition,
-to define a default collating sequence to a table column, or on field
-of an index, or in the ORDER BY clause of a SELECT statement.
-Planned enhancements to SQLite are to include standard CAST() syntax
-to allow the collating sequence of an expression to be defined.
-</p>
-
-<h3>64-bit ROWIDs</h3>
-
-<p>
-Every row of a table has a unique rowid.
-If the table defines a column with the type "INTEGER PRIMARY KEY" then that
-column becomes an alias for the rowid. But with or without an INTEGER PRIMARY
-KEY column, every row still has a rowid.
-</p>
-
-<p>
-In SQLite version 3.0, the rowid is a 64-bit signed integer.
-This is an expansion of SQLite version 2.8 which only permitted
-rowids of 32-bits.
-</p>
-
-<p>
-To minimize storage space, the 64-bit rowid is stored as a variable length
-integer. Rowids between 0 and 127 use only a single byte.
-Rowids between 0 and 16383 use just 2 bytes. Up to 2097152 uses three
-bytes. And so forth. Negative rowids are allowed but they always use
-nine bytes of storage and so their use is discouraged. When rowids
-are generated automatically by SQLite, they will always be non-negative.
-</p>
-
-<h3>Improved Concurrency</h3>
-
-<p>
-SQLite version 2.8 allowed multiple simultaneous readers or a single
-writer but not both. SQLite version 3.0 allows one process to begin
-writing the database while other processes continue to read. The
-writer must still obtain an exclusive lock on the database for a brief
-interval in order to commit its changes, but the exclusive lock is no
-longer required for the entire write operation.
-A <a href="lockingv3.html">more detailed report</a> on the locking
-behavior of SQLite version 3.0 is available separately.
-</p>
-
-<p>
-A limited form of table-level locking is now also available in SQLite.
-If each table is stored in a separate database file, those separate
-files can be attached to the main database (using the ATTACH command)
-and the combined databases will function as one. But locks will only
-be acquired on individual files as needed. So if you redefine "database"
-to mean two or more database files, then it is entirely possible for
-two processes to be writing to the same database at the same time.
-To further support this capability, commits of transactions involving
-two or more ATTACHed database are now atomic.
-</p>
-
-<h3>Credits</h3>
-
-<p>
-SQLite version 3.0 is made possible in part by AOL developers
-supporting and embracing great Open-Source Software.
-</p>
-
-
-}
-footer {$Id: version3.tcl,v 1.6 2006/03/03 21:39:54 drh Exp $}
+++ /dev/null
-#
-# Run this TCL script to generate HTML for the goals.html file.
-#
-set rcsid {$Id: whentouse.tcl,v 1.7 2007/04/14 12:04:39 drh Exp $}
-source common.tcl
-header {Appropriate Uses For SQLite}
-
-puts {
-<p>
-SQLite is different from most other SQL database engines in that its
-primary design goal is to be simple:
-</p>
-
-<ul>
-<li>Simple to administer</li>
-<li>Simple to operate</li>
-<li>Simple to embed in a larger program</li>
-<li>Simple to maintain and customize</li>
-</ul>
-
-<p>
-Many people like SQLite because it is small and fast. But those
-qualities are just happy accidents.
-Users also find that SQLite is very reliable. Reliability is
-a consequence of simplicity. With less complication, there is
-less to go wrong. So, yes, SQLite is small, fast, and reliable,
-but first and foremost, SQLite strives to be simple.
-</p>
-
-<p>
-Simplicity in a database engine can be either a strength or a
-weakness, depending on what you are trying to do. In order to
-achieve simplicity, SQLite has had to sacrifice other characteristics
-that some people find useful, such as high concurrency, fine-grained
-access control, a rich set of built-in functions, stored procedures,
-esoteric SQL language features, XML and/or Java extensions,
-tera- or peta-byte scalability, and so forth. If you need some of these
-features and do not mind the added complexity that they
-bring, then SQLite is probably not the database for you.
-SQLite is not intended to be an enterprise database engine. It
-not designed to compete with Oracle or PostgreSQL.
-</p>
-
-<p>
-The basic rule of thumb for when it is appropriate to use SQLite is
-this: Use SQLite in situations where simplicity of administration,
-implementation, and maintenance are more important than the countless
-complex features that enterprise database engines provide.
-As it turns out, situations where simplicity is the better choice
-are more common than many people realize.
-</p>
-
-<h2>Situations Where SQLite Works Well</h2>
-
-<ul>
-<li><p><b>Websites</b></p>
-
-<p>SQLite usually will work great as the database engine for low to
-medium traffic websites (which is to say, 99.9% of all websites).
-The amount of web traffic that SQLite can handle depends, of course,
-on how heavily the website uses its database. Generally
-speaking, any site that gets fewer than a 100000 hits/day should work
-fine with SQLite.
-The 100000 hits/day figure is a conservative estimate, not a
-hard upper bound.
-SQLite has been demonstrated to work with 10 times that amount
-of traffic.</p>
-</li>
-
-<li><p><b>Embedded devices and applications</b></p>
-
-<p>Because an SQLite database requires little or no administration,
-SQLite is a good choice for devices or services that must work
-unattended and without human support. SQLite is a good fit for
-use in cellphones, PDAs, set-top boxes, and/or appliances. It also
-works well as an embedded database in downloadable consumer applications.
-</p>
-</li>
-
-<li><p><b>Application File Format</b></p>
-
-<p>
-SQLite has been used with great success as the on-disk file format
-for desktop applications such as financial analysis tools, CAD
-packages, record keeping programs, and so forth. The traditional
-File/Open operation does an sqlite3_open() and executes a
-BEGIN TRANSACTION to get exclusive access to the content. File/Save
-does a COMMIT followed by another BEGIN TRANSACTION. The use
-of transactions guarantees that updates to the application file are atomic,
-durable, isolated, and consistent.
-</p>
-
-<p>
-Temporary triggers can be added to the database to record all
-changes into a (temporary) undo/redo log table. These changes can then
-be played back when the user presses the Undo and Redo buttons. Using
-this technique, a unlimited depth undo/redo implementation can be written
-in surprising little code.
-</p>
-</li>
-
-<li><p><b>Replacement for <i>ad hoc</i> disk files</b></p>
-
-<p>Many programs use fopen(), fread(), and fwrite() to create and
-manage files of data in home-grown formats. SQLite works
-particularly well as a
-replacement for these <i>ad hoc</i> data files.</p>
-</li>
-
-<li><p><b>Internal or temporary databases</b></p>
-
-<p>
-For programs that have a lot of data that must be sifted and sorted
-in diverse ways, it is often easier and quicker to load the data into
-an in-memory SQLite database and use queries with joins and ORDER BY
-clauses to extract the data in the form and order needed rather than
-to try to code the same operations manually.
-Using an SQL database internally in this way also gives the program
-greater flexibility since new columns and indices can be added without
-having to recode every query.
-</p>
-</li>
-
-<li><p><b>Command-line dataset analysis tool</b></p>
-
-<p>
-Experienced SQL users can employ
-the command-line <b>sqlite</b> program to analyze miscellaneous
-datasets. Raw data can be imported from CSV files, then that
-data can be sliced and diced to generate a myriad of summary
-reports. Possible uses include website log analysis, sports
-statistics analysis, compilation of programming metrics, and
-analysis of experimental results.
-</p>
-
-<p>
-You can also do the same thing with a enterprise client/server
-database, of course. The advantages to using SQLite in this situation
-are that SQLite is much easier to set up and the resulting database
-is a single file that you can store on a floppy disk or flash-memory stick
-or email to a colleague.
-</p>
-</li>
-
-<li><p><b>Stand-in for an enterprise database during demos or testing</b></p>
-
-<p>
-If you are writing a client application for an enterprise database engine,
-it makes sense to use a generic database backend that allows you to connect
-to many different kinds of SQL database engines. It makes even better
-sense to
-go ahead and include SQLite in the mix of supported database and to statically
-link the SQLite engine in with the client. That way the client program
-can be used standalone with an SQLite data file for testing or for
-demonstrations.
-</p>
-</li>
-
-<li><p><b>Database Pedagogy</b></p>
-
-<p>
-Because it is simple to setup and use (installation is trivial: just
-copy the <b>sqlite</b> or <b>sqlite.exe</b> executable to the target machine
-and run it) SQLite makes a good database engine for use in teaching SQL.
-Students can easily create as many databases as they like and can
-email databases to the instructor for comments or grading. For more
-advanced students who are interested in studying how an RDBMS is
-implemented, the modular and well-commented and documented SQLite code
-can serve as a good basis. This is not to say that SQLite is an accurate
-model of how other database engines are implemented, but rather a student who
-understands how SQLite works can more quickly comprehend the operational
-principles of other systems.
-</p>
-</li>
-
-<li><p><b>Experimental SQL language extensions</b></p>
-
-<p>The simple, modular design of SQLite makes it a good platform for
-prototyping new, experimental database language features or ideas.
-</p>
-</li>
-
-
-</ul>
-
-<h2>Situations Where Another RDBMS May Work Better</h2>
-
-<ul>
-<li><p><b>Client/Server Applications</b><p>
-
-<p>If you have many client programs accessing a common database
-over a network, you should consider using a client/server database
-engine instead of SQLite. SQLite will work over a network filesystem,
-but because of the latency associated with most network filesystems,
-performance will not be great. Also, the file locking logic of
-many network filesystems implementation contains bugs (on both Unix
-and windows). If file locking does not work like it should,
-it might be possible for two or more client programs to modify the
-same part of the same database at the same time, resulting in
-database corruption. Because this problem results from bugs in
-the underlying filesystem implementation, there is nothing SQLite
-can do to prevent it.</p>
-
-<p>A good rule of thumb is that you should avoid using SQLite
-in situations where the same database will be accessed simultaneously
-from many computers over a network filesystem.</p>
-</li>
-
-<li><p><b>High-volume Websites</b></p>
-
-<p>SQLite will normally work fine as the database backend to a website.
-But if you website is so busy that your are thinking of splitting the
-database component off onto a separate machine, then you should
-definitely consider using an enterprise-class client/server database
-engine instead of SQLite.</p>
-</li>
-
-<li><p><b>Very large datasets</b></p>
-
-<p>When you start a transaction in SQLite (which happens automatically
-before any write operation that is not within an explicit BEGIN...COMMIT)
-the engine has to allocate a bitmap of dirty pages in the disk file to
-help it manage its rollback journal. SQLite needs 256 bytes of RAM for
-every 1MiB of database (assuming a 1024-byte page size: less memory is
-used with larger page sizes, of course).
-For smaller databases, the amount of memory
-required is not a problem, but when database begin to grow into the
-multi-gigabyte range, the size of the bitmap can get quite large. If
-you need to store and modify more than a few dozen GB of data, you should
-consider using a different database engine.
-</p>
-</li>
-
-<li><p><b>High Concurrency</b></p>
-
-<p>
-SQLite uses reader/writer locks on the entire database file. That means
-if any process is reading from any part of the database, all other
-processes are prevented from writing any other part of the database.
-Similarly, if any one process is writing to the database,
-all other processes are prevented from reading any other part of the
-database.
-For many situations, this is not a problem. Each application
-does its database work quickly and moves on, and no lock lasts for more
-than a few dozen milliseconds. But there are some applications that require
-more concurrency, and those applications may need to seek a different
-solution.
-</p>
-</li>
-
-</ul>
-
-}
-footer $rcsid
projects / thirdparty / sqlite.git / commitdiff
