diff options
| author | drh <drh@noemail.net> | 2008-05-26 20:19:25 +0000 |
|---|---|---|
| committer | drh <drh@noemail.net> | 2008-05-26 20:19:25 +0000 |
| commit | 58f1c8b773835cfba8683d3ed058966581c4f6a3 (patch) | |
| tree | 3fc21b8494e7dcd04543bf4febb97f8813471317 | |
| parent | ebaecc148f39320fe70eda47b51e2133709ea2bd (diff) | |
| download | sqlite-58f1c8b773835cfba8683d3ed058966581c4f6a3.tar.gz sqlite-58f1c8b773835cfba8683d3ed058966581c4f6a3.zip | |
Update the amalgamation builder to incorporate the RTREE extension. (CVS 5160)
FossilOrigin-Name: aa8eba3360c31182f5238e96b83a382374f40fab
| -rw-r--r-- | ext/rtree/README | 9 | ||||
| -rw-r--r-- | ext/rtree/rtree.c | 24 | ||||
| -rw-r--r-- | ext/rtree/rtree.h | 26 | ||||
| -rw-r--r-- | main.mk | 6 | ||||
| -rw-r--r-- | manifest | 83 | ||||
| -rw-r--r-- | manifest.uuid | 2 | ||||
| -rw-r--r-- | publish.sh | 8 | ||||
| -rw-r--r-- | src/main.c | 7 | ||||
| -rw-r--r-- | tool/mksqlite3c.tcl | 3 | ||||
| -rw-r--r-- | www/34to35.tcl | 1006 | ||||
| -rw-r--r-- | www/arch.fig | 64 | ||||
| -rw-r--r-- | www/arch.gif | bin | 6487 -> 0 bytes | |||
| -rw-r--r-- | www/arch.png | bin | 4447 -> 0 bytes | |||
| -rw-r--r-- | www/arch.tcl | 221 | ||||
| -rw-r--r-- | www/arch2.fig | 123 | ||||
| -rw-r--r-- | www/arch2.gif | bin | 6501 -> 0 bytes | |||
| -rw-r--r-- | www/arch2b.fig | 125 | ||||
| -rw-r--r-- | www/audit.tcl | 214 | ||||
| -rw-r--r-- | www/autoinc.tcl | 109 | ||||
| -rw-r--r-- | www/c_interface.tcl | 1116 | ||||
| -rw-r--r-- | www/capi3.tcl | 516 | ||||
| -rw-r--r-- | www/capi3ref.tcl | 1882 | ||||
| -rw-r--r-- | www/changes.tcl | 1880 | ||||
| -rw-r--r-- | www/common.tcl | 90 | ||||
| -rw-r--r-- | www/compile.tcl | 278 | ||||
| -rw-r--r-- | www/conflict.tcl | 91 | ||||
| -rw-r--r-- | www/copyright-release.html | 109 | ||||
| -rw-r--r-- | www/copyright-release.pdf | bin | 2848 -> 0 bytes | |||
| -rw-r--r-- | www/copyright.tcl | 126 | ||||
| -rw-r--r-- | www/datatype3.tcl | 440 | ||||
| -rw-r--r-- | www/datatypes.tcl | 243 | ||||
| -rw-r--r-- | www/different.tcl | 224 | ||||
| -rw-r--r-- | www/direct1b.gif | bin | 11439 -> 0 bytes | |||
| -rw-r--r-- | www/docs.tcl | 159 | ||||
| -rw-r--r-- | www/download.tcl | 236 | ||||
| -rw-r--r-- | www/dynload.tcl | 70 | ||||
| -rw-r--r-- | www/faq.tcl | 463 | ||||
| -rw-r--r-- | www/fileformat.tcl | 785 | ||||
| -rw-r--r-- | www/formatchng.tcl | 285 | ||||
| -rw-r--r-- | www/fullscanb.gif | bin | 11946 -> 0 bytes | |||
| -rw-r--r-- | www/index-ex1-x-b.gif | bin | 23173 -> 0 bytes | |||
| -rw-r--r-- | www/index.tcl | 115 | ||||
| -rw-r--r-- | www/indirect1b1.gif | bin | 18098 -> 0 bytes | |||
| -rw-r--r-- | www/lang.tcl | 2207 | ||||
| -rw-r--r-- | www/limits.tcl | 318 | ||||
| -rw-r--r-- | www/lockingv3.tcl | 570 | ||||
| -rw-r--r-- | www/mingw.tcl | 160 | ||||
| -rw-r--r-- | www/mkapidoc.tcl | 176 | ||||
| -rw-r--r-- | www/nulls.tcl | 329 | ||||
| -rw-r--r-- | www/oldnews.tcl | 509 | ||||
| -rw-r--r-- | www/omitted.tcl | 85 | ||||
| -rw-r--r-- | www/opcode.tcl | 243 | ||||
| -rw-r--r-- | www/optimizer.tcl | 265 | ||||
| -rw-r--r-- | www/optimizing.tcl | 15 | ||||
| -rw-r--r-- | www/optoverview.tcl | 516 | ||||
| -rw-r--r-- | www/pragma.tcl | 635 | ||||
| -rw-r--r-- | www/quickstart.tcl | 110 | ||||
| -rw-r--r-- | www/shared.gif | bin | 5787 -> 0 bytes | |||
| -rw-r--r-- | www/sharedcache.tcl | 221 | ||||
| -rw-r--r-- | www/speed.tcl | 495 | ||||
| -rw-r--r-- | www/sqlite.tcl | 582 | ||||
| -rw-r--r-- | www/support.tcl | 79 | ||||
| -rw-r--r-- | www/table-ex1b2.gif | bin | 10888 -> 0 bytes | |||
| -rw-r--r-- | www/tclsqlite.tcl | 666 | ||||
| -rw-r--r-- | www/vdbe.tcl | 1988 | ||||
| -rw-r--r-- | www/version3.tcl | 293 | ||||
| -rw-r--r-- | www/whentouse.tcl | 254 |
67 files changed, 75 insertions, 21779 deletions
diff --git a/ext/rtree/README b/ext/rtree/README index f2bb90735..2c3a8ba1f 100644 --- a/ext/rtree/README +++ b/ext/rtree/README @@ -80,7 +80,7 @@ and query r-tree structures using ordinary SQL statements. 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 @@ -98,14 +98,14 @@ and query r-tree structures using ordinary SQL statements. 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. @@ -118,6 +118,3 @@ and query r-tree structures using ordinary SQL statements. [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. - - - diff --git a/ext/rtree/rtree.c b/ext/rtree/rtree.c index 1d2685980..6eafd440c 100644 --- a/ext/rtree/rtree.c +++ b/ext/rtree/rtree.c @@ -12,7 +12,7 @@ ** 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) @@ -66,9 +66,11 @@ #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; @@ -1356,7 +1358,7 @@ static int parentWrite(Rtree *pRtree, sqlite3_int64 iNode, sqlite3_int64 iPar){ return sqlite3_reset(pRtree->pWriteParent); } -static int insertCell(Rtree *, RtreeNode *, RtreeCell *, int); +static int rtreeInsertCell(Rtree *, RtreeNode *, RtreeCell *, int); #if VARIANT_GUTTMAN_LINEAR_SPLIT /* @@ -1894,7 +1896,7 @@ static int SplitNode( 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; } @@ -1904,7 +1906,7 @@ static int SplitNode( 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; } @@ -2149,7 +2151,7 @@ static int Reinsert( 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; @@ -2165,7 +2167,7 @@ static int Reinsert( ** 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, @@ -2218,7 +2220,7 @@ static int reinsertNodeContent(Rtree *pRtree, RtreeNode *pNode){ 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; @@ -2389,7 +2391,7 @@ int rtreeUpdate( 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; diff --git a/ext/rtree/rtree.h b/ext/rtree/rtree.h new file mode 100644 index 000000000..1fdbcccc5 --- /dev/null +++ b/ext/rtree/rtree.h @@ -0,0 +1,26 @@ +/* +** 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 */ @@ -77,6 +77,7 @@ EXTOBJ += fts3.o \ fts3_porter.o \ fts3_tokenizer.o \ fts3_tokenizer1.o +EXTOBJ += rtree.o # All of the source code files. # @@ -186,6 +187,9 @@ SRC += \ $(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 @@ -274,6 +278,8 @@ EXTHDR += \ $(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. @@ -1,5 +1,5 @@ -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 @@ -63,8 +63,9 @@ F ext/fts3/fts3_tokenizer1.c 0a5bcc579f35de5d24a9345d7908dc25ae403ee7 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 @@ -74,14 +75,14 @@ F ext/rtree/rtree_util.tcl ee0a0311eb12175319d78bfb37302320496cee6e 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 @@ -111,7 +112,7 @@ F src/insert.c 77f0829b3e2edd19e9238195c56b0d56ab000f17 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 @@ -573,7 +574,7 @@ F tool/memleak2.awk 9cc20c8e8f3c675efac71ea0721ee6874a1566e8 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 @@ -588,65 +589,7 @@ F tool/speedtest16.c 6f5bc019dcf8b6537f379bbac0408a9e1a86f0b6 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 diff --git a/manifest.uuid b/manifest.uuid index b1fda07cc..263cc7359 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -b104dcd6adadbd3fe15a348fe9d4d290119e139e
\ No newline at end of file +aa8eba3360c31182f5238e96b83a382374f40fab
\ No newline at end of file diff --git a/publish.sh b/publish.sh index 138f3d901..dca30b7a9 100644 --- a/publish.sh +++ b/publish.sh @@ -24,7 +24,8 @@ echo "VERSIONS: $VERS $VERSW" # 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 @@ -51,7 +52,8 @@ zip doc/sqlite-amalgamation-$VERSW.zip sqlite3.c sqlite3.h sqlite3ext.h # 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 @@ -79,7 +81,7 @@ zip doc/sqlitedll-$VERSW.zip sqlite3.dll sqlite3.def # 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 diff --git a/src/main.c b/src/main.c index ecdc8e961..c80bacb5c 100644 --- a/src/main.c +++ b/src/main.c @@ -14,13 +14,17 @@ ** 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 @@ -1187,7 +1191,6 @@ static int openDatabase( #ifdef SQLITE_ENABLE_RTREE if( !db->mallocFailed && rc==SQLITE_OK){ - extern int sqlite3RtreeInit(sqlite3*); rc = sqlite3RtreeInit(db); } #endif diff --git a/tool/mksqlite3c.tcl b/tool/mksqlite3c.tcl index 837ffa679..fd0ea4a41 100644 --- a/tool/mksqlite3c.tcl +++ b/tool/mksqlite3c.tcl @@ -100,6 +100,7 @@ foreach hdr { os_os2.h pager.h parse.h + rtree.h sqlite3ext.h sqlite3.h sqliteInt.h @@ -273,6 +274,8 @@ foreach file { fts3_porter.c fts3_tokenizer.c fts3_tokenizer1.c + + rtree.c } { copy_file tsrc/$file } diff --git a/www/34to35.tcl b/www/34to35.tcl deleted file mode 100644 index cb488e78d..000000000 --- a/www/34to35.tcl +++ /dev/null @@ -1,1006 +0,0 @@ -# -# 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. -} diff --git a/www/arch.fig b/www/arch.fig deleted file mode 100644 index d127a276e..000000000 --- a/www/arch.fig +++ /dev/null @@ -1,64 +0,0 @@ -#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 diff --git a/www/arch.gif b/www/arch.gif Binary files differdeleted file mode 100644 index 4dd8d1409..000000000 --- a/www/arch.gif +++ /dev/null diff --git a/www/arch.png b/www/arch.png Binary files differdeleted file mode 100644 index 7a2a3ab11..000000000 --- a/www/arch.png +++ /dev/null diff --git a/www/arch.tcl b/www/arch.tcl deleted file mode 100644 index d6c816603..000000000 --- a/www/arch.tcl +++ /dev/null @@ -1,221 +0,0 @@ -# -# 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 diff --git a/www/arch2.fig b/www/arch2.fig deleted file mode 100644 index 70bc5f16a..000000000 --- a/www/arch2.fig +++ /dev/null @@ -1,123 +0,0 @@ -#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 diff --git a/www/arch2.gif b/www/arch2.gif Binary files differdeleted file mode 100644 index cca292517..000000000 --- a/www/arch2.gif +++ /dev/null diff --git a/www/arch2b.fig b/www/arch2b.fig deleted file mode 100644 index e8ba8cc8e..000000000 --- a/www/arch2b.fig +++ /dev/null @@ -1,125 +0,0 @@ -#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 diff --git a/www/audit.tcl b/www/audit.tcl deleted file mode 100644 index 8b30373ae..000000000 --- a/www/audit.tcl +++ /dev/null @@ -1,214 +0,0 @@ -# -# 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>} diff --git a/www/autoinc.tcl b/www/autoinc.tcl deleted file mode 100644 index 9332adc85..000000000 --- a/www/autoinc.tcl +++ /dev/null @@ -1,109 +0,0 @@ -# -# 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 diff --git a/www/c_interface.tcl b/www/c_interface.tcl deleted file mode 100644 index c784ff042..000000000 --- a/www/c_interface.tcl +++ /dev/null @@ -1,1116 +0,0 @@ -# -# 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 diff --git a/www/capi3.tcl b/www/capi3.tcl deleted file mode 100644 index 149cf7f0a..000000000 --- a/www/capi3.tcl +++ /dev/null @@ -1,516 +0,0 @@ -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 diff --git a/www/capi3ref.tcl b/www/capi3ref.tcl deleted file mode 100644 index 631acef35..000000000 --- a/www/capi3ref.tcl +++ /dev/null @@ -1,1882 +0,0 @@ -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>" diff --git a/www/changes.tcl b/www/changes.tcl deleted file mode 100644 index b64a71cf5..000000000 --- a/www/changes.tcl +++ /dev/null @@ -1,1880 +0,0 @@ -# -# 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:} diff --git a/www/common.tcl b/www/common.tcl deleted file mode 100644 index 07129f803..000000000 --- a/www/common.tcl +++ /dev/null @@ -1,90 +0,0 @@ -# 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>} -} diff --git a/www/compile.tcl b/www/compile.tcl deleted file mode 100644 index bdf7d22f7..000000000 --- a/www/compile.tcl +++ /dev/null @@ -1,278 +0,0 @@ -# -# 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 diff --git a/www/conflict.tcl b/www/conflict.tcl deleted file mode 100644 index 2d11639bc..000000000 --- a/www/conflict.tcl +++ /dev/null @@ -1,91 +0,0 @@ -# -# 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 diff --git a/www/copyright-release.html b/www/copyright-release.html deleted file mode 100644 index bc0c764ac..000000000 --- a/www/copyright-release.html +++ /dev/null @@ -1,109 +0,0 @@ -<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> diff --git a/www/copyright-release.pdf b/www/copyright-release.pdf Binary files differdeleted file mode 100644 index 9465d3179..000000000 --- a/www/copyright-release.pdf +++ /dev/null diff --git a/www/copyright.tcl b/www/copyright.tcl deleted file mode 100644 index 74687440b..000000000 --- a/www/copyright.tcl +++ /dev/null @@ -1,126 +0,0 @@ -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 diff --git a/www/datatype3.tcl b/www/datatype3.tcl deleted file mode 100644 index da400aefe..000000000 --- a/www/datatype3.tcl +++ /dev/null @@ -1,440 +0,0 @@ -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 diff --git a/www/datatypes.tcl b/www/datatypes.tcl deleted file mode 100644 index 1b45fb675..000000000 --- a/www/datatypes.tcl +++ /dev/null @@ -1,243 +0,0 @@ -# -# 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 diff --git a/www/different.tcl b/www/different.tcl deleted file mode 100644 index 1858e6fb3..000000000 --- a/www/different.tcl +++ /dev/null @@ -1,224 +0,0 @@ -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 diff --git a/www/direct1b.gif b/www/direct1b.gif Binary files differdeleted file mode 100644 index 8999a84e5..000000000 --- a/www/direct1b.gif +++ /dev/null diff --git a/www/docs.tcl b/www/docs.tcl deleted file mode 100644 index 80fac53b3..000000000 --- a/www/docs.tcl +++ /dev/null @@ -1,159 +0,0 @@ -# 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 diff --git a/www/download.tcl b/www/download.tcl deleted file mode 100644 index b47cd5b2a..000000000 --- a/www/download.tcl +++ /dev/null @@ -1,236 +0,0 @@ -# -# 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 diff --git a/www/dynload.tcl b/www/dynload.tcl deleted file mode 100644 index 3e12b7f9c..000000000 --- a/www/dynload.tcl +++ /dev/null @@ -1,70 +0,0 @@ -# -# 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>} diff --git a/www/faq.tcl b/www/faq.tcl deleted file mode 100644 index dd2c7cc94..000000000 --- a/www/faq.tcl +++ /dev/null @@ -1,463 +0,0 @@ -# -# 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 diff --git a/www/fileformat.tcl b/www/fileformat.tcl deleted file mode 100644 index d143f0839..000000000 --- a/www/fileformat.tcl +++ /dev/null @@ -1,785 +0,0 @@ -# -# 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 diff --git a/www/formatchng.tcl b/www/formatchng.tcl deleted file mode 100644 index 83a2dcfd0..000000000 --- a/www/formatchng.tcl +++ /dev/null @@ -1,285 +0,0 @@ -# -# 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 diff --git a/www/fullscanb.gif b/www/fullscanb.gif Binary files differdeleted file mode 100644 index becb5149b..000000000 --- a/www/fullscanb.gif +++ /dev/null diff --git a/www/index-ex1-x-b.gif b/www/index-ex1-x-b.gif Binary files differdeleted file mode 100644 index 37354ceca..000000000 --- a/www/index-ex1-x-b.gif +++ /dev/null diff --git a/www/index.tcl b/www/index.tcl deleted file mode 100644 index 46945ffdd..000000000 --- a/www/index.tcl +++ /dev/null @@ -1,115 +0,0 @@ -#!/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 $} diff --git a/www/indirect1b1.gif b/www/indirect1b1.gif Binary files differdeleted file mode 100644 index 25285d5e2..000000000 --- a/www/indirect1b1.gif +++ /dev/null diff --git a/www/lang.tcl b/www/lang.tcl deleted file mode 100644 index c721b59db..000000000 --- a/www/lang.tcl +++ /dev/null @@ -1,2207 +0,0 @@ -# -# 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>} diff --git a/www/limits.tcl b/www/limits.tcl deleted file mode 100644 index cf85e380d..000000000 --- a/www/limits.tcl +++ /dev/null @@ -1,318 +0,0 @@ -# -# 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 diff --git a/www/lockingv3.tcl b/www/lockingv3.tcl deleted file mode 100644 index c51cf7980..000000000 --- a/www/lockingv3.tcl +++ /dev/null @@ -1,570 +0,0 @@ -# -# 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 diff --git a/www/mingw.tcl b/www/mingw.tcl deleted file mode 100644 index f1a018663..000000000 --- a/www/mingw.tcl +++ /dev/null @@ -1,160 +0,0 @@ -# -# 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>} diff --git a/www/mkapidoc.tcl b/www/mkapidoc.tcl deleted file mode 100644 index 723f84a5a..000000000 --- a/www/mkapidoc.tcl +++ /dev/null @@ -1,176 +0,0 @@ -#!/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>" -} diff --git a/www/nulls.tcl b/www/nulls.tcl deleted file mode 100644 index 9091389bd..000000000 --- a/www/nulls.tcl +++ /dev/null @@ -1,329 +0,0 @@ -# -# 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 diff --git a/www/oldnews.tcl b/www/oldnews.tcl deleted file mode 100644 index a4cf5abbd..000000000 --- a/www/oldnews.tcl +++ /dev/null @@ -1,509 +0,0 @@ -#!/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 $} diff --git a/www/omitted.tcl b/www/omitted.tcl deleted file mode 100644 index 23241e7d6..000000000 --- a/www/omitted.tcl +++ /dev/null @@ -1,85 +0,0 @@ -# -# 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 diff --git a/www/opcode.tcl b/www/opcode.tcl deleted file mode 100644 index f28534fb5..000000000 --- a/www/opcode.tcl +++ /dev/null @@ -1,243 +0,0 @@ -# -# 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 diff --git a/www/optimizer.tcl b/www/optimizer.tcl deleted file mode 100644 index 5b2897e2b..000000000 --- a/www/optimizer.tcl +++ /dev/null @@ -1,265 +0,0 @@ -# -# 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 diff --git a/www/optimizing.tcl b/www/optimizing.tcl deleted file mode 100644 index 44d2825f5..000000000 --- a/www/optimizing.tcl +++ /dev/null @@ -1,15 +0,0 @@ -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 diff --git a/www/optoverview.tcl b/www/optoverview.tcl deleted file mode 100644 index 15646e332..000000000 --- a/www/optoverview.tcl +++ /dev/null @@ -1,516 +0,0 @@ -# -# 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. -} diff --git a/www/pragma.tcl b/www/pragma.tcl deleted file mode 100644 index d1fcb2107..000000000 --- a/www/pragma.tcl +++ /dev/null @@ -1,635 +0,0 @@ -# -# 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> - -} diff --git a/www/quickstart.tcl b/www/quickstart.tcl deleted file mode 100644 index 8ae3d725f..000000000 --- a/www/quickstart.tcl +++ /dev/null @@ -1,110 +0,0 @@ -# -# 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 $} diff --git a/www/shared.gif b/www/shared.gif Binary files differdeleted file mode 100644 index 9b7be7c4a..000000000 --- a/www/shared.gif +++ /dev/null diff --git a/www/sharedcache.tcl b/www/sharedcache.tcl deleted file mode 100644 index c06c8882a..000000000 --- a/www/sharedcache.tcl +++ /dev/null @@ -1,221 +0,0 @@ -# -# 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 diff --git a/www/speed.tcl b/www/speed.tcl deleted file mode 100644 index b60cfe1ef..000000000 --- a/www/speed.tcl +++ /dev/null @@ -1,495 +0,0 @@ -# -# 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 diff --git a/www/sqlite.tcl b/www/sqlite.tcl deleted file mode 100644 index eed1cd749..000000000 --- a/www/sqlite.tcl +++ /dev/null @@ -1,582 +0,0 @@ -# -# 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 diff --git a/www/support.tcl b/www/support.tcl deleted file mode 100644 index 6dc46934f..000000000 --- a/www/support.tcl +++ /dev/null @@ -1,79 +0,0 @@ -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 diff --git a/www/table-ex1b2.gif b/www/table-ex1b2.gif Binary files differdeleted file mode 100644 index 5f68e0a9d..000000000 --- a/www/table-ex1b2.gif +++ /dev/null diff --git a/www/tclsqlite.tcl b/www/tclsqlite.tcl deleted file mode 100644 index 141cb5e0c..000000000 --- a/www/tclsqlite.tcl +++ /dev/null @@ -1,666 +0,0 @@ -# -# 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 diff --git a/www/vdbe.tcl b/www/vdbe.tcl deleted file mode 100644 index ed0b71205..000000000 --- a/www/vdbe.tcl +++ /dev/null @@ -1,1988 +0,0 @@ -# -# 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 diff --git a/www/version3.tcl b/www/version3.tcl deleted file mode 100644 index 70e500d68..000000000 --- a/www/version3.tcl +++ /dev/null @@ -1,293 +0,0 @@ -#!/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 $} diff --git a/www/whentouse.tcl b/www/whentouse.tcl deleted file mode 100644 index bb4378bae..000000000 --- a/www/whentouse.tcl +++ /dev/null @@ -1,254 +0,0 @@ -# -# 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 |
