aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/sqlite/unix/sqlite-3.5.1/www
diff options
context:
space:
mode:
authordan miller2007-10-21 08:36:32 +0000
committerdan miller2007-10-21 08:36:32 +0000
commit2f8d7092bc2c9609fa98d6888106b96f38b22828 (patch)
treeda6c37579258cc965b52a75aee6135fe44237698 /libraries/sqlite/unix/sqlite-3.5.1/www
parent* Committing new PolicyManager based on an ACL system. (diff)
downloadopensim-SC-2f8d7092bc2c9609fa98d6888106b96f38b22828.zip
opensim-SC-2f8d7092bc2c9609fa98d6888106b96f38b22828.tar.gz
opensim-SC-2f8d7092bc2c9609fa98d6888106b96f38b22828.tar.bz2
opensim-SC-2f8d7092bc2c9609fa98d6888106b96f38b22828.tar.xz
libraries moved to opensim-libs, a new repository
Diffstat (limited to '')
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/34to35.tcl1006
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/arch.fig64
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/arch.gifbin6487 -> 0 bytes
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/arch.pngbin4447 -> 0 bytes
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/arch.tcl221
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/arch2.fig123
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/arch2.gifbin6501 -> 0 bytes
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/arch2b.fig125
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/audit.tcl214
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/autoinc.tcl109
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/c_interface.tcl1116
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/capi3.tcl516
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/changes.tcl1866
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/common.tcl90
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/compile.tcl278
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/conflict.tcl91
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/copyright-release.html109
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/copyright-release.pdfbin2848 -> 0 bytes
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/copyright.tcl126
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/datatype3.tcl440
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/datatypes.tcl243
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/different.tcl224
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/direct1b.gifbin11439 -> 0 bytes
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/docs.tcl159
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/download.tcl236
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/dynload.tcl70
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/faq.tcl463
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/fileformat.tcl785
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/formatchng.tcl285
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/fullscanb.gifbin11946 -> 0 bytes
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/index-ex1-x-b.gifbin23173 -> 0 bytes
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/index.tcl126
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/indirect1b1.gifbin18098 -> 0 bytes
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/lang.tcl2203
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/limits.tcl318
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/lockingv3.tcl570
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/mingw.tcl160
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/mkapidoc.tcl176
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/nulls.tcl329
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/oldnews.tcl485
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/omitted.tcl85
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/opcode.tcl243
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/optimizer.tcl265
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/optimizing.tcl15
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/optoverview.tcl516
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/pragma.tcl635
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/quickstart.tcl110
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/shared.gifbin5787 -> 0 bytes
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/sharedcache.tcl221
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/speed.tcl495
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/sqlite.tcl582
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/support.tcl79
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/table-ex1b2.gifbin10888 -> 0 bytes
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/tclsqlite.tcl666
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/vdbe.tcl1988
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/version3.tcl293
-rw-r--r--libraries/sqlite/unix/sqlite-3.5.1/www/whentouse.tcl254
57 files changed, 0 insertions, 19773 deletions
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/34to35.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/34to35.tcl
deleted file mode 100644
index cb488e7..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/34to35.tcl
+++ /dev/null
@@ -1,1006 +0,0 @@
1#
2# Run this TCL script to generate HTML for the goals.html file.
3#
4set rcsid {$Id: 34to35.tcl,v 1.4 2007/10/01 13:54:11 drh Exp $}
5source common.tcl
6header {SQLite Changes From Version 3.4.2 To 3.5.0}
7
8proc CODE {text} {
9 puts "<blockquote><pre>"
10 puts $text
11 puts "</pre></blockquote>"
12}
13proc SYNTAX {text} {
14 puts "<blockquote><pre>"
15 set t2 [string map {& &amp; < &lt; > &gt;} $text]
16 regsub -all "/(\[^\n/\]+)/" $t2 {</b><i>\1</i><b>} t3
17 puts "<b>$t3</b>"
18 puts "</pre></blockquote>"
19}
20proc IMAGE {name {caption {}}} {
21 puts "<center><img src=\"$name\">"
22 if {$caption!=""} {
23 puts "<br>$caption"
24 }
25 puts "</center>"
26}
27proc PARAGRAPH {text} {
28 # regsub -all "/(\[a-zA-Z0-9\]+)/" $text {<i>\1</i>} t2
29 #regsub -all "\\*(\[^\n*\]+)\\*" $text {<tt><b><big>\1</big></b></tt>} t3
30 regsub -all {\[([^]\n]+)\]} $text {[resolve_link \1]} t3
31 puts "<p>[subst -novar -noback $t3]</p>\n"
32}
33proc resolve_link {args} {
34 set a2 [split $args |]
35 set id [string trim [lindex $a2 0]]
36 if {[lindex $a2 1]==""} {
37 set display [string trim [lindex $a2 0]]
38 } else {
39 set display [string trim [lrange $a2 1 end]]
40 }
41 regsub -all {[^a-zA-Z0-9_]} $id {} id
42 return "<a href=\"capi3ref.html#$id\">$display</a>"
43}
44set level(0) 0
45set level(1) 0
46proc HEADING {n name {tag {}}} {
47 if {$tag!=""} {
48 puts "<a name=\"$tag\">"
49 }
50 global level
51 incr level($n)
52 for {set i [expr {$n+1}]} {$i<10} {incr i} {
53 set level($i) 0
54 }
55 if {$n==0} {
56 set num {}
57 } elseif {$n==1} {
58 set num $level(1).0
59 } else {
60 set num $level(1)
61 for {set i 2} {$i<=$n} {incr i} {
62 append num .$level($i)
63 }
64 }
65 incr n 1
66 puts "<h$n>$num $name</h$n>"
67}
68
69HEADING 0 {Moving From SQLite 3.4.2 to 3.5.0}
70
71PARAGRAPH {
72 SQLite version 3.5.0 introduces a new OS interface layer that
73 is incompatible with all prior versions of SQLite. In addition,
74 a few existing interfaces have been generalized to work across all
75 database connections within a process rather than just all
76 connections within a thread. The purpose of this article
77 is to describe the changes to 3.5.0 in detail so that users
78 of prior versions of SQLite can judge what, if any, effort will
79 be required to upgrade to newer versions.
80}
81
82HEADING 1 {Overview Of Changes}
83
84PARAGRAPH {
85 A quick enumeration of the changes in SQLite version 3.5.0
86 is provide here. Subsequent sections will describe these
87 changes in more detail.
88}
89PARAGRAPH {
90 <ol>
91 <li>The OS interface layer has been completely reworked:
92 <ol type="a">
93 <li>The undocumented <b>sqlite3_os_switch()</b> interface has
94 been removed.</li>
95 <li>The <b>SQLITE_ENABLE_REDEF_IO</b> compile-time flag no longer functions.
96 I/O procedures are now always redefinable.</li>
97 <li>Three new objects are defined for specifying I/O procedures:
98 [sqlite3_vfs], [sqlite3_file], and [sqlite3_io_methods].</li>
99 <li>Three new interfaces are used to create alternative OS interfaces:
100 [sqlite3_vfs_register()], [sqlite3_vfs_unregister()], and
101 [sqlite3_vfs_find()].</li>
102 <li>A new interface has been added to provided additional control over
103 the creation of new database connections: [sqlite3_open_v2()].
104 The legacy interfaces of [sqlite3_open()] and
105 [sqlite3_open16()] continue to be fully supported.</li>
106 </ol></li>
107 <li>The optional shared cache and memory management features that
108 were introduced in version 3.3.0 can now be used across multiple
109 threads within the same process. Formerly, these extensions only
110 applied to database connections operating within a single thread.
111 <ol type="a">
112 <li>The [sqlite3_enable_shared_cache()] interface now applies to all
113 threads within a process, not to just the one thread in which it
114 was run.</li>
115 <li>The [sqlite3_soft_heap_limit()] interface now applies to all threads
116 within a process, not to just the one thread in which it was run.</li>
117 <li>The [sqlite3_release_memory()] interface will now attempt to reduce
118 the memory usages across all database connections in all threads, not
119 just connections in the thread where the interface is called.</li>
120 <li>The [sqlite3_thread_cleanup()] interface has become a no-op.</li>
121 </ol></li>
122 <li>Restrictions on the use of the same database connection by multiple
123 threads have been dropped. It is now safe for
124 multiple threads to use the same database connection at the same
125 time.</li>
126 <li>There is now a compile-time option that allows an application to
127 define alternative malloc()/free() implementations without having
128 to modify any core SQLite code.</li>
129 <li>There is now a compile-time option that allows an application to
130 define alternative mutex implementations without having
131 to modify any core SQLite code.</li>
132 </ol>
133}
134PARAGRAPH {
135 Of these changes, only 1a and 2a through 2c are incompatibilities
136 in any formal sense.
137 But users who have previously made custom modifications to the
138 SQLite source (for example to add a custom OS layer for embedded
139 hardware) might find that these changes have a larger impact.
140 On the other hand, an important goal of these changes is to make
141 it much easier to customize SQLite for use on different operating
142 systems.
143}
144
145HEADING 1 {The OS Interface Layer}
146
147PARAGRAPH {
148 If your system defines a custom OS interface for SQLite or if you
149 were using the undocumented <b>sqlite3_os_switch()</b>
150 interface, then you will need to make modifications in order to
151 upgrade to SQLite version 3.5.0. This may seem painful at first
152 glance. But as you look more closely, you will probably discover
153 that your changes are made smaller and easier to understand and manage
154 by the new SQLite interface. It is likely that your changes will
155 now also work seamlessly with the SQLite amalgamation. You will
156 no longer need to make any changes to the code SQLite source code.
157 All of your changes can be effected by application code and you can
158 link against a standard, unmodified version of the SQLite amalgamation.
159 Furthermore, the OS interface layer, which was formerly undocumented,
160 is now an officially support interface for SQLite. So you have
161 some assurance that this will be a one-time change and that your
162 new backend will continue to work in future versions of SQLite.
163}
164
165HEADING 2 {The Virtual File System Object}
166
167PARAGRAPH {
168 The new OS interface for SQLite is built around an object named
169 [sqlite3_vfs]. The "vfs" standard for "Virtual File System".
170 The sqlite3_vfs object is basically a structure containing pointers
171 to functions that implement the primitive disk I/O operations that
172 SQLite needs to perform in order to read and write databases.
173 In this article, we will often refer a sqlite3_vfs objects as a "VFS".
174}
175
176PARAGRAPH {
177 SQLite is able to use multiple VFSes at the same time. Each
178 individual database connection is associated with just one VFS.
179 But if you have multiple database connections, each connection
180 can be associated with a different VFS.
181}
182
183PARAGRAPH {
184 There is always a default VFS.
185 The legacy interfaces [sqlite3_open()] and [sqlite3_open16()] always
186 use the default VFS.
187 The new interface for creating database connections,
188 [sqlite3_open_v2()], allows you to specify which VFS you want to
189 use by name.
190}
191
192HEADING 3 {Registering New VFS Objects}
193
194PARAGRAPH {
195 Standard builds of SQLite for unix or windows come with a single
196 VFS named "unix" or "win32", as appropriate. This one VFS is also
197 the default. So if you are using the legacy open functions, everything
198 will continue to operate as it has before. The change is that an application
199 now has the flexibility of adding new VFS modules to implement a
200 customized OS layer. The [sqlite3_vfs_register()] API can be used
201 to tell SQLite about one or more application-defined VFS modules:
202}
203
204CODE {
205int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
206}
207
208PARAGRAPH {
209 Applications can call sqlite3_vfs_register at any time, though of course
210 a VFS needs to be registered before it can be used. The first argument
211 is a pointer to a customized VFS object that the application has prepared.
212 The second argument is true to make the new VFS the default VFS so that
213 it will be used by the legacy [sqlite3_open()] and [sqlite3_open16()] APIs.
214 If the new VFS is not the default, then you will probably have to use
215 the new [sqlite3_open_v2()] API to use it. Note, however, that if
216 a new VFS is the only VFS known to SQLite (if SQLite was compiled without
217 its usual default VFS or if the pre-compiled default VFS was removed
218 using [sqlite3_vfs_unregister()]) then the new VFS automatic becomes the
219 default VFS regardless of the makeDflt argument to [sqlite3_vfs_register()].
220}
221
222PARAGRAPH {
223 Standard builds include the default "unix" or "win32" VFSes.
224 But if you use the -DOS_OTHER=1 compile-time option, then SQLite is
225 built without a default VFS. In that case, the application must
226 register at least one VFS prior to calling [sqlite3_open()].
227 This is the approach that embedded applications should use.
228 Rather than modifying the SQLite source to to insert an alternative
229 OS layer as was done in prior releases of SQLite, instead compile
230 an unmodified SQLite source file (preferably the amalgamation)
231 with the -DOS_OTHER=1 option, then invoke [sqlite3_vfs_register()]
232 to define the interface to the underlying filesystem prior to
233 creating any database connections.
234}
235
236HEADING 3 {Additional Control Over VFS Objects}
237
238PARAGRAPH {
239 The [sqlite3_vfs_unregister()] API is used to remove an existing
240 VFS from the system.
241}
242
243CODE {
244int sqlite3_vfs_unregister(sqlite3_vfs*);
245}
246
247PARAGRAPH {
248 The [sqlite3_vfs_find()] API is used to locate a particular VFS
249 by name. Its prototype is as follows:
250}
251
252CODE {
253sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
254}
255
256PARAGRAPH {
257 The argument is the symbolic name for the desired VFS. If the
258 argument is a NULL pointer, then the default VFS is returned.
259 The function returns a pointer to the [sqlite3_vfs] object that
260 implements the VFS. Or it returns a NULL pointer if no object
261 could be found that matched the search criteria.
262}
263
264HEADING 3 {Modifications Of Existing VFSes}
265
266PARAGRAPH {
267 Once a VFS has been registered, it should never be modified. If
268 a change in behavior is required, a new VFS should be registered.
269 The application could, perhaps, use [sqlite3_vfs_find()] to locate
270 the old VFS, make a copy of the old VFS into a new [sqlite3_vfs]
271 object, make the desired modifications to the new VFS, unregister
272 the old VFS, the register the new VFS in its place. Existing
273 database connections would continue to use the old VFS even after
274 it is unregistered, but new database connections would use the
275 new VFS.
276}
277
278HEADING 3 {The VFS Object}
279
280PARAGRAPH {
281 A VFS object is an instance of the following structure:
282}
283
284CODE {
285typedef struct sqlite3_vfs sqlite3_vfs;
286struct sqlite3_vfs {
287 int iVersion; /* Structure version number */
288 int szOsFile; /* Size of subclassed sqlite3_file */
289 int mxPathname; /* Maximum file pathname length */
290 sqlite3_vfs *pNext; /* Next registered VFS */
291 const char *zName; /* Name of this virtual file system */
292 void *pAppData; /* Pointer to application-specific data */
293 int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
294 int flags, int *pOutFlags);
295 int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
296 int (*xAccess)(sqlite3_vfs*, const char *zName, int flags);
297 int (*xGetTempName)(sqlite3_vfs*, char *zOut);
298 int (*xFullPathname)(sqlite3_vfs*, const char *zName, char *zOut);
299 void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
300 void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
301 void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol);
302 void (*xDlClose)(sqlite3_vfs*, void*);
303 int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
304 int (*xSleep)(sqlite3_vfs*, int microseconds);
305 int (*xCurrentTime)(sqlite3_vfs*, double*);
306 /* New fields may be appended in figure versions. The iVersion
307 ** value will increment whenever this happens. */
308};
309}
310
311PARAGRAPH {
312 To create a new VFS, an application fills in an instance of this
313 structure with appropriate values and then calls [sqlite3_vfs_register()].
314}
315
316PARAGRAPH {
317 The iVersion field of [sqlite3_vfs] should be 1 for SQLite version 3.5.0.
318 This number may increase in future versions of SQLite if we have to
319 modify the VFS object in some way. We hope that this never happens,
320 but the provision is made in case it does.
321}
322
323PARAGRAPH {
324 The szOsFile field is the size in bytes of the structure that defines
325 an open file: the [sqlite3_file] object. This object will be described
326 more fully below. The point here is that each VFS implementation can
327 define its own [sqlite3_file] object containing whatever information
328 the VFS implementation needs to store about an open file. SQLite needs
329 to know how big this object is, however, in order to preallocate enough
330 space to hold it.
331}
332
333PARAGRAPH {
334 The mxPathname field is the maximum length of a file pathname that
335 this VFS can use. SQLite sometimes has to preallocate buffers of
336 this size, so it should be as small as reasonably possible. Some
337 filesystems permit huge pathnames, but in practice pathnames rarely
338 extend beyond 100 bytes or so. You do not have to put the longest
339 pathname that the underlying filesystem can handle here. You only
340 have to put the longest pathname that you want SQLite to be able to
341 handle. A few hundred is a good value in most cases.
342}
343
344PARAGRAPH {
345 The pNext field is used internally by SQLite. Specifically, SQLite
346 uses this field to form a linked list of registered VFSes.
347}
348
349PARAGRAPH {
350 The zName field is the symbolic name of the VFS. This is the name
351 that the [sqlite3_vfs_find()] compares against when it is looking for
352 a VFS.
353}
354
355PARAGRAPH {
356 The pAppData pointer is unused by the SQLite core. The pointer is
357 available to store auxiliary information that a VFS information might
358 want to carry around.
359}
360
361PARAGRAPH {
362 The remaining fields of the [sqlite3_vfs] object all store pointer
363 to functions that implement primitive operations. We call these
364 "methods". The first methods, xOpen, is used to open files on
365 the underlying storage media. The result is an [sqlite3_file]
366 object. There are additional methods, defined by the [sqlite3_file]
367 object itself that are used to read and write and close the file.
368 The additional methods are detailed below. The filename is in UTF-8.
369 SQLite will guarantee that the zFilename string passed to
370 xOpen() is a full pathname as generated by xFullPathname() and
371 that the string will be valid and unchanged until xClose() is
372 called. So the [sqlite3_file] can store a pointer to the
373 filename if it needs to remember the filename for some reason.
374 The flags argument to xOpen() is a copy of the flags argument
375 to sqlite3_open_v2(). If sqlite3_open() or sqlite3_open16()
376 is used, then flags is [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].
377 If xOpen() opens a file read-only then it sets *pOutFlags to
378 include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be
379 set.
380 SQLite will also add one of the following flags to the xOpen()
381 call, depending on the object being opened:
382 <ul>
383 <li> [SQLITE_OPEN_MAIN_DB]
384 <li> [SQLITE_OPEN_MAIN_JOURNAL]
385 <li> [SQLITE_OPEN_TEMP_DB]
386 <li> [SQLITE_OPEN_TEMP_JOURNAL]
387 <li> [SQLITE_OPEN_TRANSIENT_DB]
388 <li> [SQLITE_OPEN_SUBJOURNAL]
389 <li> [SQLITE_OPEN_MASTER_JOURNAL]
390 </ul>
391 The file I/O implementation can use the object type flags to
392 changes the way it deals with files. For example, an application
393 that does not care about crash recovery or rollback, might make
394 the open of a journal file a no-op. Writes to this journal are
395 also a no-op. Any attempt to read the journal returns [SQLITE_IOERR].
396 Or the implementation might recognize the a database file will
397 be doing page-aligned sector reads and writes in a random order
398 and set up its I/O subsystem accordingly.
399 SQLite might also add one of the following flags to the xOpen
400 method:
401 <ul>
402 <li> [SQLITE_OPEN_DELETEONCLOSE]
403 <li> [SQLITE_OPEN_EXCLUSIVE]
404 </ul>
405 The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
406 deleted when it is closed. This will always be set for TEMP
407 databases and journals and for subjournals. The
408 [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
409 for exclusive access. This flag is set for all files except
410 for the main database file.
411 The [sqlite3_file] structure passed as the third argument to
412 xOpen is allocated by the caller. xOpen just fills it in. The
413 caller allocates a minimum of szOsFile bytes for the [sqlite3_file]
414 structure.
415}
416
417PARAGRAPH {
418 The differences between an [SQLITE_OPEN_TEMP_DB] database and an
419 [SQLITE_OPEN_TRANSIENT_DB] database is this: The [SQLITE_OPEN_TEMP_DB]
420 is used for explicitly declared and named TEMP tables (using the
421 CREATE TEMP TABLE syntax) or for named tables in a temporary database
422 that is created by opening a database with a filename that is an empty
423 string. An [SQLITE_OPEN_TRANSIENT_DB] holds an database table that
424 SQLite creates automatically in order to evaluate a subquery or
425 ORDER BY or GROUP BY clause. Both TEMP_DB and TRANSIENT_DB databases
426 are private and are deleted automatically. TEMP_DB databases last
427 for the duration of the database connection. TRANSIENT_DB databases
428 last only for the duration of a single SQL statement.
429}
430
431PARAGRAPH {
432 The xDelete method is used delete a file. The name of the file is
433 given in the second parameter. The filename will be in UTF-8.
434 The VFS must convert the filename into whatever character representation
435 the underlying operating system expects. If the syncDir parameter is
436 true, then the xDelete method should not return until the change
437 to the directory contents for the directory containing the
438 deleted file have been synced to disk in order to insure that the
439 file does not "reappear" if a power failure occurs soon after.
440}
441
442PARAGRAPH {
443 The xAccess method is used to check for access permissions on a file.
444 The filename will be UTF-8 encoded. The flags argument will be
445 [SQLITE_ACCESS_EXISTS] to check for the existence of the file,
446 [SQLITE_ACCESS_READWRITE] to check to see if the file is both readable
447 and writable, or [SQLITE_ACCESS_READ] to check to see if the file is
448 at least readable. The "file" named by the second parameter might
449 be a directory or folder name.
450}
451
452PARAGRAPH {
453 The xGetTempName method computes the name of a temporary file that
454 SQLite can use. The name should be written into the buffer given
455 by the second parameter. SQLite will size that buffer to hold
456 at least mxPathname bytes. The generated filename should be in UTF-8.
457 To avoid security problems, the generated temporary filename should
458 contain enough randomness to prevent an attacker from guessing the
459 temporary filename in advance.
460}
461
462PARAGRAPH {
463 The xFullPathname method is used to convert a relative pathname
464 into a full pathname. The resulting full pathname is written into
465 the buffer provided by the third parameter. SQLite will size the
466 output buffer to at least mxPathname bytes. Both the input and
467 output names should be in UTF-8.
468}
469
470PARAGRAPH {
471 The xDlOpen, xDlError, xDlSym, and xDlClose methods are all used for
472 accessing shared libraries at run-time. These methods may be omitted
473 (and their pointers set to zero) if the library is compiled with
474 SQLITE_OMIT_LOAD_EXTENSION or if the [sqlite3_enable_load_extension()]
475 interface is never used to enable dynamic extension loading. The
476 xDlOpen method opens a shared library or DLL and returns a pointer to
477 a handle. NULL is returned if the open fails. If the open fails,
478 the xDlError method can be used to obtain a text error message.
479 The message is written into the zErrMsg buffer of the third parameter
480 which is at least nByte bytes in length. The xDlSym returns a pointer
481 to a symbol in the shared library. The name of the symbol is given
482 by the second parameter. UTF-8 encoding is assumed. If the symbol
483 is not found a NULL pointer is returned. The xDlClose routine closes
484 the shared library.
485}
486
487PARAGRAPH {
488 The xRandomness method is used exactly once to initialize the
489 pseudo-random number generator (PRNG) inside of SQLite. Only
490 the xRandomness method on the default VFS is used. The xRandomness
491 methods on other VFSes are never accessed by SQLite.
492 The xRandomness routine requests that nByte bytes of randomness
493 be written into zOut. The routine returns the actual number of
494 bytes of randomness obtained. The quality of the randomness so obtained
495 will determine the quality of the randomness generated by built-in
496 SQLite functions such as random() and randomblob(). SQLite also
497 uses its PRNG to generate temporary file names.. On some platforms
498 (ex: windows) SQLite assumes that temporary file names are unique
499 without actually testing for collisions, so it is important to have
500 good-quality randomness even if the random() and randomblob()
501 functions are never used.
502}
503
504PARAGRAPH {
505 The xSleep method is used to suspend the calling thread for at
506 least the number of microseconds given. This method is used to
507 implement the [sqlite3_sleep()] and [sqlite3_busy_timeout()] APIs.
508 In the case of [sqlite3_sleep()] the xSleep method of the default
509 VFS is always used. If the underlying system does not have a
510 microsecond resolution sleep capability, then the sleep time should
511 be rounded up. xSleep returns this rounded-up value.
512}
513
514PARAGRAPH {
515 The xCurrentTime method finds the current time and date and writes
516 the result as double-precision floating point value into pointer
517 provided by the second parameter. The time and date is in
518 coordinated universal time (UTC) and is a fractional julian day number.
519}
520
521HEADING 3 {The Open File Object}
522
523PARAGRAPH {
524 The result of opening a file is an instance of an [sqlite3_file] object.
525 The [sqlite3_file] object is an abstract base class defined as follows:
526}
527
528CODE {
529typedef struct sqlite3_file sqlite3_file;
530struct sqlite3_file {
531 const struct sqlite3_io_methods *pMethods;
532};
533}
534
535PARAGRAPH {
536 Each VFS implementation will subclass the [sqlite3_file] by adding
537 additional fields at the end to hold whatever information the VFS
538 needs to know about an open file. It does not matter what information
539 is stored as long as the total size of the structure does not exceed
540 the szOsFile value recorded in the [sqlite3_vfs] object.
541}
542
543PARAGRAPH {
544 The [sqlite3_io_methods] object is a structure that contains pointers
545 to methods for reading, writing, and otherwise dealing with files.
546 This object is defined as follows:
547}
548
549CODE {
550typedef struct sqlite3_io_methods sqlite3_io_methods;
551struct sqlite3_io_methods {
552 int iVersion;
553 int (*xClose)(sqlite3_file*);
554 int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
555 int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
556 int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
557 int (*xSync)(sqlite3_file*, int flags);
558 int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
559 int (*xLock)(sqlite3_file*, int);
560 int (*xUnlock)(sqlite3_file*, int);
561 int (*xCheckReservedLock)(sqlite3_file*);
562 int (*xFileControl)(sqlite3_file*, int op, void *pArg);
563 int (*xSectorSize)(sqlite3_file*);
564 int (*xDeviceCharacteristics)(sqlite3_file*);
565 /* Additional methods may be added in future releases */
566};
567}
568
569PARAGRAPH {
570 The iVersion field of [sqlite3_io_methods] is provided as insurance
571 against future enhancements. The iVersion value should always be
572 1 for SQLite version 3.5.
573}
574
575PARAGRAPH {
576 The xClose method closes the file. The space for the [sqlite3_file]
577 structure is deallocated by the caller. But if the [sqlite3_file]
578 contains pointers to other allocated memory or resources, those
579 allocations should be released by the xClose method.
580}
581
582PARAGRAPH {
583 The xRead method reads iAmt bytes from the file beginning at a byte
584 offset to iOfst. The data read is stored in the pointer of the
585 second parameter. xRead returns the [SQLITE_OK] on success,
586 [SQLITE_IOERR_SHORT_READ] if it was not able to read the full number
587 of bytes because it reached end-of-file, or [SQLITE_IOERR_READ] for
588 any other error.
589}
590
591PARAGRAPH {
592 The xWrite method writes iAmt bytes of data from the second parameter
593 into the file beginning at an offset of iOfst bytes. If the size of
594 the file is less than iOfst bytes prior to the write, then xWrite should
595 ensure that the file is extended with zeros up to iOfst bytes prior
596 to beginning its write. xWrite continues to extends the file as
597 necessary so that the size of the file is at least iAmt+iOfst bytes
598 at the conclusion of the xWrite call. The xWrite method returns
599 [SQLITE_OK] on success. If the write cannot complete because the
600 underlying storage medium is full, then [SQLITE_FULL] is returned.
601 [SQLITE_IOERR_WRITE] should be returned for any other error.
602}
603
604PARAGRAPH {
605 The xTruncate method truncates a file to be nByte bytes in length.
606 If the file is already nByte bytes or less in length then this
607 method is a no-op. The xTruncate method returns [SQLITE_OK] on
608 success and [SQLITE_IOERR_TRUNCATE] if anything goes wrong.
609}
610
611PARAGRAPH {
612 The xSync method is used to force previously written data out of
613 operating system cache and into non-volatile memory. The second
614 parameter is usually [SQLITE_SYNC_NORMAL]. If the second parameter
615 is [SQLITE_SYNC_FULL] then the xSync method should make sure that
616 data has also been flushed through the disk controllers cache.
617 The [SQLITE_SYNC_FULL] parameter is the equivalent of the F_FULLSYNC
618 ioctl() on Mac OS X. The xSync method returns
619 [SQLITE_OK] on success and [SQLITE_IOERR_FSYNC] if anything goes wrong.
620}
621
622PARAGRAPH {
623 The xFileSize() method determines the current size of the file
624 in bytes and writes that value into *pSize. It returns [SQLITE_OK]
625 on success and [SQLITE_IOERR_FSTAT] if something goes wrong.
626}
627
628PARAGRAPH {
629 The xLock and xUnlock methods are used to set and clear file locks.
630 SQLite supports five levels of file locks, in order:
631 <ul>
632 <li> [SQLITE_LOCK_NONE]
633 <li> [SQLITE_LOCK_SHARED]
634 <li> [SQLITE_LOCK_RESERVED]
635 <li> [SQLITE_LOCK_PENDING]
636 <li> [SQLITE_LOCK_EXCLUSIVE]
637 </ul>
638 The underlying implementation can support some subset of these locking
639 levels as long as it meets the other requirements of this paragraph.
640 The locking level is specified as the second argument to both xLock
641 and xUnlock. The xLock method increases the locking level to the
642 specified locking level or higher. The xUnlock method decreases the
643 locking level to no lower than the level specified.
644 [SQLITE_LOCK_NONE] means that the file is unlocked. [SQLITE_LOCK_SHARED]
645 gives permission to read the file. Multiple database connections can
646 hold [SQLITE_LOCK_SHARED] at the same time.
647 [SQLITE_LOCK_RESERVED] is like [SQLITE_LOCK_SHARED] in that its is permission
648 to read the file. But only a single connection can hold a reserved lock
649 at any point in time. The [SQLITE_LOCK_PENDING] is also permission to
650 read the file. Other connections can continue to read the file as well,
651 but no other connection is allowed to escalate a lock from none to shared.
652 [SQLITE_LOCK_EXCLUSIVE] is permission to write on the file. Only a single
653 connection can hold an exclusive lock and no other connection can hold
654 any lock (other than "none") while one connection is hold an exclusive
655 lock. The xLock returns [SQLITE_OK] on success, [SQLITE_BUSY] if it
656 is unable to obtain the lock, or [SQLITE_IOERR_RDLOCK] if something else
657 goes wrong. The xUnlock method returns [SQLITE_OK] on success and
658 [SQLITE_IOERR_UNLOCK] for problems.
659}
660
661PARAGRAPH {
662 The xCheckReservedLock method checks to see if another connection or
663 another process is currently holding a reserved, pending, or exclusive
664 lock on the file. It returns true or false.
665}
666
667PARAGRAPH {
668 The xFileControl() method is a generic interface that allows custom
669 VFS implementations to directly control an open file using the
670 (new and experimental)
671 [sqlite3_file_control()] interface. The second "op" argument
672 is an integer opcode. The third
673 argument is a generic pointer which is intended to be a pointer
674 to a structure that may contain arguments or space in which to
675 write return values. Potential uses for xFileControl() might be
676 functions to enable blocking locks with timeouts, to change the
677 locking strategy (for example to use dot-file locks), to inquire
678 about the status of a lock, or to break stale locks. The SQLite
679 core reserves opcodes less than 100 for its own use.
680 A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
681 Applications that define a custom xFileControl method should use opcodes
682 greater than 100 to avoid conflicts.
683}
684
685PARAGRAPH {
686 The xSectorSize returns the "sector size" of the underlying
687 non-volatile media. A "sector" is defined as the smallest unit of
688 storage that can be written without disturbing adjacent storage.
689 On a disk drive the "sector size" has until recently been 512 bytes,
690 though there is a push to increase this value to 4KiB. SQLite needs
691 to know the sector size so that it can write a full sector at a
692 time, and thus avoid corrupting adjacent storage space if a power
693 lose occurs in the middle of a write.
694}
695
696PARAGRAPH {
697 The xDeviceCharacteristics method returns an integer bit vector that
698 defines any special properties that the underlying storage medium might
699 have that SQLite can use to increase performance. The allowed return
700 is the bit-wise OR of the following values:
701 <ul>
702 <li> [SQLITE_IOCAP_ATOMIC]
703 <li> [SQLITE_IOCAP_ATOMIC512]
704 <li> [SQLITE_IOCAP_ATOMIC1K]
705 <li> [SQLITE_IOCAP_ATOMIC2K]
706 <li> [SQLITE_IOCAP_ATOMIC4K]
707 <li> [SQLITE_IOCAP_ATOMIC8K]
708 <li> [SQLITE_IOCAP_ATOMIC16K]
709 <li> [SQLITE_IOCAP_ATOMIC32K]
710 <li> [SQLITE_IOCAP_ATOMIC64K]
711 <li> [SQLITE_IOCAP_SAFE_APPEND]
712 <li> [SQLITE_IOCAP_SEQUENTIAL]
713 </ul>
714 The [SQLITE_IOCAP_ATOMIC] bit means that all writes to this device are
715 atomic in the sense that either the entire write occurs or none of it
716 occurs. The other
717 [SQLITE_IOCAP_ATOMIC | SQLITE_IOCAP_ATOMIC<i>nnn</i>] values indicate that
718 writes of aligned blocks of the indicated size are atomic.
719 [SQLITE_IOCAP_SAFE_APPEND] means that when extending a file with new
720 data, the new data is written first and then the file size is updated.
721 So if a power failure occurs, there is no chance that the file might have
722 been extended with randomness. The [SQLITE_IOCAP_SEQUENTIAL] bit means
723 that all writes occur in the order that they are issued and are not
724 reordered by the underlying file system.
725}
726
727HEADING 3 {Checklist For Constructing A New VFS}
728
729PARAGRAPH {
730 The preceding paragraphs contain a lot of information.
731 To ease the task of constructing
732 a new VFS for SQLite we offer the following implementation checklist:
733}
734
735PARAGRAPH {
736 <ol>
737 <li> Define an appropriate subclass of the [sqlite3_file] object.
738 <li> Implement the methods required by the [sqlite3_io_methods] object.
739 <li> Create a static and
740 constant [sqlite3_io_methods] object containing pointers
741 to the methods from the previous step.
742 <li> Implement the xOpen method that opens a file and populates an
743 [sqlite3_file] object, including setting pMethods to
744 point to the [sqlite3_io_methods] object from the previous step.
745 <li> Implement the other methods required by [sqlite3_vfs].
746 <li> Define a static (but not constant) [sqlite3_vfs] structure that
747 contains pointers to the xOpen method and the other methods and
748 which contains the appropriate values for iVersion, szOsFile,
749 mxPathname, zName, and pAppData.
750 <li> Implement a procedure that calls [sqlite3_vfs_register()] and
751 passes it a pointer to the [sqlite3_vfs] structure from the previous
752 step. This procedure is probably the only exported symbol in the
753 source file that implements your VFS.
754 </ol>
755}
756
757PARAGRAPH {
758 Within your application, call the procedure implemented in the last
759 step above as part of your initialization process before any
760 database connections are opened.
761}
762
763HEADING 1 {The Memory Allocation Subsystem}
764
765PARAGRAPH {
766 Beginning with version 3.5, SQLite obtains all of the heap memory it
767 needs using the routines [sqlite3_malloc()], [sqlite3_free()], and
768 [sqlite3_realloc()]. These routines have existed in prior versions
769 of SQLite, but SQLite has previously bypassed these routines and used
770 its own memory allocator. This all changes in version 3.5.0.
771}
772
773PARAGRAPH {
774 The SQLite source tree actually contains multiple versions of the
775 memory allocator. The default high-speed version found in the
776 "mem1.c" source file is used for most builds. But if the SQLITE_MEMDEBUG
777 flag is enabled, a separate memory allocator the "mem2.c" source file
778 is used instead. The mem2.c allocator implements lots of hooks to
779 do error checking and to simulate memory allocation failures for testing
780 purposes. Both of these allocators use the malloc()/free() implementation
781 in the standard C library.
782}
783
784PARAGRAPH {
785 Applications are not required to use either of these standard memory
786 allocators. If SQLite is compiled with SQLITE_OMIT_MEMORY_ALLOCATION
787 then no implementation for the [sqlite3_malloc()], [sqlite3_realloc()],
788 and [sqlite3_free()] functions is provided. Instead, the application
789 that links against SQLite must provide its own implementation of these
790 functions. The application provided memory allocator is not required
791 to use the malloc()/free() implementation in the standard C library.
792 An embedded application might provide an alternative memory allocator
793 that uses memory for a fixed memory pool set aside for the exclusive
794 use of SQLite, for example.
795}
796
797PARAGRAPH {
798 Applications that implement their own memory allocator must provide
799 implementation for the usual three allocation functions
800 [sqlite3_malloc()], [sqlite3_realloc()], and [sqlite3_free()].
801 And they must also implement a fourth function:
802}
803
804CODE {
805int sqlite3_memory_alarm(
806 void(*xCallback)(void *pArg, sqlite3_int64 used, int N),
807 void *pArg,
808 sqlite3_int64 iThreshold
809);
810}
811
812PARAGRAPH {
813 The [sqlite3_memory_alarm] routine is used to register
814 a callback on memory allocation events.
815 This routine registers or clears a callbacks that fires when
816 the amount of memory allocated exceeds iThreshold. Only
817 a single callback can be registered at a time. Each call
818 to [sqlite3_memory_alarm()] overwrites the previous callback.
819 The callback is disabled by setting xCallback to a NULL
820 pointer.
821}
822
823PARAGRAPH {
824 The parameters to the callback are the pArg value, the
825 amount of memory currently in use, and the size of the
826 allocation that provoked the callback. The callback will
827 presumably invoke [sqlite3_free()] to free up memory space.
828 The callback may invoke [sqlite3_malloc()] or [sqlite3_realloc()]
829 but if it does, no additional callbacks will be invoked by
830 the recursive calls.
831}
832
833PARAGRAPH {
834 The [sqlite3_soft_heap_limit()] interface works by registering
835 a memory alarm at the soft heap limit and invoking
836 [sqlite3_release_memory()] in the alarm callback. Application
837 programs should not attempt to use the [sqlite3_memory_alarm()]
838 interface because doing so will interfere with the
839 [sqlite3_soft_heap_limit()] module. This interface is exposed
840 only so that applications can provide their own
841 alternative implementation when the SQLite core is
842 compiled with SQLITE_OMIT_MEMORY_ALLOCATION.
843}
844
845PARAGRAPH {
846 The built-in memory allocators in SQLite also provide the following
847 additional interfaces:
848}
849
850CODE {
851sqlite3_int64 sqlite3_memory_used(void);
852sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
853}
854
855PARAGRAPH {
856 These interfaces can be used by an application to monitor how
857 much memory SQLite is using. The [sqlite3_memory_used()] routine
858 returns the number of bytes of memory currently in use and the
859 [sqlite3_memory_highwater()] returns the maximum instantaneous
860 memory usage. Neither routine includes the overhead associated
861 with the memory allocator. These routines are provided for use
862 by the application. SQLite never invokes them itself. So if
863 the application is providing its own memory allocation subsystem,
864 it can omit these interfaces if desired.
865}
866
867HEADING 1 {The Mutex Subsystem}
868
869PARAGRAPH {
870 SQLite has always been threadsafe in the sense that it is safe to
871 use different SQLite database connections in different threads at the
872 same time. The constraint was that the same database connection
873 could not be used in two separate threads at once. SQLite version 3.5.0
874 relaxes this constraint.
875}
876
877PARAGRAPH {
878 In order to allow multiple threads to use the same database connection
879 at the same time, SQLite must make extensive use of mutexes. And for
880 this reason a new mutex subsystem as been added. The mutex subsystem
881 as the following interface:
882}
883
884CODE {
885sqlite3_mutex *sqlite3_mutex_alloc(int);
886void sqlite3_mutex_free(sqlite3_mutex*);
887void sqlite3_mutex_enter(sqlite3_mutex*);
888int sqlite3_mutex_try(sqlite3_mutex*);
889void sqlite3_mutex_leave(sqlite3_mutex*);
890}
891
892PARAGRAPH {
893 Though these routines exist for the use of the SQLite core,
894 application code is free to use these routines as well, if desired.
895 A mutex is an [sqlite3_mutex] object. The [sqlite3_mutex_alloc()]
896 routine allocates a new mutex object and returns a pointer to it.
897 The argument to [sqlite3_mutex_alloc()] should be
898 [SQLITE_MUTEX_FAST] or [SQLITE_MUTEX_RECURSIVE] for non-recursive
899 and recursive mutexes, respectively. If the underlying system does
900 not provide non-recursive mutexes, then a recursive mutex can be
901 substituted in that case. The argument to [sqlite3_mutex_alloc()]
902 can also be a constant designating one of several static mutexes:
903 <ul>
904 <li> [SQLITE_MUTEX_STATIC_MASTER]
905 <li> [SQLITE_MUTEX_STATIC_MEM]
906 <li> [SQLITE_MUTEX_STATIC_MEM2]
907 <li> [SQLITE_MUTEX_STATIC_PRNG]
908 <li> [SQLITE_MUTEX_STATIC_LRU]
909 </ul>
910 These static mutexes are reserved for use internally by SQLite
911 and should not be used by the application. The static mutexes
912 are all non-recursive.
913}
914
915PARAGRAPH {
916 The [sqlite3_mutex_free()] routine should be used to deallocate
917 a non-static mutex. If a static mutex is passed to this routine
918 then the behavior is undefined.
919}
920
921PARAGRAPH {
922 The [sqlite3_mutex_enter()] attempts to enter the mutex and blocks
923 if another threads is already there. [sqlite3_mutex_try()] attempts
924 to enter and returns [SQLITE_OK] on success or [SQLITE_BUSY] if another
925 thread is already there. [sqlite3_mutex_leave()] exits a mutex.
926 The mutex is held until the number of exits matches the number of
927 entrances. If [sqlite3_mutex_leave()] is called on a mutex that
928 the thread is not currently holding, then the behavior is undefined.
929 If any routine is called for a deallocated mutex, then the behavior
930 is undefined.
931}
932
933PARAGRAPH {
934 The SQLite source code provides multiple implementations of these
935 APIs, suitable for varying environments. If SQLite is compiled with
936 the SQLITE_THREADSAFE=0 flag then a no-op mutex implementation that
937 is fast but does no real mutual exclusion is provided. That
938 implementation is suitable for use in single-threaded applications
939 or applications that only use SQLite in a single thread. Other
940 real mutex implementations are provided based on the underlying
941 operating system.
942}
943
944PARAGRAPH {
945 Embedded applications may wish to provide their own mutex implementation.
946 If SQLite is compiled with the -DSQLITE_MUTEX_APPDEF=1 compile-time flag
947 then the SQLite core provides no mutex subsystem and a mutex subsystem
948 that matches the interface described above must be provided by the
949 application that links against SQLite.
950}
951
952HEADING 1 {Other Interface Changes}
953
954PARAGRAPH {
955 Version 3.5.0 of SQLite changes the behavior of a few APIs in ways
956 that are technically incompatible. However, these APIs are seldom
957 used and even when they are used it is difficult to imagine a
958 scenario where the change might break something. The changes
959 actually makes these interface much more useful and powerful.
960}
961
962PARAGRAPH {
963 Prior to version 3.5.0, the [sqlite3_enable_shared_cache()] API
964 would enable and disable the shared cache feature for all connections
965 within a single thread - the same thread from which the
966 sqlite3_enable_shared_cache() routine was called. Database connections
967 that used the shared cache were restricted to running in the same
968 thread in which they were opened. Beginning with version 3.5.0,
969 the sqlite3_enable_shared_cache() applies to all database connections
970 in all threads within the process. Now database connections running
971 in separate threads can share a cache. And database connections that
972 use shared cache can migrate from one thread to another.
973}
974
975PARAGRAPH {
976 Prior to version 3.5.0 the [sqlite3_soft_heap_limit()] set an upper
977 bound on heap memory usage for all database connections within a
978 single thread. Each thread could have its own heap limit. Beginning
979 in version 3.5.0, there is a single heap limit for the entire process.
980 This seems more restrictive (one limit as opposed to many) but in
981 practice it is what most users want.
982}
983
984PARAGRAPH {
985 Prior to version 3.5.0 the [sqlite3_release_memory()] function would
986 try to reclaim memory from all database connections in the same thread
987 as the sqlite3_release_memory() call. Beginning with version 3.5.0,
988 the sqlite3_release_memory() function will attempt to reclaim memory
989 from all database connections in all threads.
990}
991
992HEADING 1 {Summary}
993
994PARAGRAPH {
995 The transition from SQLite version 3.4.2 to 3.5.0 is a major change.
996 Every source code file in the SQLite core had to be modified, some
997 extensively. And the change introduced some minor incompatibilities
998 in the C interface. But we feel that the benefits of the transition
999 from 3.4.2 to 3.5.0 far outweigh the pain of porting. The new
1000 VFS layer is now well-defined and stable and should simplify future
1001 customizations. The VFS layer, and the separable memory allocator
1002 and mutex subsystems allow a standard SQLite source code amalgamation
1003 to be used in an embedded project without change, greatly simplifying
1004 configuration management. And the resulting system is much more
1005 tolerant of highly threaded designs.
1006}
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/arch.fig b/libraries/sqlite/unix/sqlite-3.5.1/www/arch.fig
deleted file mode 100644
index d127a27..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/arch.fig
+++ /dev/null
@@ -1,64 +0,0 @@
1#FIG 3.2
2Portrait
3Center
4Inches
5Letter
6100.00
7Single
8-2
91200 2
102 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
11 1 1 3.00 75.00 135.00
12 3675 8550 3675 9075
132 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
14 1 1 3.00 75.00 135.00
15 3675 7200 3675 7725
162 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
17 1 1 3.00 75.00 135.00
18 3675 5775 3675 6300
192 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
20 1 1 3.00 75.00 135.00
21 3675 3975 3675 4500
222 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
23 1 1 3.00 75.00 135.00
24 3675 2625 3675 3150
252 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
26 1 1 3.00 75.00 135.00
27 3675 1275 3675 1800
282 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
29 1 1 3.00 75.00 135.00
30 3675 9900 3675 10425
312 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
32 2550 10425 4875 10425 4875 11250 2550 11250 2550 10425
332 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
34 2550 9075 4875 9075 4875 9900 2550 9900 2550 9075
352 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
36 2550 7725 4875 7725 4875 8550 2550 8550 2550 7725
372 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
38 2550 6300 4875 6300 4875 7200 2550 7200 2550 6300
392 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
40 2550 4500 4875 4500 4875 5775 2550 5775 2550 4500
412 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
42 2550 3150 4875 3150 4875 3975 2550 3975 2550 3150
432 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
44 2550 1800 4875 1800 4875 2625 2550 2625 2550 1800
452 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
46 2550 450 4875 450 4875 1275 2550 1275 2550 450
474 1 0 100 0 0 20 0.0000 4 195 1020 3675 750 Interface\001
484 1 0 100 0 0 14 0.0000 4 195 2040 3675 1125 main.c table.c tclsqlite.c\001
494 1 0 100 0 0 20 0.0000 4 195 1920 3675 6675 Virtual Machine\001
504 1 0 100 0 0 14 0.0000 4 150 570 3675 7050 vdbe.c\001
514 1 0 100 0 0 20 0.0000 4 195 1830 3675 4875 Code Generator\001
524 1 0 100 0 0 14 0.0000 4 195 1860 3675 5175 build.c delete.c expr.c\001
534 1 0 100 0 0 14 0.0000 4 195 2115 3675 5400 insert.c select.c update.c\001
544 1 0 100 0 0 14 0.0000 4 150 705 3675 5625 where.c\001
554 1 0 100 0 0 20 0.0000 4 195 735 3675 3450 Parser\001
564 1 0 100 0 0 20 0.0000 4 195 1140 3675 2100 Tokenizer\001
574 1 0 100 0 0 14 0.0000 4 150 870 3675 2475 tokenize.c\001
584 1 0 100 0 0 20 0.0000 4 255 1350 3675 9375 Page Cache\001
594 1 0 100 0 0 14 0.0000 4 150 630 3675 3825 parse.y\001
604 1 0 100 0 0 14 0.0000 4 150 600 3675 8400 btree.c\001
614 1 0 100 0 0 14 0.0000 4 150 645 3675 9750 pager.c\001
624 1 0 100 0 0 20 0.0000 4 195 1620 3675 8025 B-tree Driver\001
634 1 0 100 0 0 14 0.0000 4 105 345 3675 11100 os.c\001
644 1 0 100 0 0 20 0.0000 4 195 1470 3675 10725 OS Interface\001
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/arch.gif b/libraries/sqlite/unix/sqlite-3.5.1/www/arch.gif
deleted file mode 100644
index 4dd8d14..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/arch.gif
+++ /dev/null
Binary files differ
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/arch.png b/libraries/sqlite/unix/sqlite-3.5.1/www/arch.png
deleted file mode 100644
index 7a2a3ab..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/arch.png
+++ /dev/null
Binary files differ
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/arch.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/arch.tcl
deleted file mode 100644
index d6c8166..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/arch.tcl
+++ /dev/null
@@ -1,221 +0,0 @@
1#
2# Run this Tcl script to generate the sqlite.html file.
3#
4set rcsid {$Id: arch.tcl,v 1.16 2004/10/10 17:24:54 drh Exp $}
5source common.tcl
6header {Architecture of SQLite}
7puts {
8<h2>The Architecture Of SQLite</h2>
9
10<h3>Introduction</h3>
11
12<table align="right" border="1" cellpadding="15" cellspacing="1">
13<tr><th>Block Diagram Of SQLite</th></tr>
14<tr><td><img src="arch2.gif"></td></tr>
15</table>
16<p>This document describes the architecture of the SQLite library.
17The information here is useful to those who want to understand or
18modify the inner workings of SQLite.
19</p>
20
21<p>
22A block diagram showing the main components of SQLite
23and how they interrelate is shown at the right. The text that
24follows will provide a quick overview of each of these components.
25</p>
26
27
28<p>
29This document describes SQLite version 3.0. Version 2.8 and
30earlier are similar but the details differ.
31</p>
32
33<h3>Interface</h3>
34
35<p>Much of the public interface to the SQLite library is implemented by
36functions found in the <b>main.c</b>, <b>legacy.c</b>, and
37<b>vdbeapi.c</b> source files
38though some routines are
39scattered about in other files where they can have access to data
40structures with file scope. The
41<b>sqlite3_get_table()</b> routine is implemented in <b>table.c</b>.
42<b>sqlite3_mprintf()</b> is found in <b>printf.c</b>.
43<b>sqlite3_complete()</b> is in <b>tokenize.c</b>.
44The Tcl interface is implemented by <b>tclsqlite.c</b>. More
45information on the C interface to SQLite is
46<a href="capi3ref.html">available separately</a>.<p>
47
48<p>To avoid name collisions with other software, all external
49symbols in the SQLite library begin with the prefix <b>sqlite3</b>.
50Those symbols that are intended for external use (in other words,
51those symbols which form the API for SQLite) begin
52with <b>sqlite3_</b>.</p>
53
54<h3>Tokenizer</h3>
55
56<p>When a string containing SQL statements is to be executed, the
57interface passes that string to the tokenizer. The job of the tokenizer
58is to break the original string up into tokens and pass those tokens
59one by one to the parser. The tokenizer is hand-coded in C in
60the file <b>tokenize.c</b>.
61
62<p>Note that in this design, the tokenizer calls the parser. People
63who are familiar with YACC and BISON may be used to doing things the
64other way around -- having the parser call the tokenizer. The author
65of SQLite
66has done it both ways and finds things generally work out nicer for
67the tokenizer to call the parser. YACC has it backwards.</p>
68
69<h3>Parser</h3>
70
71<p>The parser is the piece that assigns meaning to tokens based on
72their context. The parser for SQLite is generated using the
73<a href="http://www.hwaci.com/sw/lemon/">Lemon</a> LALR(1) parser
74generator. Lemon does the same job as YACC/BISON, but it uses
75a different input syntax which is less error-prone.
76Lemon also generates a parser which is reentrant and thread-safe.
77And lemon defines the concept of a non-terminal destructor so
78that it does not leak memory when syntax errors are encountered.
79The source file that drives Lemon is found in <b>parse.y</b>.</p>
80
81<p>Because
82lemon is a program not normally found on development machines, the
83complete source code to lemon (just one C file) is included in the
84SQLite distribution in the "tool" subdirectory. Documentation on
85lemon is found in the "doc" subdirectory of the distribution.
86</p>
87
88<h3>Code Generator</h3>
89
90<p>After the parser assembles tokens into complete SQL statements,
91it calls the code generator to produce virtual machine code that
92will do the work that the SQL statements request. There are many
93files in the code generator:
94<b>attach.c</b>,
95<b>auth.c</b>,
96<b>build.c</b>,
97<b>delete.c</b>,
98<b>expr.c</b>,
99<b>insert.c</b>,
100<b>pragma.c</b>,
101<b>select.c</b>,
102<b>trigger.c</b>,
103<b>update.c</b>,
104<b>vacuum.c</b>
105and <b>where.c</b>.
106In these files is where most of the serious magic happens.
107<b>expr.c</b> handles code generation for expressions.
108<b>where.c</b> handles code generation for WHERE clauses on
109SELECT, UPDATE and DELETE statements. The files <b>attach.c</b>,
110<b>delete.c</b>, <b>insert.c</b>, <b>select.c</b>, <b>trigger.c</b>
111<b>update.c</b>, and <b>vacuum.c</b> handle the code generation
112for SQL statements with the same names. (Each of these files calls routines
113in <b>expr.c</b> and <b>where.c</b> as necessary.) All other
114SQL statements are coded out of <b>build.c</b>.
115The <b>auth.c</b> file implements the functionality of
116<b>sqlite3_set_authorizer()</b>.</p>
117
118<h3>Virtual Machine</h3>
119
120<p>The program generated by the code generator is executed by
121the virtual machine. Additional information about the virtual
122machine is <a href="opcode.html">available separately</a>.
123To summarize, the virtual machine implements an abstract computing
124engine specifically designed to manipulate database files. The
125machine has a stack which is used for intermediate storage.
126Each instruction contains an opcode and
127up to three additional operands.</p>
128
129<p>The virtual machine itself is entirely contained in a single
130source file <b>vdbe.c</b>. The virtual machine also has
131its own header files: <b>vdbe.h</b> that defines an interface
132between the virtual machine and the rest of the SQLite library and
133<b>vdbeInt.h</b> which defines structure private the virtual machine.
134The <b>vdbeaux.c</b> file contains utilities used by the virtual
135machine and interface modules used by the rest of the library to
136construct VM programs. The <b>vdbeapi.c</b> file contains external
137interfaces to the virtual machine such as the
138<b>sqlite3_bind_...</b> family of functions. Individual values
139(strings, integer, floating point numbers, and BLOBs) are stored
140in an internal object named "Mem" which is implemented by
141<b>vdbemem.c</b>.</p>
142
143<p>
144SQLite implements SQL functions using callbacks to C-language routines.
145Even the built-in SQL functions are implemented this way. Most of
146the built-in SQL functions (ex: <b>coalesce()</b>, <b>count()</b>,
147<b>substr()</b>, and so forth) can be found in <b>func.c</b>.
148Date and time conversion functions are found in <b>date.c</b>.
149</p>
150
151<h3>B-Tree</h3>
152
153<p>An SQLite database is maintained on disk using a B-tree implementation
154found in the <b>btree.c</b> source file. A separate B-tree is used for
155each table and index in the database. All B-trees are stored in the
156same disk file. Details of the file format are recorded in a large
157comment at the beginning of <b>btree.c</b>.</p>
158
159<p>The interface to the B-tree subsystem is defined by the header file
160<b>btree.h</b>.
161</p>
162
163<h3>Page Cache</h3>
164
165<p>The B-tree module requests information from the disk in fixed-size
166chunks. The default chunk size is 1024 bytes but can vary between 512
167and 65536 bytes.
168The page cache is responsible for reading, writing, and
169caching these chunks.
170The page cache also provides the rollback and atomic commit abstraction
171and takes care of locking of the database file. The
172B-tree driver requests particular pages from the page cache and notifies
173the page cache when it wants to modify pages or commit or rollback
174changes and the page cache handles all the messy details of making sure
175the requests are handled quickly, safely, and efficiently.</p>
176
177<p>The code to implement the page cache is contained in the single C
178source file <b>pager.c</b>. The interface to the page cache subsystem
179is defined by the header file <b>pager.h</b>.
180</p>
181
182<h3>OS Interface</h3>
183
184<p>
185In order to provide portability between POSIX and Win32 operating systems,
186SQLite uses an abstraction layer to interface with the operating system.
187The interface to the OS abstraction layer is defined in
188<b>os.h</b>. Each supported operating system has its own implementation:
189<b>os_unix.c</b> for Unix, <b>os_win.c</b> for windows, and so forth.
190Each of these operating-specific implements typically has its own
191header file: <b>os_unix.h</b>, <b>os_win.h</b>, etc.
192</p>
193
194<h3>Utilities</h3>
195
196<p>
197Memory allocation and caseless string comparison routines are located
198in <b>util.c</b>.
199Symbol tables used by the parser are maintained by hash tables found
200in <b>hash.c</b>. The <b>utf.c</b> source file contains Unicode
201conversion subroutines.
202SQLite has its own private implementation of <b>printf()</b> (with
203some extensions) in <b>printf.c</b> and its own random number generator
204in <b>random.c</b>.
205</p>
206
207<h3>Test Code</h3>
208
209<p>
210If you count regression test scripts,
211more than half the total code base of SQLite is devoted to testing.
212There are many <b>assert()</b> statements in the main code files.
213In additional, the source files <b>test1.c</b> through <b>test5.c</b>
214together with <b>md5.c</b> implement extensions used for testing
215purposes only. The <b>os_test.c</b> backend interface is used to
216simulate power failures to verify the crash-recovery mechanism in
217the pager.
218</p>
219
220}
221footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/arch2.fig b/libraries/sqlite/unix/sqlite-3.5.1/www/arch2.fig
deleted file mode 100644
index 70bc5f1..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/arch2.fig
+++ /dev/null
@@ -1,123 +0,0 @@
1#FIG 3.2
2Landscape
3Center
4Inches
5Letter
6100.00
7Single
8-2
91200 2
100 32 #000000
110 33 #868686
120 34 #dfefd7
130 35 #d7efef
140 36 #efdbef
150 37 #efdbd7
160 38 #e7efcf
170 39 #9e9e9e
186 3225 3900 4650 6000
192 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
20 3225 5475 4575 5475 4575 5925 3225 5925 3225 5475
212 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
22 3300 5550 4650 5550 4650 6000 3300 6000 3300 5550
232 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
24 3225 4650 4575 4650 4575 5100 3225 5100 3225 4650
252 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
26 3300 4725 4650 4725 4650 5175 3300 5175 3300 4725
272 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
28 3225 3900 4575 3900 4575 4350 3225 4350 3225 3900
292 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
30 3300 3975 4650 3975 4650 4425 3300 4425 3300 3975
312 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
32 1 1 1.00 60.00 120.00
33 3900 4350 3900 4650
342 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
35 1 1 1.00 60.00 120.00
36 3900 5100 3900 5475
374 1 0 50 0 2 12 0.0000 4 135 1050 3900 5775 OS Interface\001
384 1 0 50 0 2 12 0.0000 4 135 615 3900 4200 B-Tree\001
394 1 0 50 0 2 12 0.0000 4 180 495 3900 4950 Pager\001
40-6
416 5400 4725 6825 5250
422 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
43 5400 4725 6750 4725 6750 5175 5400 5175 5400 4725
442 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
45 5475 4800 6825 4800 6825 5250 5475 5250 5475 4800
464 1 0 50 0 2 12 0.0000 4 135 630 6000 5025 Utilities\001
47-6
486 5400 5550 6825 6075
492 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
50 5400 5550 6750 5550 6750 6000 5400 6000 5400 5550
512 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
52 5475 5625 6825 5625 6825 6075 5475 6075 5475 5625
534 1 0 50 0 2 12 0.0000 4 135 855 6000 5850 Test Code\001
54-6
556 5400 2775 6825 3750
562 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
57 5475 2850 6825 2850 6825 3750 5475 3750 5475 2850
582 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
59 5400 2775 6750 2775 6750 3675 5400 3675 5400 2775
604 1 0 50 0 2 12 0.0000 4 135 420 6075 3150 Code\001
614 1 0 50 0 2 12 0.0000 4 135 855 6075 3375 Generator\001
62-6
636 5400 1950 6825 2475
642 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
65 5400 1950 6750 1950 6750 2400 5400 2400 5400 1950
662 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
67 5475 2025 6825 2025 6825 2475 5475 2475 5475 2025
684 1 0 50 0 2 12 0.0000 4 135 570 6075 2250 Parser\001
69-6
702 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
71 5400 1050 6750 1050 6750 1500 5400 1500 5400 1050
722 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
73 5475 1125 6825 1125 6825 1575 5475 1575 5475 1125
742 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
75 3225 1050 4575 1050 4575 1500 3225 1500 3225 1050
762 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
77 3300 1125 4650 1125 4650 1575 3300 1575 3300 1125
782 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
79 3225 1800 4575 1800 4575 2250 3225 2250 3225 1800
802 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
81 3300 1875 4650 1875 4650 2325 3300 2325 3300 1875
822 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
83 3225 2550 4575 2550 4575 3000 3225 3000 3225 2550
842 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
85 3300 2625 4650 2625 4650 3075 3300 3075 3300 2625
862 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
87 1 1 1.00 60.00 120.00
88 3900 1500 3900 1800
892 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
90 1 1 1.00 60.00 120.00
91 3900 2250 3900 2550
922 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
93 1 1 1.00 60.00 120.00
94 3900 3000 3900 3900
952 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
96 1 1 1.00 60.00 120.00
97 4575 1950 5400 1350
982 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
99 1 1 1.00 60.00 120.00
100 5400 2925 4650 2325
1012 2 0 1 0 34 55 0 20 0.000 0 0 -1 0 0 5
102 2850 750 4875 750 4875 3375 2850 3375 2850 750
1032 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
104 1 1 1.00 60.00 120.00
105 6075 1500 6075 1950
1062 3 0 1 0 35 55 0 20 0.000 0 0 -1 0 0 5
107 2850 3675 4875 3675 4875 6225 2850 6225 2850 3675
1082 2 0 1 0 37 55 0 20 0.000 0 0 -1 0 0 5
109 5175 750 7200 750 7200 4050 5175 4050 5175 750
1102 2 0 1 0 38 55 0 20 0.000 0 0 -1 0 0 5
111 5175 4425 7200 4425 7200 6225 5175 6225 5175 4425
1122 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
113 1 1 1.00 60.00 120.00
114 6075 2475 6075 2775
1154 1 0 50 0 2 12 0.0000 4 135 855 6075 1350 Tokenizer\001
1164 1 0 50 0 1 12 1.5708 4 180 1020 7125 2250 SQL Compiler\001
1174 1 0 50 0 1 12 1.5708 4 135 345 3075 2025 Core\001
1184 1 0 50 0 2 12 0.0000 4 135 1290 3900 2850 Virtual Machine\001
1194 1 0 50 0 2 12 0.0000 4 165 1185 3900 1995 SQL Command\001
1204 1 0 50 0 2 12 0.0000 4 135 855 3900 2183 Processor\001
1214 1 0 50 0 2 14 0.0000 4 150 870 3900 1350 Interface\001
1224 1 0 50 0 1 12 1.5708 4 135 885 7125 5400 Accessories\001
1234 1 0 50 0 1 12 1.5708 4 135 645 3075 4875 Backend\001
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/arch2.gif b/libraries/sqlite/unix/sqlite-3.5.1/www/arch2.gif
deleted file mode 100644
index cca2925..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/arch2.gif
+++ /dev/null
Binary files differ
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/arch2b.fig b/libraries/sqlite/unix/sqlite-3.5.1/www/arch2b.fig
deleted file mode 100644
index e8ba8cc..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/arch2b.fig
+++ /dev/null
@@ -1,125 +0,0 @@
1#FIG 3.2
2Landscape
3Center
4Inches
5Letter
6100.00
7Single
8-2
91200 2
100 32 #000000
110 33 #868686
120 34 #dfefd7
130 35 #d7efef
140 36 #efdbef
150 37 #efdbd7
160 38 #e7efcf
170 39 #9e9e9e
186 3225 3900 4650 6000
192 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
20 3225 5475 4575 5475 4575 5925 3225 5925 3225 5475
212 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
22 3300 5550 4650 5550 4650 6000 3300 6000 3300 5550
232 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
24 3225 4650 4575 4650 4575 5100 3225 5100 3225 4650
252 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
26 3300 4725 4650 4725 4650 5175 3300 5175 3300 4725
272 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
28 3225 3900 4575 3900 4575 4350 3225 4350 3225 3900
292 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
30 3300 3975 4650 3975 4650 4425 3300 4425 3300 3975
312 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
32 1 1 1.00 60.00 120.00
33 3900 4350 3900 4650
342 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
35 1 1 1.00 60.00 120.00
36 3900 5100 3900 5475
374 1 0 50 0 2 12 0.0000 4 135 1050 3900 5775 OS Interface\001
384 1 0 50 0 2 12 0.0000 4 135 615 3900 4200 B-Tree\001
394 1 0 50 0 2 12 0.0000 4 180 495 3900 4950 Pager\001
40-6
416 5175 4275 7200 6150
426 5400 4519 6825 5090
432 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
44 5400 4519 6750 4519 6750 5009 5400 5009 5400 4519
452 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
46 5475 4601 6825 4601 6825 5090 5475 5090 5475 4601
474 1 0 50 0 2 12 0.0000 4 135 630 6000 4845 Utilities\001
48-6
496 5400 5416 6825 5987
502 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
51 5400 5416 6750 5416 6750 5906 5400 5906 5400 5416
522 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
53 5475 5498 6825 5498 6825 5987 5475 5987 5475 5498
544 1 0 50 0 2 12 0.0000 4 135 855 6000 5742 Test Code\001
55-6
562 2 0 1 0 38 55 0 20 0.000 0 0 -1 0 0 5
57 5175 4275 7200 4275 7200 6150 5175 6150 5175 4275
584 1 0 50 0 1 12 1.5708 4 135 885 7125 5253 Accessories\001
59-6
606 5400 2700 6825 3675
612 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
62 5475 2775 6825 2775 6825 3675 5475 3675 5475 2775
632 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
64 5400 2700 6750 2700 6750 3600 5400 3600 5400 2700
654 1 0 50 0 2 12 0.0000 4 135 420 6075 3075 Code\001
664 1 0 50 0 2 12 0.0000 4 135 855 6075 3300 Generator\001
67-6
686 5400 1875 6825 2400
692 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
70 5400 1875 6750 1875 6750 2325 5400 2325 5400 1875
712 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
72 5475 1950 6825 1950 6825 2400 5475 2400 5475 1950
734 1 0 50 0 2 12 0.0000 4 135 570 6075 2175 Parser\001
74-6
752 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
76 5400 1050 6750 1050 6750 1500 5400 1500 5400 1050
772 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
78 5475 1125 6825 1125 6825 1575 5475 1575 5475 1125
792 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
80 3225 1050 4575 1050 4575 1500 3225 1500 3225 1050
812 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
82 3300 1125 4650 1125 4650 1575 3300 1575 3300 1125
832 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
84 3225 1800 4575 1800 4575 2250 3225 2250 3225 1800
852 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
86 3300 1875 4650 1875 4650 2325 3300 2325 3300 1875
872 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
88 3225 2550 4575 2550 4575 3000 3225 3000 3225 2550
892 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
90 3300 2625 4650 2625 4650 3075 3300 3075 3300 2625
912 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
92 1 1 1.00 60.00 120.00
93 3900 1500 3900 1800
942 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
95 1 1 1.00 60.00 120.00
96 3900 2250 3900 2550
972 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
98 1 1 1.00 60.00 120.00
99 3900 3000 3900 3900
1002 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
101 1 1 1.00 60.00 120.00
102 4575 1950 5400 1350
1032 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
104 1 1 1.00 60.00 120.00
105 5400 2925 4650 2175
1062 2 0 1 0 34 55 0 20 0.000 0 0 -1 0 0 5
107 2850 750 4875 750 4875 3375 2850 3375 2850 750
1082 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
109 1 1 1.00 60.00 120.00
110 6075 1500 6075 1800
1112 3 0 1 0 35 55 0 20 0.000 0 0 -1 0 0 5
112 2850 3675 4875 3675 4875 6150 2850 6150 2850 3675
1132 2 0 1 0 37 55 0 20 0.000 0 0 -1 0 0 5
114 5175 750 7200 750 7200 3975 5175 3975 5175 750
1152 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
116 1 1 1.00 60.00 120.00
117 6075 2400 6075 2700
1184 1 0 50 0 2 12 0.0000 4 135 855 6075 1350 Tokenizer\001
1194 1 0 50 0 1 12 1.5708 4 180 1020 7125 2250 SQL Compiler\001
1204 1 0 50 0 1 12 1.5708 4 135 345 3075 2025 Core\001
1214 1 0 50 0 2 12 0.0000 4 135 1290 3900 2850 Virtual Machine\001
1224 1 0 50 0 2 12 0.0000 4 165 1185 3900 1995 SQL Command\001
1234 1 0 50 0 2 12 0.0000 4 135 855 3900 2183 Processor\001
1244 1 0 50 0 2 14 0.0000 4 150 870 3900 1350 Interface\001
1254 1 0 50 0 1 12 1.5708 4 135 645 3075 4875 Backend\001
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/audit.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/audit.tcl
deleted file mode 100644
index 8b30373..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/audit.tcl
+++ /dev/null
@@ -1,214 +0,0 @@
1#
2# Run this Tcl script to generate the audit.html file.
3#
4set rcsid {$Id: audit.tcl,v 1.1 2002/07/13 16:52:35 drh Exp $}
5
6puts {<html>
7<head>
8 <title>SQLite Security Audit Procedure</title>
9</head>
10<body bgcolor=white>
11<h1 align=center>
12SQLite Security Audit Procedure
13</h1>}
14puts "<p align=center>
15(This page was last modified on [lrange $rcsid 3 4] UTC)
16</p>"
17
18puts {
19<p>
20A security audit for SQLite consists of two components. First, there is
21a check for common errors that often lead to security problems. Second,
22an attempt is made to construct a proof that SQLite has certain desirable
23security properties.
24</p>
25
26<h2>Part I: Things to check</h2>
27
28<p>
29Scan all source code and check for the following common errors:
30</p>
31
32<ol>
33<li><p>
34Verify that the destination buffer is large enough to hold its result
35in every call to the following routines:
36<ul>
37<li> <b>strcpy()</b> </li>
38<li> <b>strncpy()</b> </li>
39<li> <b>strcat()</b> </li>
40<li> <b>memcpy()</b> </li>
41<li> <b>memset()</b> </li>
42<li> <b>memmove()</b> </li>
43<li> <b>bcopy()</b> </li>
44<li> <b>sprintf()</b> </li>
45<li> <b>scanf()</b> </li>
46</ul>
47</p></li>
48<li><p>
49Verify that pointers returned by subroutines are not NULL before using
50the pointers. In particular, make sure the return values for the following
51routines are checked before they are used:
52<ul>
53<li> <b>malloc()</b> </li>
54<li> <b>realloc()</b> </li>
55<li> <b>sqliteMalloc()</b> </li>
56<li> <b>sqliteRealloc()</b> </li>
57<li> <b>sqliteStrDup()</b> </li>
58<li> <b>sqliteStrNDup()</b> </li>
59<li> <b>sqliteExpr()</b> </li>
60<li> <b>sqliteExprFunction()</b> </li>
61<li> <b>sqliteExprListAppend()</b> </li>
62<li> <b>sqliteResultSetOfSelect()</b> </li>
63<li> <b>sqliteIdListAppend()</b> </li>
64<li> <b>sqliteSrcListAppend()</b> </li>
65<li> <b>sqliteSelectNew()</b> </li>
66<li> <b>sqliteTableNameToTable()</b> </li>
67<li> <b>sqliteTableTokenToSrcList()</b> </li>
68<li> <b>sqliteWhereBegin()</b> </li>
69<li> <b>sqliteFindTable()</b> </li>
70<li> <b>sqliteFindIndex()</b> </li>
71<li> <b>sqliteTableNameFromToken()</b> </li>
72<li> <b>sqliteGetVdbe()</b> </li>
73<li> <b>sqlite_mprintf()</b> </li>
74<li> <b>sqliteExprDup()</b> </li>
75<li> <b>sqliteExprListDup()</b> </li>
76<li> <b>sqliteSrcListDup()</b> </li>
77<li> <b>sqliteIdListDup()</b> </li>
78<li> <b>sqliteSelectDup()</b> </li>
79<li> <b>sqliteFindFunction()</b> </li>
80<li> <b>sqliteTriggerSelectStep()</b> </li>
81<li> <b>sqliteTriggerInsertStep()</b> </li>
82<li> <b>sqliteTriggerUpdateStep()</b> </li>
83<li> <b>sqliteTriggerDeleteStep()</b> </li>
84</ul>
85</p></li>
86<li><p>
87On all functions and procedures, verify that pointer parameters are not NULL
88before dereferencing those parameters.
89</p></li>
90<li><p>
91Check to make sure that temporary files are opened safely: that the process
92will not overwrite an existing file when opening the temp file and that
93another process is unable to substitute a file for the temp file being
94opened.
95</p></li>
96</ol>
97
98
99
100<h2>Part II: Things to prove</h2>
101
102<p>
103Prove that SQLite exhibits the characteristics outlined below:
104</p>
105
106<ol>
107<li><p>
108The following are preconditions:</p>
109<p><ul>
110<li><b>Z</b> is an arbitrary-length NUL-terminated string.</li>
111<li>An existing SQLite database has been opened. The return value
112 from the call to <b>sqlite_open()</b> is stored in the variable
113 <b>db</b>.</li>
114<li>The database contains at least one table of the form:
115<blockquote><pre>
116CREATE TABLE t1(a CLOB);
117</pre></blockquote></li>
118<li>There are no user-defined functions other than the standard
119 build-in functions.</li>
120</ul></p>
121<p>The following statement of C code is executed:</p>
122<blockquote><pre>
123sqlite_exec_printf(
124 db,
125 "INSERT INTO t1(a) VALUES('%q');",
126 0, 0, 0, Z
127);
128</pre></blockquote>
129<p>Prove the following are true for all possible values of string <b>Z</b>:</p>
130<ol type="a">
131<li><p>
132The call to <b>sqlite_exec_printf()</b> will
133return in a length of time that is a polynomial in <b>strlen(Z)</b>.
134It might return an error code but it will not crash.
135</p></li>
136<li><p>
137At most one new row will be inserted into table t1.
138</p></li>
139<li><p>
140No preexisting rows of t1 will be deleted or modified.
141</p></li>
142<li><p>
143No tables other than t1 will be altered in any way.
144</p></li>
145<li><p>
146No preexisting files on the host computers filesystem, other than
147the database file itself, will be deleted or modified.
148</p></li>
149<li><p>
150For some constants <b>K1</b> and <b>K2</b>,
151if at least <b>K1*strlen(Z) + K2</b> bytes of contiguous memory are
152available to <b>malloc()</b>, then the call to <b>sqlite_exec_printf()</b>
153will not return SQLITE_NOMEM.
154</p></li>
155</ol>
156</p></li>
157
158
159<li><p>
160The following are preconditions:
161<p><ul>
162<li><b>Z</b> is an arbitrary-length NUL-terminated string.</li>
163<li>An existing SQLite database has been opened. The return value
164 from the call to <b>sqlite_open()</b> is stored in the variable
165 <b>db</b>.</li>
166<li>There exists a callback function <b>cb()</b> that appends all
167 information passed in through its parameters into a single
168 data buffer called <b>Y</b>.</li>
169<li>There are no user-defined functions other than the standard
170 build-in functions.</li>
171</ul></p>
172<p>The following statement of C code is executed:</p>
173<blockquote><pre>
174sqlite_exec(db, Z, cb, 0, 0);
175</pre></blockquote>
176<p>Prove the following are true for all possible values of string <b>Z</b>:</p>
177<ol type="a">
178<li><p>
179The call to <b>sqlite_exec()</b> will
180return in a length of time which is a polynomial in <b>strlen(Z)</b>.
181It might return an error code but it will not crash.
182</p></li>
183<li><p>
184After <b>sqlite_exec()</b> returns, the buffer <b>Y</b> will not contain
185any content from any preexisting file on the host computers file system,
186except for the database file.
187</p></li>
188<li><p>
189After the call to <b>sqlite_exec()</b> returns, the database file will
190still be well-formed. It might not contain the same data, but it will
191still be a properly constructed SQLite database file.
192</p></li>
193<li><p>
194No preexisting files on the host computers filesystem, other than
195the database file itself, will be deleted or modified.
196</p></li>
197<li><p>
198For some constants <b>K1</b> and <b>K2</b>,
199if at least <b>K1*strlen(Z) + K2</b> bytes of contiguous memory are
200available to <b>malloc()</b>, then the call to <b>sqlite_exec()</b>
201will not return SQLITE_NOMEM.
202</p></li>
203</ol>
204</p></li>
205
206</ol>
207}
208puts {
209<p><hr /></p>
210<p><a href="index.html"><img src="/goback.jpg" border=0 />
211Back to the SQLite Home Page</a>
212</p>
213
214</body></html>}
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/autoinc.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/autoinc.tcl
deleted file mode 100644
index 9332adc..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/autoinc.tcl
+++ /dev/null
@@ -1,109 +0,0 @@
1#
2# Run this Tcl script to generate the autoinc.html file.
3#
4set rcsid {$Id: }
5source common.tcl
6
7if {[llength $argv]>0} {
8 set outputdir [lindex $argv 0]
9} else {
10 set outputdir ""
11}
12
13header {SQLite Autoincrement}
14puts {
15<h1>SQLite Autoincrement</h1>
16
17<p>
18In SQLite, every row of every table has an integer ROWID.
19The ROWID for each row is unique among all rows in the same table.
20In SQLite version 2.8 the ROWID is a 32-bit signed integer.
21Version 3.0 of SQLite expanded the ROWID to be a 64-bit signed integer.
22</p>
23
24<p>
25You can access the ROWID of an SQLite table using one the special column
26names ROWID, _ROWID_, or OID.
27Except if you declare an ordinary table column to use one of those special
28names, then the use of that name will refer to the declared column not
29to the internal ROWID.
30</p>
31
32<p>
33If a table contains a column of type INTEGER PRIMARY KEY, then that
34column becomes an alias for the ROWID. You can then access the ROWID
35using any of four different names, the original three names described above
36or the name given to the INTEGER PRIMARY KEY column. All these names are
37aliases for one another and work equally well in any context.
38</p>
39
40<p>
41When a new row is inserted into an SQLite table, the ROWID can either
42be specified as part of the INSERT statement or it can be assigned
43automatically by the database engine. To specify a ROWID manually,
44just include it in the list of values to be inserted. For example:
45</p>
46
47<blockquote><pre>
48CREATE TABLE test1(a INT, b TEXT);
49INSERT INTO test1(rowid, a, b) VALUES(123, 5, 'hello');
50</pre></blockquote>
51
52<p>
53If no ROWID is specified on the insert, an appropriate ROWID is created
54automatically. The usual algorithm is to give the newly created row
55a ROWID that is one larger than the largest ROWID in the table prior
56to the insert. If the table is initially empty, then a ROWID of 1 is
57used. If the largest ROWID is equal to the largest possible integer
58(9223372036854775807 in SQLite version 3.0 and later) then the database
59engine starts picking candidate ROWIDs at random until it finds one
60that is not previously used.
61</p>
62
63<p>
64The normal ROWID selection algorithm described above
65will generate monotonically increasing
66unique ROWIDs as long as you never use the maximum ROWID value and you never
67delete the entry in the table with the largest ROWID.
68If you ever delete rows or if you ever create a row with the maximum possible
69ROWID, then ROWIDs from previously deleted rows might be reused when creating
70new rows and newly created ROWIDs might not be in strictly accending order.
71</p>
72
73
74<h2>The AUTOINCREMENT Keyword</h2>
75
76<p>
77If a column has the type INTEGER PRIMARY KEY AUTOINCREMENT then a slightly
78different ROWID selection algorithm is used.
79The ROWID chosen for the new row is one larger than the largest ROWID
80that has ever before existed in that same table. If the table has never
81before contained any data, then a ROWID of 1 is used. If the table
82has previously held a row with the largest possible ROWID, then new INSERTs
83are not allowed and any attempt to insert a new row will fail with an
84SQLITE_FULL error.
85</p>
86
87<p>
88SQLite keeps track of the largest ROWID that a table has ever held using
89the special SQLITE_SEQUENCE table. The SQLITE_SEQUENCE table is created
90and initialized automatically whenever a normal table that contains an
91AUTOINCREMENT column is created. The content of the SQLITE_SEQUENCE table
92can be modified using ordinary UPDATE, INSERT, and DELETE statements.
93But making modifications to this table will likely perturb the AUTOINCREMENT
94key generation algorithm. Make sure you know what you are doing before
95you undertake such changes.
96</p>
97
98<p>
99The behavior implemented by the AUTOINCREMENT keyword is subtly different
100from the default behavior. With AUTOINCREMENT, rows with automatically
101selected ROWIDs are guaranteed to have ROWIDs that have never been used
102before by the same table in the same database. And the automatically generated
103ROWIDs are guaranteed to be monotonically increasing. These are important
104properties in certain applications. But if your application does not
105need these properties, you should probably stay with the default behavior
106since the use of AUTOINCREMENT requires additional work to be done
107as each row is inserted and thus causes INSERTs to run a little slower.
108}
109footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/c_interface.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/c_interface.tcl
deleted file mode 100644
index c784ff0..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/c_interface.tcl
+++ /dev/null
@@ -1,1116 +0,0 @@
1#
2# Run this Tcl script to generate the sqlite.html file.
3#
4set rcsid {$Id: c_interface.tcl,v 1.43 2004/11/19 11:59:24 danielk1977 Exp $}
5source common.tcl
6header {The C language interface to the SQLite library}
7puts {
8<h2>The C language interface to the SQLite library</h2>
9
10<p>The SQLite library is designed to be very easy to use from
11a C or C++ program. This document gives an overview of the C/C++
12programming interface.</p>
13
14<h3>1.0 The Core API</h3>
15
16<p>The interface to the SQLite library consists of three core functions,
17one opaque data structure, and some constants used as return values.
18The core interface is as follows:</p>
19
20<blockquote><pre>
21typedef struct sqlite sqlite;
22#define SQLITE_OK 0 /* Successful result */
23
24sqlite *sqlite_open(const char *dbname, int mode, char **errmsg);
25
26void sqlite_close(sqlite *db);
27
28int sqlite_exec(
29 sqlite *db,
30 char *sql,
31 int (*xCallback)(void*,int,char**,char**),
32 void *pArg,
33 char **errmsg
34);
35</pre></blockquote>
36
37<p>
38The above is all you really need to know in order to use SQLite
39in your C or C++ programs. There are other interface functions
40available (and described below) but we will begin by describing
41the core functions shown above.
42</p>
43
44<a name="sqlite_open">
45<h4>1.1 Opening a database</h4>
46
47<p>Use the <b>sqlite_open</b> function to open an existing SQLite
48database or to create a new SQLite database. The first argument
49is the database name. The second argument is intended to signal
50whether the database is going to be used for reading and writing
51or just for reading. But in the current implementation, the
52second argument to <b>sqlite_open</b> is ignored.
53The third argument is a pointer to a string pointer.
54If the third argument is not NULL and an error occurs
55while trying to open the database, then an error message will be
56written to memory obtained from malloc() and *errmsg will be made
57to point to this error message. The calling function is responsible
58for freeing the memory when it has finished with it.</p>
59
60<p>The name of an SQLite database is the name of a file that will
61contain the database. If the file does not exist, SQLite attempts
62to create and initialize it. If the file is read-only (due to
63permission bits or because it is located on read-only media like
64a CD-ROM) then SQLite opens the database for reading only. The
65entire SQL database is stored in a single file on the disk. But
66additional temporary files may be created during the execution of
67an SQL command in order to store the database rollback journal or
68temporary and intermediate results of a query.</p>
69
70<p>The return value of the <b>sqlite_open</b> function is a
71pointer to an opaque <b>sqlite</b> structure. This pointer will
72be the first argument to all subsequent SQLite function calls that
73deal with the same database. NULL is returned if the open fails
74for any reason.</p>
75
76<a name="sqlite_close">
77<h4>1.2 Closing the database</h4>
78
79<p>To close an SQLite database, call the <b>sqlite_close</b>
80function passing it the sqlite structure pointer that was obtained
81from a prior call to <b>sqlite_open</b>.
82If a transaction is active when the database is closed, the transaction
83is rolled back.</p>
84
85<a name="sqlite_exec">
86<h4>1.3 Executing SQL statements</h4>
87
88<p>The <b>sqlite_exec</b> function is used to process SQL statements
89and queries. This function requires 5 parameters as follows:</p>
90
91<ol>
92<li><p>A pointer to the sqlite structure obtained from a prior call
93 to <b>sqlite_open</b>.</p></li>
94<li><p>A null-terminated string containing the text of one or more
95 SQL statements and/or queries to be processed.</p></li>
96<li><p>A pointer to a callback function which is invoked once for each
97 row in the result of a query. This argument may be NULL, in which
98 case no callbacks will ever be invoked.</p></li>
99<li><p>A pointer that is forwarded to become the first argument
100 to the callback function.</p></li>
101<li><p>A pointer to an error string. Error messages are written to space
102 obtained from malloc() and the error string is made to point to
103 the malloced space. The calling function is responsible for freeing
104 this space when it has finished with it.
105 This argument may be NULL, in which case error messages are not
106 reported back to the calling function.</p></li>
107</ol>
108
109<p>
110The callback function is used to receive the results of a query. A
111prototype for the callback function is as follows:</p>
112
113<blockquote><pre>
114int Callback(void *pArg, int argc, char **argv, char **columnNames){
115 return 0;
116}
117</pre></blockquote>
118
119<a name="callback_row_data">
120<p>The first argument to the callback is just a copy of the fourth argument
121to <b>sqlite_exec</b> This parameter can be used to pass arbitrary
122information through to the callback function from client code.
123The second argument is the number of columns in the query result.
124The third argument is an array of pointers to strings where each string
125is a single column of the result for that record. Note that the
126callback function reports a NULL value in the database as a NULL pointer,
127which is very different from an empty string. If the i-th parameter
128is an empty string, we will get:</p>
129<blockquote><pre>
130argv[i][0] == 0
131</pre></blockquote>
132<p>But if the i-th parameter is NULL we will get:</p>
133<blockquote><pre>
134argv[i] == 0
135</pre></blockquote>
136
137<p>The names of the columns are contained in first <i>argc</i>
138entries of the fourth argument.
139If the <a href="pragma.html#pragma_show_datatypes">SHOW_DATATYPES</a> pragma
140is on (it is off by default) then
141the second <i>argc</i> entries in the 4th argument are the datatypes
142for the corresponding columns.
143</p>
144
145<p>If the <a href="pragma.html#pragma_empty_result_callbacks">
146EMPTY_RESULT_CALLBACKS</a> pragma is set to ON and the result of
147a query is an empty set, then the callback is invoked once with the
148third parameter (argv) set to 0. In other words
149<blockquote><pre>
150argv == 0
151</pre></blockquote>
152The second parameter (argc)
153and the fourth parameter (columnNames) are still valid
154and can be used to determine the number and names of the result
155columns if there had been a result.
156The default behavior is not to invoke the callback at all if the
157result set is empty.</p>
158
159<a name="callback_returns_nonzero">
160<p>The callback function should normally return 0. If the callback
161function returns non-zero, the query is immediately aborted and
162<b>sqlite_exec</b> will return SQLITE_ABORT.</p>
163
164<h4>1.4 Error Codes</h4>
165
166<p>
167The <b>sqlite_exec</b> function normally returns SQLITE_OK. But
168if something goes wrong it can return a different value to indicate
169the type of error. Here is a complete list of the return codes:
170</p>
171
172<blockquote><pre>
173#define SQLITE_OK 0 /* Successful result */
174#define SQLITE_ERROR 1 /* SQL error or missing database */
175#define SQLITE_INTERNAL 2 /* An internal logic error in SQLite */
176#define SQLITE_PERM 3 /* Access permission denied */
177#define SQLITE_ABORT 4 /* Callback routine requested an abort */
178#define SQLITE_BUSY 5 /* The database file is locked */
179#define SQLITE_LOCKED 6 /* A table in the database is locked */
180#define SQLITE_NOMEM 7 /* A malloc() failed */
181#define SQLITE_READONLY 8 /* Attempt to write a readonly database */
182#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite_interrupt() */
183#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
184#define SQLITE_CORRUPT 11 /* The database disk image is malformed */
185#define SQLITE_NOTFOUND 12 /* (Internal Only) Table or record not found */
186#define SQLITE_FULL 13 /* Insertion failed because database is full */
187#define SQLITE_CANTOPEN 14 /* Unable to open the database file */
188#define SQLITE_PROTOCOL 15 /* Database lock protocol error */
189#define SQLITE_EMPTY 16 /* (Internal Only) Database table is empty */
190#define SQLITE_SCHEMA 17 /* The database schema changed */
191#define SQLITE_TOOBIG 18 /* Too much data for one row of a table */
192#define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */
193#define SQLITE_MISMATCH 20 /* Data type mismatch */
194#define SQLITE_MISUSE 21 /* Library used incorrectly */
195#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
196#define SQLITE_AUTH 23 /* Authorization denied */
197#define SQLITE_ROW 100 /* sqlite_step() has another row ready */
198#define SQLITE_DONE 101 /* sqlite_step() has finished executing */
199</pre></blockquote>
200
201<p>
202The meanings of these various return values are as follows:
203</p>
204
205<blockquote>
206<dl>
207<dt>SQLITE_OK</dt>
208<dd><p>This value is returned if everything worked and there were no errors.
209</p></dd>
210<dt>SQLITE_INTERNAL</dt>
211<dd><p>This value indicates that an internal consistency check within
212the SQLite library failed. This can only happen if there is a bug in
213the SQLite library. If you ever get an SQLITE_INTERNAL reply from
214an <b>sqlite_exec</b> call, please report the problem on the SQLite
215mailing list.
216</p></dd>
217<dt>SQLITE_ERROR</dt>
218<dd><p>This return value indicates that there was an error in the SQL
219that was passed into the <b>sqlite_exec</b>.
220</p></dd>
221<dt>SQLITE_PERM</dt>
222<dd><p>This return value says that the access permissions on the database
223file are such that the file cannot be opened.
224</p></dd>
225<dt>SQLITE_ABORT</dt>
226<dd><p>This value is returned if the callback function returns non-zero.
227</p></dd>
228<dt>SQLITE_BUSY</dt>
229<dd><p>This return code indicates that another program or thread has
230the database locked. SQLite allows two or more threads to read the
231database at the same time, but only one thread can have the database
232open for writing at the same time. Locking in SQLite is on the
233entire database.</p>
234</p></dd>
235<dt>SQLITE_LOCKED</dt>
236<dd><p>This return code is similar to SQLITE_BUSY in that it indicates
237that the database is locked. But the source of the lock is a recursive
238call to <b>sqlite_exec</b>. This return can only occur if you attempt
239to invoke sqlite_exec from within a callback routine of a query
240from a prior invocation of sqlite_exec. Recursive calls to
241sqlite_exec are allowed as long as they do
242not attempt to write the same table.
243</p></dd>
244<dt>SQLITE_NOMEM</dt>
245<dd><p>This value is returned if a call to <b>malloc</b> fails.
246</p></dd>
247<dt>SQLITE_READONLY</dt>
248<dd><p>This return code indicates that an attempt was made to write to
249a database file that is opened for reading only.
250</p></dd>
251<dt>SQLITE_INTERRUPT</dt>
252<dd><p>This value is returned if a call to <b>sqlite_interrupt</b>
253interrupts a database operation in progress.
254</p></dd>
255<dt>SQLITE_IOERR</dt>
256<dd><p>This value is returned if the operating system informs SQLite
257that it is unable to perform some disk I/O operation. This could mean
258that there is no more space left on the disk.
259</p></dd>
260<dt>SQLITE_CORRUPT</dt>
261<dd><p>This value is returned if SQLite detects that the database it is
262working on has become corrupted. Corruption might occur due to a rogue
263process writing to the database file or it might happen due to an
264perviously undetected logic error in of SQLite. This value is also
265returned if a disk I/O error occurs in such a way that SQLite is forced
266to leave the database file in a corrupted state. The latter should only
267happen due to a hardware or operating system malfunction.
268</p></dd>
269<dt>SQLITE_FULL</dt>
270<dd><p>This value is returned if an insertion failed because there is
271no space left on the disk, or the database is too big to hold any
272more information. The latter case should only occur for databases
273that are larger than 2GB in size.
274</p></dd>
275<dt>SQLITE_CANTOPEN</dt>
276<dd><p>This value is returned if the database file could not be opened
277for some reason.
278</p></dd>
279<dt>SQLITE_PROTOCOL</dt>
280<dd><p>This value is returned if some other process is messing with
281file locks and has violated the file locking protocol that SQLite uses
282on its rollback journal files.
283</p></dd>
284<dt>SQLITE_SCHEMA</dt>
285<dd><p>When the database first opened, SQLite reads the database schema
286into memory and uses that schema to parse new SQL statements. If another
287process changes the schema, the command currently being processed will
288abort because the virtual machine code generated assumed the old
289schema. This is the return code for such cases. Retrying the
290command usually will clear the problem.
291</p></dd>
292<dt>SQLITE_TOOBIG</dt>
293<dd><p>SQLite will not store more than about 1 megabyte of data in a single
294row of a single table. If you attempt to store more than 1 megabyte
295in a single row, this is the return code you get.
296</p></dd>
297<dt>SQLITE_CONSTRAINT</dt>
298<dd><p>This constant is returned if the SQL statement would have violated
299a database constraint.
300</p></dd>
301<dt>SQLITE_MISMATCH</dt>
302<dd><p>This error occurs when there is an attempt to insert non-integer
303data into a column labeled INTEGER PRIMARY KEY. For most columns, SQLite
304ignores the data type and allows any kind of data to be stored. But
305an INTEGER PRIMARY KEY column is only allowed to store integer data.
306</p></dd>
307<dt>SQLITE_MISUSE</dt>
308<dd><p>This error might occur if one or more of the SQLite API routines
309is used incorrectly. Examples of incorrect usage include calling
310<b>sqlite_exec</b> after the database has been closed using
311<b>sqlite_close</b> or
312calling <b>sqlite_exec</b> with the same
313database pointer simultaneously from two separate threads.
314</p></dd>
315<dt>SQLITE_NOLFS</dt>
316<dd><p>This error means that you have attempts to create or access a file
317database file that is larger that 2GB on a legacy Unix machine that
318lacks large file support.
319</p></dd>
320<dt>SQLITE_AUTH</dt>
321<dd><p>This error indicates that the authorizer callback
322has disallowed the SQL you are attempting to execute.
323</p></dd>
324<dt>SQLITE_ROW</dt>
325<dd><p>This is one of the return codes from the
326<b>sqlite_step</b> routine which is part of the non-callback API.
327It indicates that another row of result data is available.
328</p></dd>
329<dt>SQLITE_DONE</dt>
330<dd><p>This is one of the return codes from the
331<b>sqlite_step</b> routine which is part of the non-callback API.
332It indicates that the SQL statement has been completely executed and
333the <b>sqlite_finalize</b> routine is ready to be called.
334</p></dd>
335</dl>
336</blockquote>
337
338<h3>2.0 Accessing Data Without Using A Callback Function</h3>
339
340<p>
341The <b>sqlite_exec</b> routine described above used to be the only
342way to retrieve data from an SQLite database. But many programmers found
343it inconvenient to use a callback function to obtain results. So beginning
344with SQLite version 2.7.7, a second access interface is available that
345does not use callbacks.
346</p>
347
348<p>
349The new interface uses three separate functions to replace the single
350<b>sqlite_exec</b> function.
351</p>
352
353<blockquote><pre>
354typedef struct sqlite_vm sqlite_vm;
355
356int sqlite_compile(
357 sqlite *db, /* The open database */
358 const char *zSql, /* SQL statement to be compiled */
359 const char **pzTail, /* OUT: uncompiled tail of zSql */
360 sqlite_vm **ppVm, /* OUT: the virtual machine to execute zSql */
361 char **pzErrmsg /* OUT: Error message. */
362);
363
364int sqlite_step(
365 sqlite_vm *pVm, /* The virtual machine to execute */
366 int *pN, /* OUT: Number of columns in result */
367 const char ***pazValue, /* OUT: Column data */
368 const char ***pazColName /* OUT: Column names and datatypes */
369);
370
371int sqlite_finalize(
372 sqlite_vm *pVm, /* The virtual machine to be finalized */
373 char **pzErrMsg /* OUT: Error message */
374);
375</pre></blockquote>
376
377<p>
378The strategy is to compile a single SQL statement using
379<b>sqlite_compile</b> then invoke <b>sqlite_step</b> multiple times,
380once for each row of output, and finally call <b>sqlite_finalize</b>
381to clean up after the SQL has finished execution.
382</p>
383
384<h4>2.1 Compiling An SQL Statement Into A Virtual Machine</h4>
385
386<p>
387The <b>sqlite_compile</b> "compiles" a single SQL statement (specified
388by the second parameter) and generates a virtual machine that is able
389to execute that statement.
390As with must interface routines, the first parameter must be a pointer
391to an sqlite structure that was obtained from a prior call to
392<b>sqlite_open</b>.
393
394<p>
395A pointer to the virtual machine is stored in a pointer which is passed
396in as the 4th parameter.
397Space to hold the virtual machine is dynamically allocated. To avoid
398a memory leak, the calling function must invoke
399<b>sqlite_finalize</b> on the virtual machine after it has finished
400with it.
401The 4th parameter may be set to NULL if an error is encountered during
402compilation.
403</p>
404
405<p>
406If any errors are encountered during compilation, an error message is
407written into memory obtained from <b>malloc</b> and the 5th parameter
408is made to point to that memory. If the 5th parameter is NULL, then
409no error message is generated. If the 5th parameter is not NULL, then
410the calling function should dispose of the memory containing the error
411message by calling <b>sqlite_freemem</b>.
412</p>
413
414<p>
415If the 2nd parameter actually contains two or more statements of SQL,
416only the first statement is compiled. (This is different from the
417behavior of <b>sqlite_exec</b> which executes all SQL statements
418in its input string.) The 3rd parameter to <b>sqlite_compile</b>
419is made to point to the first character beyond the end of the first
420statement of SQL in the input. If the 2nd parameter contains only
421a single SQL statement, then the 3rd parameter will be made to point
422to the '\000' terminator at the end of the 2nd parameter.
423</p>
424
425<p>
426On success, <b>sqlite_compile</b> returns SQLITE_OK.
427Otherwise and error code is returned.
428</p>
429
430<h4>2.2 Step-By-Step Execution Of An SQL Statement</h4>
431
432<p>
433After a virtual machine has been generated using <b>sqlite_compile</b>
434it is executed by one or more calls to <b>sqlite_step</b>. Each
435invocation of <b>sqlite_step</b>, except the last one,
436returns a single row of the result.
437The number of columns in the result is stored in the integer that
438the 2nd parameter points to.
439The pointer specified by the 3rd parameter is made to point
440to an array of pointers to column values.
441The pointer in the 4th parameter is made to point to an array
442of pointers to column names and datatypes.
443The 2nd through 4th parameters to <b>sqlite_step</b> convey the
444same information as the 2nd through 4th parameters of the
445<b>callback</b> routine when using
446the <b>sqlite_exec</b> interface. Except, with <b>sqlite_step</b>
447the column datatype information is always included in the in the
4484th parameter regardless of whether or not the
449<a href="pragma.html#pragma_show_datatypes">SHOW_DATATYPES</a> pragma
450is on or off.
451</p>
452
453<p>
454Each invocation of <b>sqlite_step</b> returns an integer code that
455indicates what happened during that step. This code may be
456SQLITE_BUSY, SQLITE_ROW, SQLITE_DONE, SQLITE_ERROR, or
457SQLITE_MISUSE.
458</p>
459
460<p>
461If the virtual machine is unable to open the database file because
462it is locked by another thread or process, <b>sqlite_step</b>
463will return SQLITE_BUSY. The calling function should do some other
464activity, or sleep, for a short amount of time to give the lock a
465chance to clear, then invoke <b>sqlite_step</b> again. This can
466be repeated as many times as desired.
467</p>
468
469<p>
470Whenever another row of result data is available,
471<b>sqlite_step</b> will return SQLITE_ROW. The row data is
472stored in an array of pointers to strings and the 2nd parameter
473is made to point to this array.
474</p>
475
476<p>
477When all processing is complete, <b>sqlite_step</b> will return
478either SQLITE_DONE or SQLITE_ERROR. SQLITE_DONE indicates that the
479statement completed successfully and SQLITE_ERROR indicates that there
480was a run-time error. (The details of the error are obtained from
481<b>sqlite_finalize</b>.) It is a misuse of the library to attempt
482to call <b>sqlite_step</b> again after it has returned SQLITE_DONE
483or SQLITE_ERROR.
484</p>
485
486<p>
487When <b>sqlite_step</b> returns SQLITE_DONE or SQLITE_ERROR,
488the *pN and *pazColName values are set to the number of columns
489in the result set and to the names of the columns, just as they
490are for an SQLITE_ROW return. This allows the calling code to
491find the number of result columns and the column names and datatypes
492even if the result set is empty. The *pazValue parameter is always
493set to NULL when the return codes is SQLITE_DONE or SQLITE_ERROR.
494If the SQL being executed is a statement that does not
495return a result (such as an INSERT or an UPDATE) then *pN will
496be set to zero and *pazColName will be set to NULL.
497</p>
498
499<p>
500If you abuse the library by trying to call <b>sqlite_step</b>
501inappropriately it will attempt return SQLITE_MISUSE.
502This can happen if you call sqlite_step() on the same virtual machine
503at the same
504time from two or more threads or if you call sqlite_step()
505again after it returned SQLITE_DONE or SQLITE_ERROR or if you
506pass in an invalid virtual machine pointer to sqlite_step().
507You should not depend on the SQLITE_MISUSE return code to indicate
508an error. It is possible that a misuse of the interface will go
509undetected and result in a program crash. The SQLITE_MISUSE is
510intended as a debugging aid only - to help you detect incorrect
511usage prior to a mishap. The misuse detection logic is not guaranteed
512to work in every case.
513</p>
514
515<h4>2.3 Deleting A Virtual Machine</h4>
516
517<p>
518Every virtual machine that <b>sqlite_compile</b> creates should
519eventually be handed to <b>sqlite_finalize</b>. The sqlite_finalize()
520procedure deallocates the memory and other resources that the virtual
521machine uses. Failure to call sqlite_finalize() will result in
522resource leaks in your program.
523</p>
524
525<p>
526The <b>sqlite_finalize</b> routine also returns the result code
527that indicates success or failure of the SQL operation that the
528virtual machine carried out.
529The value returned by sqlite_finalize() will be the same as would
530have been returned had the same SQL been executed by <b>sqlite_exec</b>.
531The error message returned will also be the same.
532</p>
533
534<p>
535It is acceptable to call <b>sqlite_finalize</b> on a virtual machine
536before <b>sqlite_step</b> has returned SQLITE_DONE. Doing so has
537the effect of interrupting the operation in progress. Partially completed
538changes will be rolled back and the database will be restored to its
539original state (unless an alternative recovery algorithm is selected using
540an ON CONFLICT clause in the SQL being executed.) The effect is the
541same as if a callback function of <b>sqlite_exec</b> had returned
542non-zero.
543</p>
544
545<p>
546It is also acceptable to call <b>sqlite_finalize</b> on a virtual machine
547that has never been passed to <b>sqlite_step</b> even once.
548</p>
549
550<h3>3.0 The Extended API</h3>
551
552<p>Only the three core routines described in section 1.0 are required to use
553SQLite. But there are many other functions that provide
554useful interfaces. These extended routines are as follows:
555</p>
556
557<blockquote><pre>
558int sqlite_last_insert_rowid(sqlite*);
559
560int sqlite_changes(sqlite*);
561
562int sqlite_get_table(
563 sqlite*,
564 char *sql,
565 char ***result,
566 int *nrow,
567 int *ncolumn,
568 char **errmsg
569);
570
571void sqlite_free_table(char**);
572
573void sqlite_interrupt(sqlite*);
574
575int sqlite_complete(const char *sql);
576
577void sqlite_busy_handler(sqlite*, int (*)(void*,const char*,int), void*);
578
579void sqlite_busy_timeout(sqlite*, int ms);
580
581const char sqlite_version[];
582
583const char sqlite_encoding[];
584
585int sqlite_exec_printf(
586 sqlite*,
587 char *sql,
588 int (*)(void*,int,char**,char**),
589 void*,
590 char **errmsg,
591 ...
592);
593
594int sqlite_exec_vprintf(
595 sqlite*,
596 char *sql,
597 int (*)(void*,int,char**,char**),
598 void*,
599 char **errmsg,
600 va_list
601);
602
603int sqlite_get_table_printf(
604 sqlite*,
605 char *sql,
606 char ***result,
607 int *nrow,
608 int *ncolumn,
609 char **errmsg,
610 ...
611);
612
613int sqlite_get_table_vprintf(
614 sqlite*,
615 char *sql,
616 char ***result,
617 int *nrow,
618 int *ncolumn,
619 char **errmsg,
620 va_list
621);
622
623char *sqlite_mprintf(const char *zFormat, ...);
624
625char *sqlite_vmprintf(const char *zFormat, va_list);
626
627void sqlite_freemem(char*);
628
629void sqlite_progress_handler(sqlite*, int, int (*)(void*), void*);
630
631</pre></blockquote>
632
633<p>All of the above definitions are included in the "sqlite.h"
634header file that comes in the source tree.</p>
635
636<h4>3.1 The ROWID of the most recent insert</h4>
637
638<p>Every row of an SQLite table has a unique integer key. If the
639table has a column labeled INTEGER PRIMARY KEY, then that column
640serves as the key. If there is no INTEGER PRIMARY KEY column then
641the key is a unique integer. The key for a row can be accessed in
642a SELECT statement or used in a WHERE or ORDER BY clause using any
643of the names "ROWID", "OID", or "_ROWID_".</p>
644
645<p>When you do an insert into a table that does not have an INTEGER PRIMARY
646KEY column, or if the table does have an INTEGER PRIMARY KEY but the value
647for that column is not specified in the VALUES clause of the insert, then
648the key is automatically generated. You can find the value of the key
649for the most recent INSERT statement using the
650<b>sqlite_last_insert_rowid</b> API function.</p>
651
652<h4>3.2 The number of rows that changed</h4>
653
654<p>The <b>sqlite_changes</b> API function returns the number of rows
655that have been inserted, deleted, or modified since the database was
656last quiescent. A "quiescent" database is one in which there are
657no outstanding calls to <b>sqlite_exec</b> and no VMs created by
658<b>sqlite_compile</b> that have not been finalized by <b>sqlite_finalize</b>.
659In common usage, <b>sqlite_changes</b> returns the number
660of rows inserted, deleted, or modified by the most recent <b>sqlite_exec</b>
661call or since the most recent <b>sqlite_compile</b>. But if you have
662nested calls to <b>sqlite_exec</b> (that is, if the callback routine
663of one <b>sqlite_exec</b> invokes another <b>sqlite_exec</b>) or if
664you invoke <b>sqlite_compile</b> to create a new VM while there is
665still another VM in existance, then
666the meaning of the number returned by <b>sqlite_changes</b> is more
667complex.
668The number reported includes any changes
669that were later undone by a ROLLBACK or ABORT. But rows that are
670deleted because of a DROP TABLE are <em>not</em> counted.</p>
671
672<p>SQLite implements the command "<b>DELETE FROM table</b>" (without
673a WHERE clause) by dropping the table then recreating it.
674This is much faster than deleting the elements of the table individually.
675But it also means that the value returned from <b>sqlite_changes</b>
676will be zero regardless of the number of elements that were originally
677in the table. If an accurate count of the number of elements deleted
678is necessary, use "<b>DELETE FROM table WHERE 1</b>" instead.</p>
679
680<h4>3.3 Querying into memory obtained from malloc()</h4>
681
682<p>The <b>sqlite_get_table</b> function is a wrapper around
683<b>sqlite_exec</b> that collects all the information from successive
684callbacks and writes it into memory obtained from malloc(). This
685is a convenience function that allows the application to get the
686entire result of a database query with a single function call.</p>
687
688<p>The main result from <b>sqlite_get_table</b> is an array of pointers
689to strings. There is one element in this array for each column of
690each row in the result. NULL results are represented by a NULL
691pointer. In addition to the regular data, there is an added row at the
692beginning of the array that contains the name of each column of the
693result.</p>
694
695<p>As an example, consider the following query:</p>
696
697<blockquote>
698SELECT employee_name, login, host FROM users WHERE login LIKE 'd%';
699</blockquote>
700
701<p>This query will return the name, login and host computer name
702for every employee whose login begins with the letter "d". If this
703query is submitted to <b>sqlite_get_table</b> the result might
704look like this:</p>
705
706<blockquote>
707nrow = 2<br>
708ncolumn = 3<br>
709result[0] = "employee_name"<br>
710result[1] = "login"<br>
711result[2] = "host"<br>
712result[3] = "dummy"<br>
713result[4] = "No such user"<br>
714result[5] = 0<br>
715result[6] = "D. Richard Hipp"<br>
716result[7] = "drh"<br>
717result[8] = "zadok"
718</blockquote>
719
720<p>Notice that the "host" value for the "dummy" record is NULL so
721the result[] array contains a NULL pointer at that slot.</p>
722
723<p>If the result set of a query is empty, then by default
724<b>sqlite_get_table</b> will set nrow to 0 and leave its
725result parameter is set to NULL. But if the EMPTY_RESULT_CALLBACKS
726pragma is ON then the result parameter is initialized to the names
727of the columns only. For example, consider this query which has
728an empty result set:</p>
729
730<blockquote>
731SELECT employee_name, login, host FROM users WHERE employee_name IS NULL;
732</blockquote>
733
734<p>
735The default behavior gives this results:
736</p>
737
738<blockquote>
739nrow = 0<br>
740ncolumn = 0<br>
741result = 0<br>
742</blockquote>
743
744<p>
745But if the EMPTY_RESULT_CALLBACKS pragma is ON, then the following
746is returned:
747</p>
748
749<blockquote>
750nrow = 0<br>
751ncolumn = 3<br>
752result[0] = "employee_name"<br>
753result[1] = "login"<br>
754result[2] = "host"<br>
755</blockquote>
756
757<p>Memory to hold the information returned by <b>sqlite_get_table</b>
758is obtained from malloc(). But the calling function should not try
759to free this information directly. Instead, pass the complete table
760to <b>sqlite_free_table</b> when the table is no longer needed.
761It is safe to call <b>sqlite_free_table</b> with a NULL pointer such
762as would be returned if the result set is empty.</p>
763
764<p>The <b>sqlite_get_table</b> routine returns the same integer
765result code as <b>sqlite_exec</b>.</p>
766
767<h4>3.4 Interrupting an SQLite operation</h4>
768
769<p>The <b>sqlite_interrupt</b> function can be called from a
770different thread or from a signal handler to cause the current database
771operation to exit at its first opportunity. When this happens,
772the <b>sqlite_exec</b> routine (or the equivalent) that started
773the database operation will return SQLITE_INTERRUPT.</p>
774
775<h4>3.5 Testing for a complete SQL statement</h4>
776
777<p>The next interface routine to SQLite is a convenience function used
778to test whether or not a string forms a complete SQL statement.
779If the <b>sqlite_complete</b> function returns true when its input
780is a string, then the argument forms a complete SQL statement.
781There are no guarantees that the syntax of that statement is correct,
782but we at least know the statement is complete. If <b>sqlite_complete</b>
783returns false, then more text is required to complete the SQL statement.</p>
784
785<p>For the purpose of the <b>sqlite_complete</b> function, an SQL
786statement is complete if it ends in a semicolon.</p>
787
788<p>The <b>sqlite</b> command-line utility uses the <b>sqlite_complete</b>
789function to know when it needs to call <b>sqlite_exec</b>. After each
790line of input is received, <b>sqlite</b> calls <b>sqlite_complete</b>
791on all input in its buffer. If <b>sqlite_complete</b> returns true,
792then <b>sqlite_exec</b> is called and the input buffer is reset. If
793<b>sqlite_complete</b> returns false, then the prompt is changed to
794the continuation prompt and another line of text is read and added to
795the input buffer.</p>
796
797<h4>3.6 Library version string</h4>
798
799<p>The SQLite library exports the string constant named
800<b>sqlite_version</b> which contains the version number of the
801library. The header file contains a macro SQLITE_VERSION
802with the same information. If desired, a program can compare
803the SQLITE_VERSION macro against the <b>sqlite_version</b>
804string constant to verify that the version number of the
805header file and the library match.</p>
806
807<h4>3.7 Library character encoding</h4>
808
809<p>By default, SQLite assumes that all data uses a fixed-size
8108-bit character (iso8859). But if you give the --enable-utf8 option
811to the configure script, then the library assumes UTF-8 variable
812sized characters. This makes a difference for the LIKE and GLOB
813operators and the LENGTH() and SUBSTR() functions. The static
814string <b>sqlite_encoding</b> will be set to either "UTF-8" or
815"iso8859" to indicate how the library was compiled. In addition,
816the <b>sqlite.h</b> header file will define one of the
817macros <b>SQLITE_UTF8</b> or <b>SQLITE_ISO8859</b>, as appropriate.</p>
818
819<p>Note that the character encoding mechanism used by SQLite cannot
820be changed at run-time. This is a compile-time option only. The
821<b>sqlite_encoding</b> character string just tells you how the library
822was compiled.</p>
823
824<h4>3.8 Changing the library's response to locked files</h4>
825
826<p>The <b>sqlite_busy_handler</b> procedure can be used to register
827a busy callback with an open SQLite database. The busy callback will
828be invoked whenever SQLite tries to access a database that is locked.
829The callback will typically do some other useful work, or perhaps sleep,
830in order to give the lock a chance to clear. If the callback returns
831non-zero, then SQLite tries again to access the database and the cycle
832repeats. If the callback returns zero, then SQLite aborts the current
833operation and returns SQLITE_BUSY.</p>
834
835<p>The arguments to <b>sqlite_busy_handler</b> are the opaque
836structure returned from <b>sqlite_open</b>, a pointer to the busy
837callback function, and a generic pointer that will be passed as
838the first argument to the busy callback. When SQLite invokes the
839busy callback, it sends it three arguments: the generic pointer
840that was passed in as the third argument to <b>sqlite_busy_handler</b>,
841the name of the database table or index that the library is trying
842to access, and the number of times that the library has attempted to
843access the database table or index.</p>
844
845<p>For the common case where we want the busy callback to sleep,
846the SQLite library provides a convenience routine <b>sqlite_busy_timeout</b>.
847The first argument to <b>sqlite_busy_timeout</b> is a pointer to
848an open SQLite database and the second argument is a number of milliseconds.
849After <b>sqlite_busy_timeout</b> has been executed, the SQLite library
850will wait for the lock to clear for at least the number of milliseconds
851specified before it returns SQLITE_BUSY. Specifying zero milliseconds for
852the timeout restores the default behavior.</p>
853
854<h4>3.9 Using the <tt>_printf()</tt> wrapper functions</h4>
855
856<p>The four utility functions</p>
857
858<p>
859<ul>
860<li><b>sqlite_exec_printf()</b></li>
861<li><b>sqlite_exec_vprintf()</b></li>
862<li><b>sqlite_get_table_printf()</b></li>
863<li><b>sqlite_get_table_vprintf()</b></li>
864</ul>
865</p>
866
867<p>implement the same query functionality as <b>sqlite_exec</b>
868and <b>sqlite_get_table</b>. But instead of taking a complete
869SQL statement as their second argument, the four <b>_printf</b>
870routines take a printf-style format string. The SQL statement to
871be executed is generated from this format string and from whatever
872additional arguments are attached to the end of the function call.</p>
873
874<p>There are two advantages to using the SQLite printf
875functions instead of <b>sprintf</b>. First of all, with the
876SQLite printf routines, there is never a danger of overflowing a
877static buffer as there is with <b>sprintf</b>. The SQLite
878printf routines automatically allocate (and later frees)
879as much memory as is
880necessary to hold the SQL statements generated.</p>
881
882<p>The second advantage the SQLite printf routines have over
883<b>sprintf</b> are two new formatting options specifically designed
884to support string literals in SQL. Within the format string,
885the %q formatting option works very much like %s in that it
886reads a null-terminated string from the argument list and inserts
887it into the result. But %q translates the inserted string by
888making two copies of every single-quote (') character in the
889substituted string. This has the effect of escaping the end-of-string
890meaning of single-quote within a string literal. The %Q formatting
891option works similar; it translates the single-quotes like %q and
892additionally encloses the resulting string in single-quotes.
893If the argument for the %Q formatting options is a NULL pointer,
894the resulting string is NULL without single quotes.
895</p>
896
897<p>Consider an example. Suppose you are trying to insert a string
898value into a database table where the string value was obtained from
899user input. Suppose the string to be inserted is stored in a variable
900named zString. The code to do the insertion might look like this:</p>
901
902<blockquote><pre>
903sqlite_exec_printf(db,
904 "INSERT INTO table1 VALUES('%s')",
905 0, 0, 0, zString);
906</pre></blockquote>
907
908<p>If the zString variable holds text like "Hello", then this statement
909will work just fine. But suppose the user enters a string like
910"Hi y'all!". The SQL statement generated reads as follows:
911
912<blockquote><pre>
913INSERT INTO table1 VALUES('Hi y'all')
914</pre></blockquote>
915
916<p>This is not valid SQL because of the apostrophy in the word "y'all".
917But if the %q formatting option is used instead of %s, like this:</p>
918
919<blockquote><pre>
920sqlite_exec_printf(db,
921 "INSERT INTO table1 VALUES('%q')",
922 0, 0, 0, zString);
923</pre></blockquote>
924
925<p>Then the generated SQL will look like the following:</p>
926
927<blockquote><pre>
928INSERT INTO table1 VALUES('Hi y''all')
929</pre></blockquote>
930
931<p>Here the apostrophy has been escaped and the SQL statement is well-formed.
932When generating SQL on-the-fly from data that might contain a
933single-quote character ('), it is always a good idea to use the
934SQLite printf routines and the %q formatting option instead of <b>sprintf</b>.
935</p>
936
937<p>If the %Q formatting option is used instead of %q, like this:</p>
938
939<blockquote><pre>
940sqlite_exec_printf(db,
941 "INSERT INTO table1 VALUES(%Q)",
942 0, 0, 0, zString);
943</pre></blockquote>
944
945<p>Then the generated SQL will look like the following:</p>
946
947<blockquote><pre>
948INSERT INTO table1 VALUES('Hi y''all')
949</pre></blockquote>
950
951<p>If the value of the zString variable is NULL, the generated SQL
952will look like the following:</p>
953
954<blockquote><pre>
955INSERT INTO table1 VALUES(NULL)
956</pre></blockquote>
957
958<p>All of the _printf() routines above are built around the following
959two functions:</p>
960
961<blockquote><pre>
962char *sqlite_mprintf(const char *zFormat, ...);
963char *sqlite_vmprintf(const char *zFormat, va_list);
964</pre></blockquote>
965
966<p>The <b>sqlite_mprintf()</b> routine works like the the standard library
967<b>sprintf()</b> except that it writes its results into memory obtained
968from malloc() and returns a pointer to the malloced buffer.
969<b>sqlite_mprintf()</b> also understands the %q and %Q extensions described
970above. The <b>sqlite_vmprintf()</b> is a varargs version of the same
971routine. The string pointer that these routines return should be freed
972by passing it to <b>sqlite_freemem()</b>.
973</p>
974
975<h4>3.10 Performing background jobs during large queries</h3>
976
977<p>The <b>sqlite_progress_handler()</b> routine can be used to register a
978callback routine with an SQLite database to be invoked periodically during long
979running calls to <b>sqlite_exec()</b>, <b>sqlite_step()</b> and the various
980wrapper functions.
981</p>
982
983<p>The callback is invoked every N virtual machine operations, where N is
984supplied as the second argument to <b>sqlite_progress_handler()</b>. The third
985and fourth arguments to <b>sqlite_progress_handler()</b> are a pointer to the
986routine to be invoked and a void pointer to be passed as the first argument to
987it.
988</p>
989
990<p>The time taken to execute each virtual machine operation can vary based on
991many factors. A typical value for a 1 GHz PC is between half and three million
992per second but may be much higher or lower, depending on the query. As such it
993is difficult to schedule background operations based on virtual machine
994operations. Instead, it is recommended that a callback be scheduled relatively
995frequently (say every 1000 instructions) and external timer routines used to
996determine whether or not background jobs need to be run.
997</p>
998
999<a name="cfunc">
1000<h3>4.0 Adding New SQL Functions</h3>
1001
1002<p>Beginning with version 2.4.0, SQLite allows the SQL language to be
1003extended with new functions implemented as C code. The following interface
1004is used:
1005</p>
1006
1007<blockquote><pre>
1008typedef struct sqlite_func sqlite_func;
1009
1010int sqlite_create_function(
1011 sqlite *db,
1012 const char *zName,
1013 int nArg,
1014 void (*xFunc)(sqlite_func*,int,const char**),
1015 void *pUserData
1016);
1017int sqlite_create_aggregate(
1018 sqlite *db,
1019 const char *zName,
1020 int nArg,
1021 void (*xStep)(sqlite_func*,int,const char**),
1022 void (*xFinalize)(sqlite_func*),
1023 void *pUserData
1024);
1025
1026char *sqlite_set_result_string(sqlite_func*,const char*,int);
1027void sqlite_set_result_int(sqlite_func*,int);
1028void sqlite_set_result_double(sqlite_func*,double);
1029void sqlite_set_result_error(sqlite_func*,const char*,int);
1030
1031void *sqlite_user_data(sqlite_func*);
1032void *sqlite_aggregate_context(sqlite_func*, int nBytes);
1033int sqlite_aggregate_count(sqlite_func*);
1034</pre></blockquote>
1035
1036<p>
1037The <b>sqlite_create_function()</b> interface is used to create
1038regular functions and <b>sqlite_create_aggregate()</b> is used to
1039create new aggregate functions. In both cases, the <b>db</b>
1040parameter is an open SQLite database on which the functions should
1041be registered, <b>zName</b> is the name of the new function,
1042<b>nArg</b> is the number of arguments, and <b>pUserData</b> is
1043a pointer which is passed through unchanged to the C implementation
1044of the function. Both routines return 0 on success and non-zero
1045if there are any errors.
1046</p>
1047
1048<p>
1049The length of a function name may not exceed 255 characters.
1050Any attempt to create a function whose name exceeds 255 characters
1051in length will result in an error.
1052</p>
1053
1054<p>
1055For regular functions, the <b>xFunc</b> callback is invoked once
1056for each function call. The implementation of xFunc should call
1057one of the <b>sqlite_set_result_...</b> interfaces to return its
1058result. The <b>sqlite_user_data()</b> routine can be used to
1059retrieve the <b>pUserData</b> pointer that was passed in when the
1060function was registered.
1061</p>
1062
1063<p>
1064For aggregate functions, the <b>xStep</b> callback is invoked once
1065for each row in the result and then <b>xFinalize</b> is invoked at the
1066end to compute a final answer. The xStep routine can use the
1067<b>sqlite_aggregate_context()</b> interface to allocate memory that
1068will be unique to that particular instance of the SQL function.
1069This memory will be automatically deleted after xFinalize is called.
1070The <b>sqlite_aggregate_count()</b> routine can be used to find out
1071how many rows of data were passed to the aggregate. The xFinalize
1072callback should invoke one of the <b>sqlite_set_result_...</b>
1073interfaces to set the final result of the aggregate.
1074</p>
1075
1076<p>
1077SQLite now implements all of its built-in functions using this
1078interface. For additional information and examples on how to create
1079new SQL functions, review the SQLite source code in the file
1080<b>func.c</b>.
1081</p>
1082
1083<h3>5.0 Multi-Threading And SQLite</h3>
1084
1085<p>
1086If SQLite is compiled with the THREADSAFE preprocessor macro set to 1,
1087then it is safe to use SQLite from two or more threads of the same process
1088at the same time. But each thread should have its own <b>sqlite*</b>
1089pointer returned from <b>sqlite_open</b>. It is never safe for two
1090or more threads to access the same <b>sqlite*</b> pointer at the same time.
1091</p>
1092
1093<p>
1094In precompiled SQLite libraries available on the website, the Unix
1095versions are compiled with THREADSAFE turned off but the windows
1096versions are compiled with THREADSAFE turned on. If you need something
1097different that this you will have to recompile.
1098</p>
1099
1100<p>
1101Under Unix, an <b>sqlite*</b> pointer should not be carried across a
1102<b>fork()</b> system call into the child process. The child process
1103should open its own copy of the database after the <b>fork()</b>.
1104</p>
1105
1106<h3>6.0 Usage Examples</h3>
1107
1108<p>For examples of how the SQLite C/C++ interface can be used,
1109refer to the source code for the <b>sqlite</b> program in the
1110file <b>src/shell.c</b> of the source tree.
1111Additional information about sqlite is available at
1112<a href="sqlite.html">sqlite.html</a>.
1113See also the sources to the Tcl interface for SQLite in
1114the source file <b>src/tclsqlite.c</b>.</p>
1115}
1116footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/capi3.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/capi3.tcl
deleted file mode 100644
index 149cf7f..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/capi3.tcl
+++ /dev/null
@@ -1,516 +0,0 @@
1set rcsid {$Id: capi3.tcl,v 1.10 2007/04/27 17:16:22 drh Exp $}
2source common.tcl
3header {C/C++ Interface For SQLite Version 3}
4
5proc AddHyperlinks {txt} {
6 regsub -all {([^:alnum:>])(sqlite3_\w+)(\([^\)]*\))} $txt \
7 {\1<a href="capi3ref.html#\2">\2</a>\3} t2
8 puts $t2
9}
10
11AddHyperlinks {
12<h2>C/C++ Interface For SQLite Version 3</h2>
13
14<h3>1.0 Overview</h3>
15
16<p>
17SQLite version 3.0 is a new version of SQLite, derived from
18the SQLite 2.8.13 code base, but with an incompatible file format
19and API.
20SQLite version 3.0 was created to answer demand for the following features:
21</p>
22
23<ul>
24<li>Support for UTF-16.</li>
25<li>User-definable text collating sequences.</li>
26<li>The ability to store BLOBs in indexed columns.</li>
27</ul>
28
29<p>
30It was necessary to move to version 3.0 to implement these features because
31each requires incompatible changes to the database file format. Other
32incompatible changes, such as a cleanup of the API, were introduced at the
33same time under the theory that it is best to get your incompatible changes
34out of the way all at once.
35</p>
36
37<p>
38The API for version 3.0 is similar to the version 2.X API,
39but with some important changes. Most noticeably, the "<tt>sqlite_</tt>"
40prefix that occurs on the beginning of all API functions and data
41structures are changed to "<tt>sqlite3_</tt>".
42This avoids confusion between the two APIs and allows linking against both
43SQLite 2.X and SQLite 3.0 at the same time.
44</p>
45
46<p>
47There is no agreement on what the C datatype for a UTF-16
48string should be. Therefore, SQLite uses a generic type of void*
49to refer to UTF-16 strings. Client software can cast the void*
50to whatever datatype is appropriate for their system.
51</p>
52
53<h3>2.0 C/C++ Interface</h3>
54
55<p>
56The API for SQLite 3.0 includes 83 separate functions in addition
57to several data structures and #defines. (A complete
58<a href="capi3ref.html">API reference</a> is provided as a separate document.)
59Fortunately, the interface is not nearly as complex as its size implies.
60Simple programs can still make do with only 3 functions:
61<a href="capi3ref.html#sqlite3_open">sqlite3_open()</a>,
62<a href="capi3ref.html#sqlite3_exec">sqlite3_exec()</a>, and
63<a href="capi3ref.html#sqlite3_close">sqlite3_close()</a>.
64More control over the execution of the database engine is provided
65using
66<a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a>
67to compile an SQLite statement into byte code and
68<a href="capi3ref.html#sqlite3_prepare">sqlite3_step()</a>
69to execute that bytecode.
70A family of routines with names beginning with
71<a href="capi3ref.html#sqlite3_column_blob">sqlite3_column_</a>
72is used to extract information about the result set of a query.
73Many interface functions come in pairs, with both a UTF-8 and
74UTF-16 version. And there is a collection of routines
75used to implement user-defined SQL functions and user-defined
76text collating sequences.
77</p>
78
79
80<h4>2.1 Opening and closing a database</h4>
81
82<blockquote><pre>
83 typedef struct sqlite3 sqlite3;
84 int sqlite3_open(const char*, sqlite3**);
85 int sqlite3_open16(const void*, sqlite3**);
86 int sqlite3_close(sqlite3*);
87 const char *sqlite3_errmsg(sqlite3*);
88 const void *sqlite3_errmsg16(sqlite3*);
89 int sqlite3_errcode(sqlite3*);
90</pre></blockquote>
91
92<p>
93The sqlite3_open() routine returns an integer error code rather than
94a pointer to the sqlite3 structure as the version 2 interface did.
95The difference between sqlite3_open()
96and sqlite3_open16() is that sqlite3_open16() takes UTF-16 (in host native
97byte order) for the name of the database file. If a new database file
98needs to be created, then sqlite3_open16() sets the internal text
99representation to UTF-16 whereas sqlite3_open() sets the text
100representation to UTF-8.
101</p>
102
103<p>
104The opening and/or creating of the database file is deferred until the
105file is actually needed. This allows options and parameters, such
106as the native text representation and default page size, to be
107set using PRAGMA statements.
108</p>
109
110<p>
111The sqlite3_errcode() routine returns a result code for the most
112recent major API call. sqlite3_errmsg() returns an English-language
113text error message for the most recent error. The error message is
114represented in UTF-8 and will be ephemeral - it could disappear on
115the next call to any SQLite API function. sqlite3_errmsg16() works like
116sqlite3_errmsg() except that it returns the error message represented
117as UTF-16 in host native byte order.
118</p>
119
120<p>
121The error codes for SQLite version 3 are unchanged from version 2.
122They are as follows:
123</p>
124
125<blockquote><pre>
126#define SQLITE_OK 0 /* Successful result */
127#define SQLITE_ERROR 1 /* SQL error or missing database */
128#define SQLITE_INTERNAL 2 /* An internal logic error in SQLite */
129#define SQLITE_PERM 3 /* Access permission denied */
130#define SQLITE_ABORT 4 /* Callback routine requested an abort */
131#define SQLITE_BUSY 5 /* The database file is locked */
132#define SQLITE_LOCKED 6 /* A table in the database is locked */
133#define SQLITE_NOMEM 7 /* A malloc() failed */
134#define SQLITE_READONLY 8 /* Attempt to write a readonly database */
135#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite_interrupt() */
136#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
137#define SQLITE_CORRUPT 11 /* The database disk image is malformed */
138#define SQLITE_NOTFOUND 12 /* (Internal Only) Table or record not found */
139#define SQLITE_FULL 13 /* Insertion failed because database is full */
140#define SQLITE_CANTOPEN 14 /* Unable to open the database file */
141#define SQLITE_PROTOCOL 15 /* Database lock protocol error */
142#define SQLITE_EMPTY 16 /* (Internal Only) Database table is empty */
143#define SQLITE_SCHEMA 17 /* The database schema changed */
144#define SQLITE_TOOBIG 18 /* Too much data for one row of a table */
145#define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */
146#define SQLITE_MISMATCH 20 /* Data type mismatch */
147#define SQLITE_MISUSE 21 /* Library used incorrectly */
148#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
149#define SQLITE_AUTH 23 /* Authorization denied */
150#define SQLITE_ROW 100 /* sqlite_step() has another row ready */
151#define SQLITE_DONE 101 /* sqlite_step() has finished executing */
152</pre></blockquote>
153
154<h4>2.2 Executing SQL statements</h4>
155
156<blockquote><pre>
157 typedef int (*sqlite_callback)(void*,int,char**, char**);
158 int sqlite3_exec(sqlite3*, const char *sql, sqlite_callback, void*, char**);
159</pre></blockquote>
160
161<p>
162The sqlite3_exec function works much as it did in SQLite version 2.
163Zero or more SQL statements specified in the second parameter are compiled
164and executed. Query results are returned to a callback routine.
165See the <a href="capi3ref.html#sqlite3_exec">API reference</a> for additional
166information.
167</p>
168
169<p>
170In SQLite version 3, the sqlite3_exec routine is just a wrapper around
171calls to the prepared statement interface.
172</p>
173
174<blockquote><pre>
175 typedef struct sqlite3_stmt sqlite3_stmt;
176 int sqlite3_prepare(sqlite3*, const char*, int, sqlite3_stmt**, const char**);
177 int sqlite3_prepare16(sqlite3*, const void*, int, sqlite3_stmt**, const void**);
178 int sqlite3_finalize(sqlite3_stmt*);
179 int sqlite3_reset(sqlite3_stmt*);
180</pre></blockquote>
181
182<p>
183The sqlite3_prepare interface compiles a single SQL statement into byte code
184for later execution. This interface is now the preferred way of accessing
185the database.
186</p>
187
188<p>
189The SQL statement is a UTF-8 string for sqlite3_prepare().
190The sqlite3_prepare16() works the same way except
191that it expects a UTF-16 string as SQL input.
192Only the first SQL statement in the input string is compiled.
193The fourth parameter is filled in with a pointer to the next (uncompiled)
194SQLite statement in the input string, if any.
195The sqlite3_finalize() routine deallocates a prepared SQL statement.
196All prepared statements must be finalized before the database can be
197closed.
198The sqlite3_reset() routine resets a prepared SQL statement so that it
199can be executed again.
200</p>
201
202<p>
203The SQL statement may contain tokens of the form "?" or "?nnn" or ":aaa"
204where "nnn" is an integer and "aaa" is an identifier.
205Such tokens represent unspecified literal values (or "wildcards")
206to be filled in later by the
207<a href="capi3ref.html#sqlite3_bind_blob">sqlite3_bind</a> interface.
208Each wildcard has an associated number which is its sequence in the
209statement or the "nnn" in the case of a "?nnn" form.
210It is allowed for the same wildcard
211to occur more than once in the same SQL statement, in which case
212all instance of that wildcard will be filled in with the same value.
213Unbound wildcards have a value of NULL.
214</p>
215
216<blockquote><pre>
217 int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
218 int sqlite3_bind_double(sqlite3_stmt*, int, double);
219 int sqlite3_bind_int(sqlite3_stmt*, int, int);
220 int sqlite3_bind_int64(sqlite3_stmt*, int, long long int);
221 int sqlite3_bind_null(sqlite3_stmt*, int);
222 int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
223 int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
224 int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
225</pre></blockquote>
226
227<p>
228There is an assortment of sqlite3_bind routines used to assign values
229to wildcards in a prepared SQL statement. Unbound wildcards
230are interpreted as NULLs. Bindings are not reset by sqlite3_reset().
231But wildcards can be rebound to new values after an sqlite3_reset().
232</p>
233
234<p>
235After an SQL statement has been prepared (and optionally bound), it
236is executed using:
237</p>
238
239<blockquote><pre>
240 int sqlite3_step(sqlite3_stmt*);
241</pre></blockquote>
242
243<p>
244The sqlite3_step() routine return SQLITE_ROW if it is returning a single
245row of the result set, or SQLITE_DONE if execution has completed, either
246normally or due to an error. It might also return SQLITE_BUSY if it is
247unable to open the database file. If the return value is SQLITE_ROW, then
248the following routines can be used to extract information about that row
249of the result set:
250</p>
251
252<blockquote><pre>
253 const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
254 int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
255 int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
256 int sqlite3_column_count(sqlite3_stmt*);
257 const char *sqlite3_column_decltype(sqlite3_stmt *, int iCol);
258 const void *sqlite3_column_decltype16(sqlite3_stmt *, int iCol);
259 double sqlite3_column_double(sqlite3_stmt*, int iCol);
260 int sqlite3_column_int(sqlite3_stmt*, int iCol);
261 long long int sqlite3_column_int64(sqlite3_stmt*, int iCol);
262 const char *sqlite3_column_name(sqlite3_stmt*, int iCol);
263 const void *sqlite3_column_name16(sqlite3_stmt*, int iCol);
264 const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
265 const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
266 int sqlite3_column_type(sqlite3_stmt*, int iCol);
267</pre></blockquote>
268
269<p>
270The
271<a href="capi3ref.html#sqlite3_column_count">sqlite3_column_count()</a>
272function returns the number of columns in
273the results set. sqlite3_column_count() can be called at any time after
274sqlite3_prepare().
275<a href="capi3ref.html#sqlite3_data_count">sqlite3_data_count()</a>
276works similarly to
277sqlite3_column_count() except that it only works following sqlite3_step().
278If the previous call to sqlite3_step() returned SQLITE_DONE or an error code,
279then sqlite3_data_count() will return 0 whereas sqlite3_column_count() will
280continue to return the number of columns in the result set.
281</p>
282
283<p>Returned data is examined using the other sqlite3_column_***() functions,
284all of which take a column number as their second parameter. Columns are
285zero-indexed from left to right. Note that this is different to parameters,
286which are indexed starting at one.
287</p>
288
289<p>
290The sqlite3_column_type() function returns the
291datatype for the value in the Nth column. The return value is one
292of these:
293</p>
294
295<blockquote><pre>
296 #define SQLITE_INTEGER 1
297 #define SQLITE_FLOAT 2
298 #define SQLITE_TEXT 3
299 #define SQLITE_BLOB 4
300 #define SQLITE_NULL 5
301</pre></blockquote>
302
303<p>
304The sqlite3_column_decltype() routine returns text which is the
305declared type of the column in the CREATE TABLE statement. For an
306expression, the return type is an empty string. sqlite3_column_name()
307returns the name of the Nth column. sqlite3_column_bytes() returns
308the number of bytes in a column that has type BLOB or the number of bytes
309in a TEXT string with UTF-8 encoding. sqlite3_column_bytes16() returns
310the same value for BLOBs but for TEXT strings returns the number of bytes
311in a UTF-16 encoding.
312sqlite3_column_blob() return BLOB data.
313sqlite3_column_text() return TEXT data as UTF-8.
314sqlite3_column_text16() return TEXT data as UTF-16.
315sqlite3_column_int() return INTEGER data in the host machines native
316integer format.
317sqlite3_column_int64() returns 64-bit INTEGER data.
318Finally, sqlite3_column_double() return floating point data.
319</p>
320
321<p>
322It is not necessary to retrieve data in the format specify by
323sqlite3_column_type(). If a different format is requested, the data
324is converted automatically.
325</p>
326
327<p>
328Data format conversions can invalidate the pointer returned by
329prior calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
330sqlite3_column_text16(). Pointers might be invalided in the following
331cases:
332</p>
333<ul>
334<li><p>
335The initial content is a BLOB and sqlite3_column_text()
336or sqlite3_column_text16()
337is called. A zero-terminator might need to be added to the string.
338</p></li>
339<li><p>
340The initial content is UTF-8 text and sqlite3_column_bytes16() or
341sqlite3_column_text16() is called. The content must be converted to UTF-16.
342</p></li>
343<li><p>
344The initial content is UTF-16 text and sqlite3_column_bytes() or
345sqlite3_column_text() is called. The content must be converted to UTF-8.
346</p></li>
347</ul>
348<p>
349Note that conversions between UTF-16be and UTF-16le
350are always done in place and do
351not invalidate a prior pointer, though of course the content of the buffer
352that the prior pointer points to will have been modified. Other kinds
353of conversion are done in place when it is possible, but sometime it is
354not possible and in those cases prior pointers are invalidated.
355</p>
356
357<p>
358The safest and easiest to remember policy is this: assume that any
359result from
360<ul>
361<li>sqlite3_column_blob(),</li>
362<li>sqlite3_column_text(), or</li>
363<li>sqlite3_column_text16()</li>
364</ul>
365is invalided by subsequent calls to
366<ul>
367<li>sqlite3_column_bytes(),</li>
368<li>sqlite3_column_bytes16(),</li>
369<li>sqlite3_column_text(), or</li>
370<li>sqlite3_column_text16().</li>
371</ul>
372This means that you should always call sqlite3_column_bytes() or
373sqlite3_column_bytes16() <u>before</u> calling sqlite3_column_blob(),
374sqlite3_column_text(), or sqlite3_column_text16().
375</p>
376
377<h4>2.3 User-defined functions</h4>
378
379<p>
380User defined functions can be created using the following routine:
381</p>
382
383<blockquote><pre>
384 typedef struct sqlite3_value sqlite3_value;
385 int sqlite3_create_function(
386 sqlite3 *,
387 const char *zFunctionName,
388 int nArg,
389 int eTextRep,
390 void*,
391 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
392 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
393 void (*xFinal)(sqlite3_context*)
394 );
395 int sqlite3_create_function16(
396 sqlite3*,
397 const void *zFunctionName,
398 int nArg,
399 int eTextRep,
400 void*,
401 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
402 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
403 void (*xFinal)(sqlite3_context*)
404 );
405 #define SQLITE_UTF8 1
406 #define SQLITE_UTF16 2
407 #define SQLITE_UTF16BE 3
408 #define SQLITE_UTF16LE 4
409 #define SQLITE_ANY 5
410</pre></blockquote>
411
412<p>
413The nArg parameter specifies the number of arguments to the function.
414A value of 0 indicates that any number of arguments is allowed. The
415eTextRep parameter specifies what representation text values are expected
416to be in for arguments to this function. The value of this parameter should
417be one of the parameters defined above. SQLite version 3 allows multiple
418implementations of the same function using different text representations.
419The database engine chooses the function that minimization the number
420of text conversions required.
421</p>
422
423<p>
424Normal functions specify only xFunc and leave xStep and xFinal set to NULL.
425Aggregate functions specify xStep and xFinal and leave xFunc set to NULL.
426There is no separate sqlite3_create_aggregate() API.
427</p>
428
429<p>
430The function name is specified in UTF-8. A separate sqlite3_create_function16()
431API works the same as sqlite_create_function()
432except that the function name is specified in UTF-16 host byte order.
433</p>
434
435<p>
436Notice that the parameters to functions are now pointers to sqlite3_value
437structures instead of pointers to strings as in SQLite version 2.X.
438The following routines are used to extract useful information from these
439"values":
440</p>
441
442<blockquote><pre>
443 const void *sqlite3_value_blob(sqlite3_value*);
444 int sqlite3_value_bytes(sqlite3_value*);
445 int sqlite3_value_bytes16(sqlite3_value*);
446 double sqlite3_value_double(sqlite3_value*);
447 int sqlite3_value_int(sqlite3_value*);
448 long long int sqlite3_value_int64(sqlite3_value*);
449 const unsigned char *sqlite3_value_text(sqlite3_value*);
450 const void *sqlite3_value_text16(sqlite3_value*);
451 int sqlite3_value_type(sqlite3_value*);
452</pre></blockquote>
453
454<p>
455Function implementations use the following APIs to acquire context and
456to report results:
457</p>
458
459<blockquote><pre>
460 void *sqlite3_aggregate_context(sqlite3_context*, int nbyte);
461 void *sqlite3_user_data(sqlite3_context*);
462 void sqlite3_result_blob(sqlite3_context*, const void*, int n, void(*)(void*));
463 void sqlite3_result_double(sqlite3_context*, double);
464 void sqlite3_result_error(sqlite3_context*, const char*, int);
465 void sqlite3_result_error16(sqlite3_context*, const void*, int);
466 void sqlite3_result_int(sqlite3_context*, int);
467 void sqlite3_result_int64(sqlite3_context*, long long int);
468 void sqlite3_result_null(sqlite3_context*);
469 void sqlite3_result_text(sqlite3_context*, const char*, int n, void(*)(void*));
470 void sqlite3_result_text16(sqlite3_context*, const void*, int n, void(*)(void*));
471 void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
472 void *sqlite3_get_auxdata(sqlite3_context*, int);
473 void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*));
474</pre></blockquote>
475
476<h4>2.4 User-defined collating sequences</h4>
477
478<p>
479The following routines are used to implement user-defined
480collating sequences:
481</p>
482
483<blockquote><pre>
484 sqlite3_create_collation(sqlite3*, const char *zName, int eTextRep, void*,
485 int(*xCompare)(void*,int,const void*,int,const void*));
486 sqlite3_create_collation16(sqlite3*, const void *zName, int eTextRep, void*,
487 int(*xCompare)(void*,int,const void*,int,const void*));
488 sqlite3_collation_needed(sqlite3*, void*,
489 void(*)(void*,sqlite3*,int eTextRep,const char*));
490 sqlite3_collation_needed16(sqlite3*, void*,
491 void(*)(void*,sqlite3*,int eTextRep,const void*));
492</pre></blockquote>
493
494<p>
495The sqlite3_create_collation() function specifies a collating sequence name
496and a comparison function to implement that collating sequence. The
497comparison function is only used for comparing text values. The eTextRep
498parameter is one of SQLITE_UTF8, SQLITE_UTF16LE, SQLITE_UTF16BE, or
499SQLITE_ANY to specify which text representation the comparison function works
500with. Separate comparison functions can exist for the same collating
501sequence for each of the UTF-8, UTF-16LE and UTF-16BE text representations.
502The sqlite3_create_collation16() works like sqlite3_create_collation() except
503that the collation name is specified in UTF-16 host byte order instead of
504in UTF-8.
505</p>
506
507<p>
508The sqlite3_collation_needed() routine registers a callback which the
509database engine will invoke if it encounters an unknown collating sequence.
510The callback can lookup an appropriate comparison function and invoke
511sqlite_3_create_collation() as needed. The fourth parameter to the callback
512is the name of the collating sequence in UTF-8. For sqlite3_collation_need16()
513the callback sends the collating sequence name in UTF-16 host byte order.
514</p>
515}
516footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/changes.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/changes.tcl
deleted file mode 100644
index df697ad..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/changes.tcl
+++ /dev/null
@@ -1,1866 +0,0 @@
1#
2# Run this script to generated a changes.html output file
3#
4source common.tcl
5header {SQLite changes}
6puts {
7<p>
8This page provides a high-level summary of changes to SQLite.
9For more detail, refer the the checkin logs generated by
10CVS at
11<a href="http://www.sqlite.org/cvstrac/timeline">
12http://www.sqlite.org/cvstrac/timeline</a>.
13</p>
14
15<DL>
16}
17
18
19proc chng {date desc} {
20 if {[regexp {\(([0-9.]+)\)} $date all vers]} {
21 set label [string map {. _} $vers]
22 puts "<A NAME=\"version_$label\">"
23 }
24 puts "<DT><B>$date</B></DT>"
25 regsub -all {[Tt]icket #(\d+)} $desc \
26 {<a href="http://www.sqlite.org/cvstrac/tktview?tn=\1">\0</a>} desc
27 puts "<DD><P><UL>$desc</UL></P>"
28 puts "</DD>"
29}
30
31chng {2007 Oct 04 (3.5.1)} {
32<li><i><b>Nota Bene:</b> We are not using terms "alpha" or "beta" on this
33 release because the code is stable and because if we use those terms,
34 nobody will upgrade. However, we still reserve the right to make
35 incompatible changes to the new VFS interface in future releases.</i></li>
36
37<li>Fix a bug in the handling of SQLITE_FULL errors that could lead
38 to database corruption. Ticket #2686.
39<li>The test_async.c drive now does full file locking and works correctly
40 when used simultaneously by multiple processes on the same database.
41<li>The CLI ignores whitespace (including comments) at the end of lines
42<li>Make sure the query optimizer checks dependences on all terms of
43 a compound SELECT statement. Ticket #2640.
44<li>Add demonstration code showing how to build a VFS for a raw
45 mass storage without a filesystem.
46<li>Added an output buffer size parameter to the xGetTempname() method
47 of the VFS layer.
48<li>Sticky SQLITE_FULL or SQLITE_IOERR errors in the pager are reset
49 when a new transaction is started.
50}
51
52
53chng {2007 Sep 04 (3.5.0) alpha} {
54<li>Redesign the OS interface layer. See
55 <a href="34to35.html">34to35.html</a> for details.
56 <font color="red">*** Potentially incompatible change ***</font>
57<li>The <a href="capi3ref.html#sqlite3_release_memory">
58 sqlite3_release_memory()</a>,
59 <a href="capi3ref.html#sqlite3_soft_heap_limit">
60 sqlite3_soft_heap_limit()</a>,
61 and <a href="capi3ref.html#sqlite3_enable_shared_cache">
62 sqlite3_enable_shared_cache()</a> interfaces now work cross all
63 threads in the process, not just the single thread in which they
64 are invoked.
65 <font color="red">*** Potentially incompatible change ***</font>
66<li>Added the
67 <a href="capi3ref.html#sqlite3_open_v2">sqlite3_open_v2()</a>
68 interface.
69<li>Reimplemented the memory allocation subsystem and made it
70 replacable at compile-time.
71<li>Created a new mutex subsystem and made it replacable at
72 compile-time.
73<li>The same database connection may now be used simultaneously by
74 separate threads.
75}
76
77
78chng {2007 August 13 (3.4.2)} {
79<li>Fix a database corruption bug that might occur if a ROLLBACK command
80is executed in <a href="pragma.html#pragma_auto_vacuum">auto-vacuum mode</a>
81and a very small <a href="capi3ref.html#sqlite3_soft_heap_limit">
82soft_heap_limit</a> is set.
83<a href="http://www.sqlite.org/cvstrac/tktview?tn=2565">Ticket #2565</a>.
84
85<li>Add the ability to run a full regression test with a small
86<a href="capi3ref.html#sqlite3_soft_heap_limit">soft_heap_limit</a>.
87
88<li>Fix other minor problems with using small soft heap limits.
89
90<li>Work-around for
91<a href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=32575">GCC bug 32575</a>.
92
93<li>Improved error detection of misused aggregate functions.
94
95<li>Improvements to the amalgamation generator script so that all symbols
96are prefixed with either SQLITE_PRIVATE or SQLITE_API.
97}
98
99chng {2007 July 20 (3.4.1)} {
100<li>Fix a bug in <a href="lang_vacuum.html">VACUUM</a> that can lead to
101 <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption">
102 database corruption</a> if two
103 processes are connected to the database at the same time and one
104 VACUUMs then the other then modifies the database.</li>
105<li>The expression "+column" is now considered the same as "column"
106 when computing the collating sequence to use on the expression.</li>
107<li>In the <a href="tclsqlite.html">TCL language interface</a>,
108 "@variable" instead of "$variable" always binds as a blob.</li>
109<li>Added <a href="pragma.html#pragma_freelist_count">PRAGMA freelist_count</a>
110 for determining the current size of the freelist.</li>
111<li>The <a href="pragma.html#pragma_auto_vacuum">
112 PRAGMA auto_vacuum=incremental</a> setting is now persistent.</li>
113<li>Add FD_CLOEXEC to all open files under unix.</li>
114<li>Fix a bug in the <a href="optoverview.html#minmax">
115 min()/max() optimization</a> when applied to
116 descending indices.</li>
117<li>Make sure the TCL language interface works correctly with 64-bit
118 integers on 64-bit machines.</li>
119<li>Allow the value -9223372036854775808 as an integer literal in SQL
120 statements.</li>
121<li>Add the capability of "hidden" columns in virtual tables.</li>
122<li>Use the macro SQLITE_PRIVATE (defaulting to "static") on all
123 internal functions in the amalgamation.</li>
124<li>Add pluggable tokenizers and <a href="http://www.icu-project.org/">ICU</a>
125 tokenization support to FTS2</li>
126<li>Other minor bug fixes and documentation enhancements</li>
127}
128
129chng {2007 June 18 (3.4.0)} {
130<li>Fix a bug that can lead to database corruption if an SQLITE_BUSY error
131 occurs in the middle of an explicit transaction and that transaction
132 is later committed.
133 <a href="http://www.sqlite.org/cvstrac/tktview?tn=2409">Ticket #2409.</a>
134 See the
135 <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">
136 CorruptionFollowingBusyError</a> wiki page for details.</i>
137<li>Fix a bug that can lead to database corruption if autovacuum mode is
138 on and a malloc() failure follows a CREATE TABLE or CREATE INDEX statement
139 which itself follows a cache overflow inside a transaction. See
140 <a href="http://www.sqlite.org/cvstrac/tktview?tn=2418">ticket #2418</a>.
141 </li>
142<li>Added explicit <a href="limits.html">upper bounds</a> on the sizes and
143 quantities of things SQLite can process. This change might cause
144 compatibility problems for
145 applications that use SQLite in the extreme, which is why the current
146 release is 3.4.0 instead of 3.3.18.</li>
147<li>Added support for <a href="capi3ref.html#sqlite3_blob_open">
148 Incremental BLOB I/O</a>.</li>
149<li>Added the <a href="capi3ref.html#sqlite3_bind_zeroblob">zeroblob API</a>
150 and the <a href="lang_expr.html#zeroblob">zeroblob()</a> SQL function.</li>
151<li>Added support for <a href="pragma.html#pragma_incremental_vacuum">
152 Incremental Vacuum</a>.</li>
153<li>Added the SQLITE_MIXED_ENDIAN_64BIT_FLOAT compile-time option to suppport
154 ARM7 processors with goofy endianness.</li>
155<li>Removed all instances of sprintf() and strcpy() from the core library.</li>
156<li>Added support for <a href="http://www.icu-project.org/">
157 International Components for Unicode (ICU)</a> to the full-text search
158 extensions.
159</ul><p>
160<ul type="circle">
161<li>In the windows OS driver, reacquire a SHARED lock if an attempt to
162 acquire an EXCLUSIVE lock fails. Ticket #2354</li>
163<li>Fix the REPLACE() function so that it returns NULL if the second argument
164 is an empty string. Ticket #2324.</li>
165<li>Document the hazards of type coversions in
166 <a href="capi3ref.html#sqlite3_column_blob">sqlite3_column_blob()</a>
167 and related APIs. Fix unnecessary type conversions. Ticket #2321.</li>
168<li>Internationalization of the TRIM() function. Ticket #2323</li>
169<li>Use memmove() instead of memcpy() when moving between memory regions
170 that might overlap. Ticket #2334</li>
171<li>Fix an optimizer bug involving subqueries in a compound SELECT that has
172 both an ORDER BY and a LIMIT clause. Ticket #2339.</li>
173<li>Make sure the <a href="capi3ref.html#sqlite3_snprintf">sqlite3_snprintf()
174 </a> interface does not zero-terminate the buffer if the buffer size is
175 less than 1. Ticket #2341</li>
176<li>Fix the built-in printf logic so that it prints "NaN" not "Inf" for
177 floating-point NaNs. Ticket #2345</li>
178<li>When converting BLOB to TEXT, use the text encoding of the main database.
179 Ticket #2349</li>
180<li>Keep the full precision of integers (if possible) when casting to
181 NUMERIC. Ticket #2364</li>
182<li>Fix a bug in the handling of UTF16 codepoint 0xE000</li>
183<li>Consider explicit collate clauses when matching WHERE constraints
184 to indices in the query optimizer. Ticket #2391</li>
185<li>Fix the query optimizer to correctly handle constant expressions in
186 the ON clause of a LEFT JOIN. Ticket #2403</li>
187<li>Fix the query optimizer to handle rowid comparisions to NULL
188 correctly. Ticket #2404</li>
189<li>Fix many potental segfaults that could be caused by malicious SQL
190 statements.</li>
191}
192
193chng {2007 April 25 (3.3.17)} {
194<li>When the "write_version" value of the database header is larger than
195 what the library understands, make the database read-only instead of
196 unreadable.</li>
197<li>Other minor bug fixes</li>
198}
199
200chng {2007 April 18 (3.3.16)} {
201<li>Fix a bug that caused VACUUM to fail if NULLs appeared in a
202 UNIQUE column.</li>
203<li>Reinstate performance improvements that were added in 3.3.14
204 but regressed in 3.3.15.</li>
205<li>Fix problems with the handling of ORDER BY expressions on
206 compound SELECT statements in subqueries.</li>
207<li>Fix a potential segfault when destroying locks on WinCE in
208 a multi-threaded environment.</li>
209<li>Documentation updates.</li>
210}
211
212chng {2007 April 9 (3.3.15)} {
213<li>Fix a bug introduced in 3.3.14 that caused a rollback of
214 CREATE TEMP TABLE to leave the database connection wedged.</li>
215<li>Fix a bug that caused an extra NULL row to be returned when
216 a descending query was interrupted by a change to the database.</li>
217<li>The FOR EACH STATEMENT clause on a trigger now causes a syntax
218 error. It used to be silently ignored.</li>
219<li>Fix an obscure and relatively harmless problem that might have caused
220 a resource leak following an I/O error.</li>
221<li>Many improvements to the test suite. Test coverage now exceeded 98%</li>
222}
223
224chng {2007 April 2 (3.3.14)} {
225<li>Fix a <a href="http://www.sqlite.org/cvstrac/tktview?tn=2273">bug</a>
226 in 3.3.13 that could cause a segfault when the IN operator
227 is used one one term of a two-column index and the right-hand side of
228 the IN operator contains a NULL.</li>
229<li>Added a new OS interface method for determining the sector size
230 of underlying media: sqlite3OsSectorSize().</li>
231<li>A new algorithm for statements of the form
232 INSERT INTO <i>table1</i> SELECT * FROM <i>table2</i>
233 is faster and reduces fragmentation. VACUUM uses statements of
234 this form and thus runs faster and defragments better.</li>
235<li>Performance enhancements through reductions in disk I/O:
236<ul>
237<li>Do not read the last page of an overflow chain when
238 deleting the row - just add that page to the freelist.</li>
239<li>Do not store pages being deleted in the
240 rollback journal.</li>
241<li>Do not read in the (meaningless) content of
242 pages extracted from the freelist.</li>
243<li>Do not flush the page cache (and thus avoiding
244 a cache refill) unless another process changes the underlying
245 database file.</li>
246<li>Truncate rather than delete the rollback journal when committing
247 a transaction in exclusive access mode, or when committing the TEMP
248 database.</li>
249</ul></li>
250<li>Added support for exclusive access mode using
251 <a href="pragma.html#pragma_locking_mode">
252 "PRAGMA locking_mode=EXCLUSIVE"</a></li>
253<li>Use heap space instead of stack space for large buffers in the
254 pager - useful on embedded platforms with stack-space
255 limitations.</li>
256<li>Add a makefile target "sqlite3.c" that builds an amalgamation containing
257 the core SQLite library C code in a single file.</li>
258<li>Get the library working correctly when compiled
259 with GCC option "-fstrict-aliasing".</li>
260<li>Removed the vestigal SQLITE_PROTOCOL error.</li>
261<li>Improvements to test coverage, other minor bugs fixed,
262 memory leaks plugged,
263 code refactored and/or recommented in places for easier reading.</li>
264}
265
266chng {2007 February 13 (3.3.13)} {
267<li>Add a "fragmentation" measurement in the output of sqlite3_analyzer.</li>
268<li>Add the COLLATE operator used to explicitly set the collating sequence
269used by an expression. This feature is considered experimental pending
270additional testing.</li>
271<li>Allow up to 64 tables in a join - the old limit was 32.</li>
272<li>Added two new experimental functions:
273<a href="lang_expr.html#randomblobFunc">randomBlob()</a> and
274<a href="lang_expr.html#hexFunc">hex()</a>.
275Their intended use is to facilitate generating
276<a href="http://en.wikipedia.org/wiki/UUID">UUIDs</a>.
277</li>
278<li>Fix a problem where
279<a href="pragma.html#pragma_count_changes">PRAGMA count_changes</a> was
280causing incorrect results for updates on tables with triggers</li>
281<li>Fix a bug in the ORDER BY clause optimizer for joins where the
282left-most table in the join is constrained by a UNIQUE index.</li>
283<li>Fixed a bug in the "copy" method of the TCL interface.</li>
284<li>Bug fixes in fts1 and fts2 modules.</li>
285}
286
287chng {2007 January 27 (3.3.12)} {
288<li>Fix another bug in the IS NULL optimization that was added in
289version 3.3.9.</li>
290<li>Fix a assertion fault that occurred on deeply nested views.</li>
291<li>Limit the amount of output that
292<a href="pragma.html#pragma_integrity_check">PRAGMA integrity_check</a>
293generates.</li>
294<li>Minor syntactic changes to support a wider variety of compilers.</li>
295}
296
297chng {2007 January 22 (3.3.11)} {
298<li>Fix another bug in the implementation of the new
299<a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a> API.
300We'll get it right eventually...</li>
301<li>Fix a bug in the IS NULL optimization that was added in version 3.3.9 -
302the bug was causing incorrect results on certain LEFT JOINs that included
303in the WHERE clause an IS NULL constraint for the right table of the
304LEFT JOIN.</li>
305<li>Make AreFileApisANSI() a no-op macro in winCE since winCE does not
306support this function.</li>
307}
308
309chng {2007 January 9 (3.3.10)} {
310<li>Fix bugs in the implementation of the new
311<a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a> API
312that can lead to segfaults.</li>
313<li>Fix 1-second round-off errors in the
314<a href="http://www.sqlite.org/cvstrac/wiki?p=DateAndTimeFunctions">
315strftime()</a> function</li>
316<li>Enhance the windows OS layer to provide detailed error codes</li>
317<li>Work around a win2k problem so that SQLite can use single-character
318database file names</li>
319<li>The
320<a href="pragma.html#pragma_user_version">user_version</a> and
321<a href="pragma.html#pragma_schema_version">schema_version</a> pragmas
322correctly set their column names in the result set</li>
323<li>Documentation updates</li>
324}
325
326chng {2007 January 4 (3.3.9)} {
327<li>Fix bugs in pager.c that could lead to database corruption if two
328processes both try to recover a hot journal at the same instant</li>
329<li>Added the <a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a>
330API.</li>
331<li>Fixed the ".dump" command in the command-line shell to show
332indices, triggers and views again.</li>
333<li>Change the table_info pragma so that it returns NULL for the default
334value if there is no default value</li>
335<li>Support for non-ASCII characters in win95 filenames</li>
336<li>Query optimizer enhancements:
337<ul>
338<li>Optimizer does a better job of using indices to satisfy ORDER BY
339clauses that sort on the integer primary key</li>
340<li>Use an index to satisfy an IS NULL operator in the WHERE clause</li>
341<li>Fix a bug that was causing the optimizer to miss an OR optimization
342opportunity</li>
343<li>The optimizer has more freedom to reorder tables in the FROM clause
344even in there are LEFT joins.</li>
345</ul>
346<li>Extension loading supported added to winCE</li>
347<li>Allow constraint names on the DEFAULT clause in a table definition</li>
348<li>Added the ".bail" command to the command-line shell</li>
349<li>Make CSV (comma separate value) output from the command-line shell
350more closely aligned to accepted practice</li>
351<li>Experimental FTS2 module added</li>
352<li>Use sqlite3_mprintf() instead of strdup() to avoid libc dependencies</li>
353<li>VACUUM uses a temporary file in the official TEMP folder, not in the
354same directory as the original database</li>
355<li>The prefix on temporary filenames on windows is changed from "sqlite"
356to "etilqs".</li>
357}
358
359chng {2006 October 9 (3.3.8)} {
360<li>Support for full text search using the
361<a href="http://www.sqlite.org/cvstrac/wiki?p=FullTextIndex">FTS1 module</a>
362(beta)</li>
363<li>Added OS-X locking patches (beta - disabled by default)</li>
364<li>Introduce extended error codes and add error codes for various
365kinds of I/O errors.</li>
366<li>Added support for IF EXISTS on CREATE/DROP TRIGGER/VIEW</li>
367<li>Fix the regression test suite so that it works with Tcl8.5</li>
368<li>Enhance sqlite3_set_authorizer() to provide notification of calls to
369 SQL functions.</li>
370<li>Added experimental API: sqlite3_auto_extension()</li>
371<li>Various minor bug fixes</li>
372}
373
374chng {2006 August 12 (3.3.7)} {
375<li>Added support for
376<a href="http://www.sqlite.org/cvstrac/wiki?p=VirtualTables">virtual tables</a>
377(beta)</li>
378<li>Added support for
379<a href="http://www.sqlite.org/cvstrac/wiki?p=LoadableExtensions">
380dynamically loaded extensions</a> (beta)</li>
381<li>The
382<a href="capi3ref.html#sqlite3_interrupt">sqlite3_interrupt()</a>
383routine can be called for a different thread</li>
384<li>Added the <a href="lang_expr.html#match">MATCH</a> operator.</li>
385<li>The default file format is now 1.
386}
387
388chng {2006 June 6 (3.3.6)} {
389<li>Plays better with virus scanners on windows</li>
390<li>Faster :memory: databases</li>
391<li>Fix an obscure segfault in UTF-8 to UTF-16 conversions</li>
392<li>Added driver for OS/2</li>
393<li>Correct column meta-information returned for aggregate queries</li>
394<li>Enhanced output from EXPLAIN QUERY PLAN</li>
395<li>LIMIT 0 now works on subqueries</li>
396<li>Bug fixes and performance enhancements in the query optimizer</li>
397<li>Correctly handle NULL filenames in ATTACH and DETACH</li>
398<li>Inproved syntax error messages in the parser</li>
399<li>Fix type coercion rules for the IN operator</li>
400}
401
402chng {2006 April 5 (3.3.5)} {
403<li>CHECK constraints use conflict resolution algorithms correctly.</li>
404<li>The SUM() function throws an error on integer overflow.</li>
405<li>Choose the column names in a compound query from the left-most SELECT
406 instead of the right-most.</li>
407<li>The sqlite3_create_collation() function
408 honors the SQLITE_UTF16_ALIGNED flag.</li>
409<li>SQLITE_SECURE_DELETE compile-time option causes deletes to overwrite
410 old data with zeros.</li>
411<li>Detect integer overflow in abs().</li>
412<li>The random() function provides 64 bits of randomness instead of
413 only 32 bits.</li>
414<li>Parser detects and reports automaton stack overflow.</li>
415<li>Change the round() function to return REAL instead of TEXT.</li>
416<li>Allow WHERE clause terms on the left table of a LEFT OUTER JOIN to
417 contain aggregate subqueries.</li>
418<li>Skip over leading spaces in text to numeric conversions.</li>
419<li>Various minor bug and documentation typo fixes and
420 performance enhancements.</li>
421}
422
423chng {2006 February 11 (3.3.4)} {
424<li>Fix a blunder in the Unix mutex implementation that can lead to
425deadlock on multithreaded systems.</li>
426<li>Fix an alignment problem on 64-bit machines</li>
427<li>Added the fullfsync pragma.</li>
428<li>Fix an optimizer bug that could have caused some unusual LEFT OUTER JOINs
429to give incorrect results.</li>
430<li>The SUM function detects integer overflow and converts to accumulating
431an approximate result using floating point numbers</li>
432<li>Host parameter names can begin with '@' for compatibility with SQL Server.
433</li>
434<li>Other miscellaneous bug fixes</li>
435}
436
437chng {2006 January 31 (3.3.3)} {
438<li>Removed support for an ON CONFLICT clause on CREATE INDEX - it never
439worked correctly so this should not present any backward compatibility
440problems.</li>
441<li>Authorizer callback now notified of ALTER TABLE ADD COLUMN commands</li>
442<li>After any changes to the TEMP database schema, all prepared statements
443are invalidated and must be recreated using a new call to
444sqlite3_prepare()</li>
445<li>Other minor bug fixes in preparation for the first stable release
446of version 3.3</li>
447}
448
449chng {2006 January 24 (3.3.2 beta)} {
450<li>Bug fixes and speed improvements. Improved test coverage.</li>
451<li>Changes to the OS-layer interface: mutexes must now be recursive.</li>
452<li>Discontinue the use of thread-specific data for out-of-memory
453exception handling</li>
454}
455
456chng {2006 January 16 (3.3.1 alpha)} {
457<li>Countless bug fixes</li>
458<li>Speed improvements</li>
459<li>Database connections can now be used by multiple threads, not just
460the thread in which they were created.</li>
461}
462
463chng {2006 January 10 (3.3.0 alpha)} {
464<li>CHECK constraints</li>
465<li>IF EXISTS and IF NOT EXISTS clauses on CREATE/DROP TABLE/INDEX.</li>
466<li>DESC indices</li>
467<li>More efficient encoding of boolean values resulting in smaller database
468files</li>
469<li>More aggressive SQLITE_OMIT_FLOATING_POINT</li>
470<li>Separate INTEGER and REAL affinity</li>
471<li>Added a virtual function layer for the OS interface</li>
472<li>"exists" method added to the TCL interface</li>
473<li>Improved response to out-of-memory errors</li>
474<li>Database cache can be optionally shared between connections
475in the same thread</li>
476<li>Optional READ UNCOMMITTED isolation (instead of the default
477isolation level of SERIALIZABLE) and table level locking when
478database connections share a common cache.</li>
479}
480
481chng {2005 December 19 (3.2.8)} {
482<li>Fix an obscure bug that can cause database corruption under the
483following unusual circumstances: A large INSERT or UPDATE statement which
484is part of an even larger transaction fails due to a uniqueness contraint
485but the containing transaction commits.</li>
486}
487
488chng {2005 December 19 (2.8.17)} {
489<li>Fix an obscure bug that can cause database corruption under the
490following unusual circumstances: A large INSERT or UPDATE statement which
491is part of an even larger transaction fails due to a uniqueness contraint
492but the containing transaction commits.</li>
493}
494
495chng {2005 September 24 (3.2.7)} {
496<li>GROUP BY now considers NULLs to be equal again, as it should
497</li>
498<li>Now compiles on Solaris and OpenBSD and other Unix variants
499that lack the fdatasync() function</li>
500<li>Now compiles on MSVC++6 again</li>
501<li>Fix uninitialized variables causing malfunctions for various obscure
502queries</li>
503<li>Correctly compute a LEFT OUTER JOINs that is constrained on the
504left table only</li>
505}
506
507chng {2005 September 17 (3.2.6)} {
508<li>Fix a bug that can cause database corruption if a VACUUM (or
509 autovacuum) fails and is rolled back on a database that is
510 larger than 1GiB</li>
511<li>LIKE optiization now works for columns with COLLATE NOCASE</li>
512<li>ORDER BY and GROUP BY now use bounded memory</li>
513<li>Added support for COUNT(DISTINCT expr)</li>
514<li>Change the way SUM() handles NULL values in order to comply with
515 the SQL standard</li>
516<li>Use fdatasync() instead of fsync() where possible in order to speed
517 up commits slightly</li>
518<li>Use of the CROSS keyword in a join turns off the table reordering
519 optimization</li>
520<li>Added the experimental and undocumented EXPLAIN QUERY PLAN capability</li>
521<li>Use the unicode API in windows</li>
522}
523
524chng {2005 August 27 (3.2.5)} {
525<li>Fix a bug effecting DELETE and UPDATE statements that changed
526more than 40960 rows.</li>
527<li>Change the makefile so that it no longer requires GNUmake extensions</li>
528<li>Fix the --enable-threadsafe option on the configure script</li>
529<li>Fix a code generator bug that occurs when the left-hand side of an IN
530operator is constant and the right-hand side is a SELECT statement</li>
531<li>The PRAGMA synchronous=off statement now disables syncing of the
532master journal file in addition to the normal rollback journals</li>
533}
534
535chng {2005 August 24 (3.2.4)} {
536<li>Fix a bug introduced in the previous release
537that can cause a segfault while generating code
538for complex WHERE clauses.</li>
539<li>Allow floating point literals to begin or end with a decimal point.</li>
540}
541
542chng {2005 August 21 (3.2.3)} {
543<li>Added support for the CAST operator</li>
544<li>Tcl interface allows BLOB values to be transferred to user-defined
545functions</li>
546<li>Added the "transaction" method to the Tcl interface</li>
547<li>Allow the DEFAULT value of a column to call functions that have constant
548operands</li>
549<li>Added the ANALYZE command for gathering statistics on indices and
550using those statistics when picking an index in the optimizer</li>
551<li>Remove the limit (formerly 100) on the number of terms in the
552WHERE clause</li>
553<li>The right-hand side of the IN operator can now be a list of expressions
554instead of just a list of constants</li>
555<li>Rework the optimizer so that it is able to make better use of indices</li>
556<li>The order of tables in a join is adjusted automatically to make
557better use of indices</li>
558<li>The IN operator is now a candidate for optimization even if the left-hand
559side is not the left-most term of the index. Multiple IN operators can be
560used with the same index.</li>
561<li>WHERE clause expressions using BETWEEN and OR are now candidates
562for optimization</li>
563<li>Added the "case_sensitive_like" pragma and the SQLITE_CASE_SENSITIVE_LIKE
564compile-time option to set its default value to "on".</li>
565<li>Use indices to help with GLOB expressions and LIKE expressions too
566when the case_sensitive_like pragma is enabled</li>
567<li>Added support for grave-accent quoting for compatibility with MySQL</li>
568<li>Improved test coverage</li>
569<li>Dozens of minor bug fixes</li>
570}
571
572chng {2005 June 13 (3.2.2)} {
573<li>Added the sqlite3_db_handle() API</li>
574<li>Added the sqlite3_get_autocommit() API</li>
575<li>Added a REGEXP operator to the parser. There is no function to back
576up this operator in the standard build but users can add their own using
577sqlite3_create_function()</li>
578<li>Speed improvements and library footprint reductions.</li>
579<li>Fix byte alignment problems on 64-bit architectures.</li>
580<li>Many, many minor bug fixes and documentation updates.</li>
581}
582
583chng {2005 March 29 (3.2.1)} {
584<li>Fix a memory allocation error in the new ADD COLUMN comment.</li>
585<li>Documentation updates</li>
586}
587
588chng {2005 March 21 (3.2.0)} {
589<li>Added support for ALTER TABLE ADD COLUMN.</li>
590<li>Added support for the "T" separator in ISO-8601 date/time strings.</li>
591<li>Improved support for Cygwin.</li>
592<li>Numerous bug fixes and documentation updates.</li>
593}
594
595chng {2005 March 16 (3.1.6)} {
596<li>Fix a bug that could cause database corruption when inserting
597 record into tables with around 125 columns.</li>
598<li>sqlite3_step() is now much more likely to invoke the busy handler
599 and less likely to return SQLITE_BUSY.</li>
600<li>Fix memory leaks that used to occur after a malloc() failure.</li>
601}
602
603chng {2005 March 11 (3.1.5)} {
604<li>The ioctl on OS-X to control syncing to disk is F_FULLFSYNC,
605 not F_FULLSYNC. The previous release had it wrong.</li>
606}
607
608chng {2005 March 10 (3.1.4)} {
609<li>Fix a bug in autovacuum that could cause database corruption if
610a CREATE UNIQUE INDEX fails because of a constraint violation.
611This problem only occurs if the new autovacuum feature introduced in
612version 3.1 is turned on.</li>
613<li>The F_FULLSYNC ioctl (currently only supported on OS-X) is disabled
614if the synchronous pragma is set to something other than "full".</li>
615<li>Add additional forward compatibility to the future version 3.2 database
616file format.</li>
617<li>Fix a bug in WHERE clauses of the form (rowid<'2')</li>
618<li>New SQLITE_OMIT_... compile-time options added</li>
619<li>Updates to the man page</li>
620<li>Remove the use of strcasecmp() from the shell</li>
621<li>Windows DLL exports symbols Tclsqlite_Init and Sqlite_Init</li>
622}
623
624chng {2005 February 19 (3.1.3)} {
625<li>Fix a problem with VACUUM on databases from which tables containing
626AUTOINCREMENT have been dropped.</li>
627<li>Add forward compatibility to the future version 3.2 database file
628format.</li>
629<li>Documentation updates</li>
630}
631
632chng {2005 February 15 (3.1.2)} {
633<li>Fix a bug that can lead to database corruption if there are two
634open connections to the same database and one connection does a VACUUM
635and the second makes some change to the database.</li>
636<li>Allow "?" parameters in the LIMIT clause.</li>
637<li>Fix VACUUM so that it works with AUTOINCREMENT.</li>
638<li>Fix a race condition in AUTOVACUUM that can lead to corrupt databases</li>
639<li>Add a numeric version number to the sqlite3.h include file.</li>
640<li>Other minor bug fixes and performance enhancements.</li>
641}
642
643chng {2005 February 15 (2.8.16)} {
644<li>Fix a bug that can lead to database corruption if there are two
645open connections to the same database and one connection does a VACUUM
646and the second makes some change to the database.</li>
647<li>Correctly handle quoted names in CREATE INDEX statements.</li>
648<li>Fix a naming conflict between sqlite.h and sqlite3.h.</li>
649<li>Avoid excess heap usage when copying expressions.</li>
650<li>Other minor bug fixes.</li>
651}
652
653chng {2005 February 1 (3.1.1 BETA)} {
654<li>Automatic caching of prepared statements in the TCL interface</li>
655<li>ATTACH and DETACH as well as some other operations cause existing
656 prepared statements to expire.</li>
657<li>Numerious minor bug fixes</li>
658}
659
660chng {2005 January 21 (3.1.0 ALPHA)} {
661<li>Autovacuum support added</li>
662<li>CURRENT_TIME, CURRENT_DATE, and CURRENT_TIMESTAMP added</li>
663<li>Support for the EXISTS clause added.</li>
664<li>Support for correlated subqueries added.</li>
665<li>Added the ESCAPE clause on the LIKE operator.</li>
666<li>Support for ALTER TABLE ... RENAME TABLE ... added</li>
667<li>AUTOINCREMENT keyword supported on INTEGER PRIMARY KEY</li>
668<li>Many SQLITE_OMIT_ macros inserts to omit features at compile-time
669 and reduce the library footprint.</li>
670<li>The REINDEX command was added.</li>
671<li>The engine no longer consults the main table if it can get
672 all the information it needs from an index.</li>
673<li>Many nuisance bugs fixed.</li>
674}
675
676chng {2004 October 11 (3.0.8)} {
677<li>Add support for DEFERRED, IMMEDIATE, and EXCLUSIVE transactions.</li>
678<li>Allow new user-defined functions to be created when there are
679already one or more precompiled SQL statements.<li>
680<li>Fix portability problems for Mingw/MSYS.</li>
681<li>Fix a byte alignment problem on 64-bit Sparc machines.</li>
682<li>Fix the ".import" command of the shell so that it ignores \r
683characters at the end of lines.</li>
684<li>The "csv" mode option in the shell puts strings inside double-quotes.</li>
685<li>Fix typos in documentation.</li>
686<li>Convert array constants in the code to have type "const".</li>
687<li>Numerous code optimizations, specially optimizations designed to
688make the code footprint smaller.</li>
689}
690
691chng {2004 September 18 (3.0.7)} {
692<li>The BTree module allocates large buffers using malloc() instead of
693 off of the stack, in order to play better on machines with limited
694 stack space.</li>
695<li>Fixed naming conflicts so that versions 2.8 and 3.0 can be
696 linked and used together in the same ANSI-C source file.</li>
697<li>New interface: sqlite3_bind_parameter_index()</li>
698<li>Add support for wildcard parameters of the form: "?nnn"</li>
699<li>Fix problems found on 64-bit systems.</li>
700<li>Removed encode.c file (containing unused routines) from the
701 version 3.0 source tree.</li>
702<li>The sqlite3_trace() callbacks occur before each statement
703 is executed, not when the statement is compiled.</li>
704<li>Makefile updates and miscellaneous bug fixes.</li>
705}
706
707chng {2004 September 02 (3.0.6 beta)} {
708<li>Better detection and handling of corrupt database files.</li>
709<li>The sqlite3_step() interface returns SQLITE_BUSY if it is unable
710 to commit a change because of a lock</li>
711<li>Combine the implementations of LIKE and GLOB into a single
712 pattern-matching subroutine.</li>
713<li>Miscellaneous code size optimizations and bug fixes</li>
714}
715
716chng {2004 August 29 (3.0.5 beta)} {
717<li>Support for ":AAA" style bind parameter names.</li>
718<li>Added the new sqlite3_bind_parameter_name() interface.</li>
719<li>Support for TCL variable names embedded in SQL statements in the
720 TCL bindings.</li>
721<li>The TCL bindings transfer data without necessarily doing a conversion
722 to a string.</li>
723<li>The database for TEMP tables is not created until it is needed.</li>
724<li>Add the ability to specify an alternative temporary file directory
725 using the "sqlite_temp_directory" global variable.</li>
726<li>A compile-time option (SQLITE_BUSY_RESERVED_LOCK) causes the busy
727 handler to be called when there is contention for a RESERVED lock.</li>
728<li>Various bug fixes and optimizations</li>
729}
730
731chng {2004 August 8 (3.0.4 beta)} {
732<li>CREATE TABLE and DROP TABLE now work correctly as prepared statements.</li>
733<li>Fix a bug in VACUUM and UNIQUE indices.</li>
734<li>Add the ".import" command to the command-line shell.</li>
735<li>Fix a bug that could cause index corruption when an attempt to
736 delete rows of a table is blocked by a pending query.</li>
737<li>Library size optimizations.</li>
738<li>Other minor bug fixes.</li>
739}
740
741chng {2004 July 22 (2.8.15)} {
742<li>This is a maintenance release only. Various minor bugs have been
743fixed and some portability enhancements are added.</li>
744}
745
746chng {2004 July 22 (3.0.3 beta)} {
747<li>The second beta release for SQLite 3.0.</li>
748<li>Add support for "PRAGMA page_size" to adjust the page size of
749the database.</li>
750<li>Various bug fixes and documentation updates.</li>
751}
752
753chng {2004 June 30 (3.0.2 beta)} {
754<li>The first beta release for SQLite 3.0.</li>
755}
756
757chng {2004 June 22 (3.0.1 alpha)} {
758<li><font color="red"><b>
759 *** Alpha Release - Research And Testing Use Only ***</b></font>
760<li>Lots of bug fixes.</li>
761}
762
763chng {2004 June 18 (3.0.0 alpha)} {
764<li><font color="red"><b>
765 *** Alpha Release - Research And Testing Use Only ***</b></font>
766<li>Support for internationalization including UTF-8, UTF-16, and
767 user defined collating sequences.</li>
768<li>New file format that is 25% to 35% smaller for typical use.</li>
769<li>Improved concurrency.</li>
770<li>Atomic commits for ATTACHed databases.</li>
771<li>Remove cruft from the APIs.</li>
772<li>BLOB support.</li>
773<li>64-bit rowids.</li>
774<li><a href="version3.html">More information</a>.
775}
776
777chng {2004 June 9 (2.8.14)} {
778<li>Fix the min() and max() optimizer so that it works when the FROM
779 clause consists of a subquery.</li>
780<li>Ignore extra whitespace at the end of of "." commands in the shell.</li>
781<li>Bundle sqlite_encode_binary() and sqlite_decode_binary() with the
782 library.</li>
783<li>The TEMP_STORE and DEFAULT_TEMP_STORE pragmas now work.</li>
784<li>Code changes to compile cleanly using OpenWatcom.</li>
785<li>Fix VDBE stack overflow problems with INSTEAD OF triggers and
786 NULLs in IN operators.</li>
787<li>Add the global variable sqlite_temp_directory which if set defines the
788 directory in which temporary files are stored.</li>
789<li>sqlite_interrupt() plays well with VACUUM.</li>
790<li>Other minor bug fixes.</li>
791}
792
793chng {2004 March 8 (2.8.13)} {
794<li>Refactor parts of the code in order to make the code footprint
795 smaller. The code is now also a little bit faster.</li>
796<li>sqlite_exec() is now implemented as a wrapper around sqlite_compile()
797 and sqlite_step().</li>
798<li>The built-in min() and max() functions now honor the difference between
799 NUMERIC and TEXT datatypes. Formerly, min() and max() always assumed
800 their arguments were of type NUMERIC.</li>
801<li>New HH:MM:SS modifier to the built-in date/time functions.</li>
802<li>Experimental sqlite_last_statement_changes() API added. Fixed the
803 the last_insert_rowid() function so that it works correctly with
804 triggers.</li>
805<li>Add functions prototypes for the database encryption API.</li>
806<li>Fix several nuisance bugs.</li>
807}
808
809chng {2004 February 8 (2.8.12)} {
810<li>Fix a bug that will might corrupt the rollback journal if a power failure
811 or external program halt occurs in the middle of a COMMIT. The corrupt
812 journal can lead to database corruption when it is rolled back.</li>
813<li>Reduce the size and increase the speed of various modules, especially
814 the virtual machine.</li>
815<li>Allow "&lt;expr&gt; IN &lt;table&gt;" as a shorthand for
816 "&lt;expr&gt; IN (SELECT * FROM &lt;table&gt;".</li>
817<li>Optimizations to the sqlite_mprintf() routine.</li>
818<li>Make sure the MIN() and MAX() optimizations work within subqueries.</li>
819}
820
821chng {2004 January 14 (2.8.11)} {
822<li>Fix a bug in how the IN operator handles NULLs in subqueries. The bug
823 was introduced by the previous release.</li>
824}
825
826chng {2004 January 13 (2.8.10)} {
827<li>Fix a potential database corruption problem on Unix caused by the fact
828 that all posix advisory locks are cleared whenever you close() a file.
829 The work around it to embargo all close() calls while locks are
830 outstanding.</li>
831<li>Performance enhancements on some corner cases of COUNT(*).</li>
832<li>Make sure the in-memory backend response sanely if malloc() fails.</li>
833<li>Allow sqlite_exec() to be called from within user-defined SQL
834 functions.</li>
835<li>Improved accuracy of floating-point conversions using "long double".</li>
836<li>Bug fixes in the experimental date/time functions.</li>
837}
838
839chng {2004 January 5 (2.8.9)} {
840<li>Fix a 32-bit integer overflow problem that could result in corrupt
841 indices in a database if large negative numbers (less than -2147483648)
842 were inserted into a indexed numeric column.</li>
843<li>Fix a locking problem on multi-threaded Linux implementations.</li>
844<li>Always use "." instead of "," as the decimal point even if the locale
845 requests ",".</li>
846<li>Added UTC to localtime conversions to the experimental date/time
847 functions.</li>
848<li>Bug fixes to date/time functions.</li>
849}
850
851chng {2003 December 17 (2.8.8)} {
852<li>Fix a critical bug introduced into 2.8.0 which could cause
853 database corruption.</li>
854<li>Fix a problem with 3-way joins that do not use indices</li>
855<li>The VACUUM command now works with the non-callback API</li>
856<li>Improvements to the "PRAGMA integrity_check" command</li>
857}
858
859chng {2003 December 4 (2.8.7)} {
860<li>Added experimental sqlite_bind() and sqlite_reset() APIs.</li>
861<li>If the name of the database is an empty string, open a new database
862 in a temporary file that is automatically deleted when the database
863 is closed.</li>
864<li>Performance enhancements in the lemon-generated parser</li>
865<li>Experimental date/time functions revised.</li>
866<li>Disallow temporary indices on permanent tables.</li>
867<li>Documentation updates and typo fixes</li>
868<li>Added experimental sqlite_progress_handler() callback API</li>
869<li>Removed support for the Oracle8 outer join syntax.</li>
870<li>Allow GLOB and LIKE operators to work as functions.</li>
871<li>Other minor documentation and makefile changes and bug fixes.</li>
872}
873
874chng {2003 August 21 (2.8.6)} {
875<li>Moved the CVS repository to www.sqlite.org</li>
876<li>Update the NULL-handling documentation.</li>
877<li>Experimental date/time functions added.</li>
878<li>Bug fix: correctly evaluate a view of a view without segfaulting.</li>
879<li>Bug fix: prevent database corruption if you dropped a
880 trigger that had the same name as a table.</li>
881<li>Bug fix: allow a VACUUM (without segfaulting) on an empty
882 database after setting the EMPTY_RESULT_CALLBACKS pragma.</li>
883<li>Bug fix: if an integer value will not fit in a 32-bit int, store it in
884 a double instead.</li>
885<li>Bug fix: Make sure the journal file directory entry is committed to disk
886 before writing the database file.</li>
887}
888
889chng {2003 July 22 (2.8.5)} {
890<li>Make LIMIT work on a compound SELECT statement.</li>
891<li>LIMIT 0 now shows no rows. Use LIMIT -1 to see all rows.</li>
892<li>Correctly handle comparisons between an INTEGER PRIMARY KEY and
893 a floating point number.</li>
894<li>Fix several important bugs in the new ATTACH and DETACH commands.</li>
895<li>Updated the <a href="nulls.html">NULL-handling document</a>.</li>
896<li>Allow NULL arguments in sqlite_compile() and sqlite_step().</li>
897<li>Many minor bug fixes</li>
898}
899
900chng {2003 June 29 (2.8.4)} {
901<li>Enhanced the "PRAGMA integrity_check" command to verify indices.</li>
902<li>Added authorization hooks for the new ATTACH and DETACH commands.</li>
903<li>Many documentation updates</li>
904<li>Many minor bug fixes</li>
905}
906
907chng {2003 June 4 (2.8.3)} {
908<li>Fix a problem that will corrupt the indices on a table if you
909 do an INSERT OR REPLACE or an UPDATE OR REPLACE on a table that
910 contains an INTEGER PRIMARY KEY plus one or more indices.</li>
911<li>Fix a bug in windows locking code so that locks work correctly
912 when simultaneously accessed by Win95 and WinNT systems.</li>
913<li>Add the ability for INSERT and UPDATE statements to refer to the
914 "rowid" (or "_rowid_" or "oid") columns.</li>
915<li>Other important bug fixes</li>
916}
917
918chng {2003 May 17 (2.8.2)} {
919<li>Fix a problem that will corrupt the database file if you drop a
920 table from the main database that has a TEMP index.</li>
921}
922
923chng {2003 May 16 (2.8.1)} {
924<li>Reactivated the VACUUM command that reclaims unused disk space in
925 a database file.</li>
926<li>Added the ATTACH and DETACH commands to allow interacting with multiple
927 database files at the same time.</li>
928<li>Added support for TEMP triggers and indices.</li>
929<li>Added support for in-memory databases.</li>
930<li>Removed the experimental sqlite_open_aux_file(). Its function is
931 subsumed in the new ATTACH command.</li>
932<li>The precedence order for ON CONFLICT clauses was changed so that
933 ON CONFLICT clauses on BEGIN statements have a higher precedence than
934 ON CONFLICT clauses on constraints.
935<li>Many, many bug fixes and compatibility enhancements.</li>
936}
937
938chng {2003 Feb 16 (2.8.0)} {
939<li>Modified the journal file format to make it more resistant to corruption
940 that can occur after an OS crash or power failure.</li>
941<li>Added a new C/C++ API that does not use callback for returning data.</li>
942}
943
944chng {2003 Jan 25 (2.7.6)} {
945<li>Performance improvements. The library is now much faster.</li>
946<li>Added the <b>sqlite_set_authorizer()</b> API. Formal documentation has
947 not been written - see the source code comments for instructions on
948 how to use this function.</li>
949<li>Fix a bug in the GLOB operator that was preventing it from working
950 with upper-case letters.</li>
951<li>Various minor bug fixes.</li>
952}
953
954chng {2002 Dec 27 (2.7.5)} {
955<li>Fix an uninitialized variable in pager.c which could (with a probability
956 of about 1 in 4 billion) result in a corrupted database.</li>
957}
958
959chng {2002 Dec 17 (2.7.4)} {
960<li>Database files can now grow to be up to 2^41 bytes. The old limit
961 was 2^31 bytes.</li>
962<li>The optimizer will now scan tables in the reverse if doing so will
963 satisfy an ORDER BY ... DESC clause.</li>
964<li>The full pathname of the database file is now remembered even if
965 a relative path is passed into sqlite_open(). This allows
966 the library to continue operating correctly after a chdir().</li>
967<li>Speed improvements in the VDBE.</li>
968<li>Lots of little bug fixes.</li>
969}
970
971chng {2002 Oct 30 (2.7.3)} {
972<li>Various compiler compatibility fixes.</li>
973<li>Fix a bug in the "expr IN ()" operator.</li>
974<li>Accept column names in parentheses.</li>
975<li>Fix a problem with string memory management in the VDBE</li>
976<li>Fix a bug in the "table_info" pragma"</li>
977<li>Export the sqlite_function_type() API function in the Windows DLL</li>
978<li>Fix locking behavior under windows</li>
979<li>Fix a bug in LEFT OUTER JOIN</li>
980}
981
982chng {2002 Sep 25 (2.7.2)} {
983<li>Prevent journal file overflows on huge transactions.</li>
984<li>Fix a memory leak that occurred when sqlite_open() failed.</li>
985<li>Honor the ORDER BY and LIMIT clause of a SELECT even if the
986 result set is used for an INSERT.</li>
987<li>Do not put write locks on the file used to hold TEMP tables.</li>
988<li>Added documentation on SELECT DISTINCT and on how SQLite handles NULLs.</li>
989<li>Fix a problem that was causing poor performance when many thousands
990 of SQL statements were executed by a single sqlite_exec() call.</li>
991}
992
993chng {2002 Aug 31 (2.7.1)} {
994<li>Fix a bug in the ORDER BY logic that was introduced in version 2.7.0</li>
995<li>C-style comments are now accepted by the tokenizer.</li>
996<li>INSERT runs a little faster when the source is a SELECT statement.</li>
997}
998
999chng {2002 Aug 25 (2.7.0)} {
1000<li>Make a distinction between numeric and text values when sorting.
1001 Text values sort according to memcmp(). Numeric values sort in
1002 numeric order.</li>
1003<li>Allow multiple simultaneous readers under windows by simulating
1004 the reader/writers locks that are missing from Win95/98/ME.</li>
1005<li>An error is now returned when trying to start a transaction if
1006 another transaction is already active.</li>
1007}
1008
1009chng {2002 Aug 12 (2.6.3)} {
1010<li>Add the ability to read both little-endian and big-endian databases.
1011 So database created under SunOS or MacOSX can be read and written
1012 under Linux or Windows and vice versa.</li>
1013<li>Convert to the new website: http://www.sqlite.org/</li>
1014<li>Allow transactions to span Linux Threads</li>
1015<li>Bug fix in the processing of the ORDER BY clause for GROUP BY queries</li>
1016}
1017
1018chng {2002 Jly 30 (2.6.2)} {
1019<li>Text files read by the COPY command can now have line terminators
1020 of LF, CRLF, or CR.</li>
1021<li>SQLITE_BUSY is handled correctly if encountered during database
1022 initialization.</li>
1023<li>Fix to UPDATE triggers on TEMP tables.</li>
1024<li>Documentation updates.</li>
1025}
1026
1027chng {2002 Jly 19 (2.6.1)} {
1028<li>Include a static string in the library that responds to the RCS
1029 "ident" command and which contains the library version number.</li>
1030<li>Fix an assertion failure that occurred when deleting all rows of
1031 a table with the "count_changes" pragma turned on.</li>
1032<li>Better error reporting when problems occur during the automatic
1033 2.5.6 to 2.6.0 database format upgrade.</li>
1034}
1035
1036chng {2002 Jly 17 (2.6.0)} {
1037<li>Change the format of indices to correct a design flaw the originated
1038 with version 2.1.0. <font color="red">*** This is an incompatible
1039 file format change ***</font> When version 2.6.0 or later of the
1040 library attempts to open a database file created by version 2.5.6 or
1041 earlier, it will automatically and irreversibly convert the file format.
1042 <b>Make backup copies of older database files before opening them with
1043 version 2.6.0 of the library.</b>
1044 </li>
1045}
1046
1047chng {2002 Jly 7 (2.5.6)} {
1048<li>Fix more problems with rollback. Enhance the test suite to exercise
1049 the rollback logic extensively in order to prevent any future problems.
1050 </li>
1051}
1052
1053chng {2002 Jly 6 (2.5.5)} {
1054<li>Fix a bug which could cause database corruption during a rollback.
1055 This bugs was introduced in version 2.4.0 by the freelist
1056 optimization of checking [410].</li>
1057<li>Fix a bug in aggregate functions for VIEWs.</li>
1058<li>Other minor changes and enhancements.</li>
1059}
1060
1061chng {2002 Jly 1 (2.5.4)} {
1062<li>Make the "AS" keyword optional again.</li>
1063<li>The datatype of columns now appear in the 4th argument to the
1064 callback.</li>
1065<li>Added the <b>sqlite_open_aux_file()</b> API, though it is still
1066 mostly undocumented and untested.</li>
1067<li>Added additional test cases and fixed a few bugs that those
1068 test cases found.</li>
1069}
1070
1071chng {2002 Jun 24 (2.5.3)} {
1072<li>Bug fix: Database corruption can occur due to the optimization
1073 that was introduced in version 2.4.0 (check-in [410]). The problem
1074 should now be fixed. The use of versions 2.4.0 through 2.5.2 is
1075 not recommended.</li>
1076}
1077
1078chng {2002 Jun 24 (2.5.2)} {
1079<li>Added the new <b>SQLITE_TEMP_MASTER</b> table which records the schema
1080 for temporary tables in the same way that <b>SQLITE_MASTER</b> does for
1081 persistent tables.</li>
1082<li>Added an optimization to UNION ALL</li>
1083<li>Fixed a bug in the processing of LEFT OUTER JOIN</li>
1084<li>The LIMIT clause now works on subselects</li>
1085<li>ORDER BY works on subselects</li>
1086<li>There is a new TypeOf() function used to determine if an expression
1087 is numeric or text.</li>
1088<li>Autoincrement now works for INSERT from a SELECT.</li>
1089}
1090
1091chng {2002 Jun 19 (2.5.1)} {
1092<li>The query optimizer now attempts to implement the ORDER BY clause
1093 using an index. Sorting is still used if not suitable index is
1094 available.</li>
1095}
1096
1097chng {2002 Jun 17 (2.5.0)} {
1098<li>Added support for row triggers.</li>
1099<li>Added SQL-92 compliant handling of NULLs.</li>
1100<li>Add support for the full SQL-92 join syntax and LEFT OUTER JOINs.</li>
1101<li>Double-quoted strings interpreted as column names not text literals.</li>
1102<li>Parse (but do not implement) foreign keys.</li>
1103<li>Performance improvements in the parser, pager, and WHERE clause code
1104 generator.</li>
1105<li>Make the LIMIT clause work on subqueries. (ORDER BY still does not
1106 work, though.)</li>
1107<li>Added the "%Q" expansion to sqlite_*_printf().</li>
1108<li>Bug fixes too numerous to mention (see the change log).</li>
1109}
1110
1111chng {2002 May 09 (2.4.12)} {
1112<li>Added logic to detect when the library API routines are called out
1113 of sequence.</li>
1114}
1115
1116chng {2002 May 08 (2.4.11)} {
1117<li>Bug fix: Column names in the result set were not being generated
1118 correctly for some (rather complex) VIEWs. This could cause a
1119 segfault under certain circumstances.</li>
1120}
1121
1122chng {2002 May 02 (2.4.10)} {
1123<li>Bug fix: Generate correct column headers when a compound SELECT is used
1124 as a subquery.</li>
1125<li>Added the sqlite_encode_binary() and sqlite_decode_binary() functions to
1126 the source tree. But they are not yet linked into the library.</li>
1127<li>Documentation updates.</li>
1128<li>Export the sqlite_changes() function from windows DLLs.</li>
1129<li>Bug fix: Do not attempt the subquery flattening optimization on queries
1130 that lack a FROM clause. To do so causes a segfault.</li>
1131}
1132
1133chng {2002 Apr 21 (2.4.9)} {
1134<li>Fix a bug that was causing the precompiled binary of SQLITE.EXE to
1135 report "out of memory" under Windows 98.</li>
1136}
1137
1138chng {2002 Apr 20 (2.4.8)} {
1139<li>Make sure VIEWs are created after their corresponding TABLEs in the
1140 output of the <b>.dump</b> command in the shell.</li>
1141<li>Speed improvements: Do not do synchronous updates on TEMP tables.</li>
1142<li>Many improvements and enhancements to the shell.</li>
1143<li>Make the GLOB and LIKE operators functions that can be overridden
1144 by a programmer. This allows, for example, the LIKE operator to
1145 be changed to be case sensitive.</li>
1146}
1147
1148chng {2002 Apr 06 (2.4.7)} {
1149<li>Add the ability to put TABLE.* in the column list of a
1150 SELECT statement.</li>
1151<li>Permit SELECT statements without a FROM clause.</li>
1152<li>Added the <b>last_insert_rowid()</b> SQL function.</li>
1153<li>Do not count rows where the IGNORE conflict resolution occurs in
1154 the row count.</li>
1155<li>Make sure functions expressions in the VALUES clause of an INSERT
1156 are correct.</li>
1157<li>Added the <b>sqlite_changes()</b> API function to return the number
1158 of row that changed in the most recent operation.</li>
1159}
1160
1161chng {2002 Apr 02 (2.4.6)} {
1162<li>Bug fix: Correctly handle terms in the WHERE clause of a join that
1163 do not contain a comparison operator.</li>
1164}
1165
1166chng {2002 Apr 01 (2.4.5)} {
1167<li>Bug fix: Correctly handle functions that appear in the WHERE clause
1168 of a join.</li>
1169<li>When the PRAGMA vdbe_trace=ON is set, correctly print the P3 operand
1170 value when it is a pointer to a structure rather than a pointer to
1171 a string.</li>
1172<li>When inserting an explicit NULL into an INTEGER PRIMARY KEY, convert
1173 the NULL value into a unique key automatically.</li>
1174}
1175
1176chng {2002 Mar 24 (2.4.4)} {
1177<li>Allow "VIEW" to be a column name</li>
1178<li>Added support for CASE expressions (patch from Dan Kennedy)</li>
1179<li>Added RPMS to the delivery (patches from Doug Henry)</li>
1180<li>Fix typos in the documentation</li>
1181<li>Cut over configuration management to a new CVS repository with
1182 its own CVSTrac bug tracking system.</li>
1183}
1184
1185chng {2002 Mar 22 (2.4.3)} {
1186<li>Fix a bug in SELECT that occurs when a compound SELECT is used as a
1187 subquery in the FROM of a SELECT.</li>
1188<li>The <b>sqlite_get_table()</b> function now returns an error if you
1189 give it two or more SELECTs that return different numbers of columns.</li>
1190}
1191
1192chng {2002 Mar 14 (2.4.2)} {
1193<li>Bug fix: Fix an assertion failure that occurred when ROWID was a column
1194 in a SELECT statement on a view.</li>
1195<li>Bug fix: Fix an uninitialized variable in the VDBE that would could an
1196 assert failure.</li>
1197<li>Make the os.h header file more robust in detecting when the compile is
1198 for windows and when it is for unix.</li>
1199}
1200
1201chng {2002 Mar 13 (2.4.1)} {
1202<li>Using an unnamed subquery in a FROM clause would cause a segfault.</li>
1203<li>The parser now insists on seeing a semicolon or the end of input before
1204 executing a statement. This avoids an accidental disaster if the
1205 WHERE keyword is misspelled in an UPDATE or DELETE statement.</li>
1206}
1207
1208
1209chng {2002 Mar 10 (2.4.0)} {
1210<li>Change the name of the sanity_check PRAGMA to <b>integrity_check</b>
1211 and make it available in all compiles.</li>
1212<li>SELECT min() or max() of an indexed column with no WHERE or GROUP BY
1213 clause is handled as a special case which avoids a complete table scan.</li>
1214<li>Automatically generated ROWIDs are now sequential.</li>
1215<li>Do not allow dot-commands of the command-line shell to occur in the
1216 middle of a real SQL command.</li>
1217<li>Modifications to the "lemon" parser generator so that the parser tables
1218 are 4 times smaller.</li>
1219<li>Added support for user-defined functions implemented in C.</li>
1220<li>Added support for new functions: <b>coalesce()</b>, <b>lower()</b>,
1221 <b>upper()</b>, and <b>random()</b>
1222<li>Added support for VIEWs.</li>
1223<li>Added the subquery flattening optimizer.</li>
1224<li>Modified the B-Tree and Pager modules so that disk pages that do not
1225 contain real data (free pages) are not journaled and are not
1226 written from memory back to the disk when they change. This does not
1227 impact database integrity, since the
1228 pages contain no real data, but it does make large INSERT operations
1229 about 2.5 times faster and large DELETEs about 5 times faster.</li>
1230<li>Made the CACHE_SIZE pragma persistent</li>
1231<li>Added the SYNCHRONOUS pragma</li>
1232<li>Fixed a bug that was causing updates to fail inside of transactions when
1233 the database contained a temporary table.</li>
1234}
1235
1236chng {2002 Feb 18 (2.3.3)} {
1237<li>Allow identifiers to be quoted in square brackets, for compatibility
1238 with MS-Access.</li>
1239<li>Added support for sub-queries in the FROM clause of a SELECT.</li>
1240<li>More efficient implementation of sqliteFileExists() under Windows.
1241 (by Joel Luscy)</li>
1242<li>The VALUES clause of an INSERT can now contain expressions, including
1243 scalar SELECT clauses.</li>
1244<li>Added support for CREATE TABLE AS SELECT</li>
1245<li>Bug fix: Creating and dropping a table all within a single
1246 transaction was not working.</li>
1247}
1248
1249chng {2002 Feb 14 (2.3.2)} {
1250<li>Bug fix: There was an incorrect assert() in pager.c. The real code was
1251 all correct (as far as is known) so everything should work OK if you
1252 compile with -DNDEBUG=1. When asserts are not disabled, there
1253 could be a fault.</li>
1254}
1255
1256chng {2002 Feb 13 (2.3.1)} {
1257<li>Bug fix: An assertion was failing if "PRAGMA full_column_names=ON;" was
1258 set and you did a query that used a rowid, like this:
1259 "SELECT rowid, * FROM ...".</li>
1260}
1261
1262chng {2002 Jan 30 (2.3.0)} {
1263<li>Fix a serious bug in the INSERT command which was causing data to go
1264 into the wrong columns if the data source was a SELECT and the INSERT
1265 clauses specified its columns in some order other than the default.</li>
1266<li>Added the ability to resolve constraint conflicts is ways other than
1267 an abort and rollback. See the documentation on the "ON CONFLICT"
1268 clause for details.</li>
1269<li>Temporary files are now automatically deleted by the operating system
1270 when closed. There are no more dangling temporary files on a program
1271 crash. (If the OS crashes, fsck will delete the file after reboot
1272 under Unix. I do not know what happens under Windows.)</li>
1273<li>NOT NULL constraints are honored.</li>
1274<li>The COPY command puts NULLs in columns whose data is '\N'.</li>
1275<li>In the COPY command, backslash can now be used to escape a newline.</li>
1276<li>Added the SANITY_CHECK pragma.</li>
1277}
1278
1279chng {2002 Jan 28 (2.2.5)} {
1280<li>Important bug fix: the IN operator was not working if either the
1281 left-hand or right-hand side was derived from an INTEGER PRIMARY KEY.</li>
1282<li>Do not escape the backslash '\' character in the output of the
1283 <b>sqlite</b> command-line access program.</li>
1284}
1285
1286chng {2002 Jan 22 (2.2.4)} {
1287<li>The label to the right of an AS in the column list of a SELECT can now
1288 be used as part of an expression in the WHERE, ORDER BY, GROUP BY, and/or
1289 HAVING clauses.</li>
1290<li>Fix a bug in the <b>-separator</b> command-line option to the <b>sqlite</b>
1291 command.</li>
1292<li>Fix a problem with the sort order when comparing upper-case strings against
1293 characters greater than 'Z' but less than 'a'.</li>
1294<li>Report an error if an ORDER BY or GROUP BY expression is constant.</li>
1295}
1296
1297chng {2002 Jan 16 (2.2.3)} {
1298<li>Fix warning messages in VC++ 7.0. (Patches from nicolas352001)</li>
1299<li>Make the library thread-safe. (The code is there and appears to work
1300 but has not been stressed.)</li>
1301<li>Added the new <b>sqlite_last_insert_rowid()</b> API function.</li>
1302}
1303
1304chng {2002 Jan 13 (2.2.2)} {
1305<li>Bug fix: An assertion was failing when a temporary table with an index
1306 had the same name as a permanent table created by a separate process.</li>
1307<li>Bug fix: Updates to tables containing an INTEGER PRIMARY KEY and an
1308 index could fail.</li>
1309}
1310
1311chng {2002 Jan 9 (2.2.1)} {
1312<li>Bug fix: An attempt to delete a single row of a table with a WHERE
1313 clause of "ROWID=x" when no such rowid exists was causing an error.</li>
1314<li>Bug fix: Passing in a NULL as the 3rd parameter to <b>sqlite_open()</b>
1315 would sometimes cause a coredump.</li>
1316<li>Bug fix: DROP TABLE followed by a CREATE TABLE with the same name all
1317 within a single transaction was causing a coredump.</li>
1318<li>Makefile updates from A. Rottmann</li>
1319}
1320
1321chng {2001 Dec 22 (2.2.0)} {
1322<li>Columns of type INTEGER PRIMARY KEY are actually used as the primary
1323 key in underlying B-Tree representation of the table.</li>
1324<li>Several obscure, unrelated bugs were found and fixed while
1325 implemented the integer primary key change of the previous bullet.</li>
1326<li>Added the ability to specify "*" as part of a larger column list in
1327 the result section of a SELECT statement. For example:
1328 <nobr>"<b>SELECT rowid, * FROM table1;</b>"</nobr>.</li>
1329<li>Updates to comments and documentation.</li>
1330}
1331
1332chng {2001 Dec 14 (2.1.7)} {
1333<li>Fix a bug in <b>CREATE TEMPORARY TABLE</b> which was causing the
1334 table to be initially allocated in the main database file instead
1335 of in the separate temporary file. This bug could cause the library
1336 to suffer an assertion failure and it could cause "page leaks" in the
1337 main database file.
1338<li>Fix a bug in the b-tree subsystem that could sometimes cause the first
1339 row of a table to be repeated during a database scan.</li>
1340}
1341
1342chng {2001 Dec 14 (2.1.6)} {
1343<li>Fix the locking mechanism yet again to prevent
1344 <b>sqlite_exec()</b> from returning SQLITE_PROTOCOL
1345 unnecessarily. This time the bug was a race condition in
1346 the locking code. This change effects both POSIX and Windows users.</li>
1347}
1348
1349chng {2001 Dec 6 (2.1.5)} {
1350<li>Fix for another problem (unrelated to the one fixed in 2.1.4)
1351 that sometimes causes <b>sqlite_exec()</b> to return SQLITE_PROTOCOL
1352 unnecessarily. This time the bug was
1353 in the POSIX locking code and should not effect windows users.</li>
1354}
1355
1356chng {2001 Dec 4 (2.1.4)} {
1357<li>Sometimes <b>sqlite_exec()</b> would return SQLITE_PROTOCOL when it
1358 should have returned SQLITE_BUSY.</li>
1359<li>The fix to the previous bug uncovered a deadlock which was also
1360 fixed.</li>
1361<li>Add the ability to put a single .command in the second argument
1362 of the sqlite shell</li>
1363<li>Updates to the FAQ</li>
1364}
1365
1366chng {2001 Nov 23 (2.1.3)} {
1367<li>Fix the behavior of comparison operators
1368 (ex: "<b>&lt</b>", "<b>==</b>", etc.)
1369 so that they are consistent with the order of entries in an index.</li>
1370<li>Correct handling of integers in SQL expressions that are larger than
1371 what can be represented by the machine integer.</li>
1372}
1373
1374chng {2001 Nov 22 (2.1.2)} {
1375<li>Changes to support 64-bit architectures.</li>
1376<li>Fix a bug in the locking protocol.</li>
1377<li>Fix a bug that could (rarely) cause the database to become
1378 unreadable after a DROP TABLE due to corruption to the SQLITE_MASTER
1379 table.</li>
1380<li>Change the code so that version 2.1.1 databases that were rendered
1381 unreadable by the above bug can be read by this version of
1382 the library even though the SQLITE_MASTER table is (slightly)
1383 corrupted.</li>
1384}
1385
1386chng {2001 Nov 13 (2.1.1)} {
1387<li>Bug fix: Sometimes arbitrary strings were passed to the callback
1388 function when the actual value of a column was NULL.</li>
1389}
1390
1391chng {2001 Nov 12 (2.1.0)} {
1392<li>Change the format of data records so that records up to 16MB in size
1393 can be stored.</li>
1394<li>Change the format of indices to allow for better query optimization.</li>
1395<li>Implement the "LIMIT ... OFFSET ..." clause on SELECT statements.</li>
1396}
1397
1398chng {2001 Nov 3 (2.0.8)} {
1399<li>Made selected parameters in API functions <b>const</b>. This should
1400 be fully backwards compatible.</li>
1401<li>Documentation updates</li>
1402<li>Simplify the design of the VDBE by restricting the number of sorters
1403 and lists to 1.
1404 In practice, no more than one sorter and one list was ever used anyhow.
1405 </li>
1406}
1407
1408chng {2001 Oct 21 (2.0.7)} {
1409<li>Any UTF-8 character or ISO8859 character can be used as part of
1410 an identifier.</li>
1411<li>Patches from Christian Werner to improve ODBC compatibility and to
1412 fix a bug in the round() function.</li>
1413<li>Plug some memory leaks that use to occur if malloc() failed.
1414 We have been and continue to be memory leak free as long as
1415 malloc() works.</li>
1416<li>Changes to some test scripts so that they work on Windows in
1417 addition to Unix.</li>
1418}
1419
1420chng {2001 Oct 19 (2.0.6)} {
1421<li>Added the EMPTY_RESULT_CALLBACKS pragma</li>
1422<li>Support for UTF-8 and ISO8859 characters in column and table names.</li>
1423<li>Bug fix: Compute correct table names with the FULL_COLUMN_NAMES pragma
1424 is turned on.</li>
1425}
1426
1427chng {2001 Oct 14 (2.0.5)} {
1428<li>Added the COUNT_CHANGES pragma.</li>
1429<li>Changes to the FULL_COLUMN_NAMES pragma to help out the ODBC driver.</li>
1430<li>Bug fix: "SELECT count(*)" was returning NULL for empty tables.
1431 Now it returns 0.</li>
1432}
1433
1434chng {2001 Oct 13 (2.0.4)} {
1435<li>Bug fix: an obscure and relatively harmless bug was causing one of
1436 the tests to fail when gcc optimizations are turned on. This release
1437 fixes the problem.</li>
1438}
1439
1440chng {2001 Oct 13 (2.0.3)} {
1441<li>Bug fix: the <b>sqlite_busy_timeout()</b> function was delaying 1000
1442 times too long before failing.</li>
1443<li>Bug fix: an assertion was failing if the disk holding the database
1444 file became full or stopped accepting writes for some other reason.
1445 New tests were added to detect similar problems in the future.</li>
1446<li>Added new operators: <b>&amp;</b> (bitwise-and)
1447 <b>|</b> (bitwise-or), <b>~</b> (ones-complement),
1448 <b>&lt;&lt;</b> (shift left), <b>&gt;&gt;</b> (shift right).</li>
1449<li>Added new functions: <b>round()</b> and <b>abs()</b>.</li>
1450}
1451
1452chng {2001 Oct 9 (2.0.2)} {
1453<li>Fix two bugs in the locking protocol. (One was masking the other.)</li>
1454<li>Removed some unused "#include <unistd.h>" that were causing problems
1455 for VC++.</li>
1456<li>Fixed <b>sqlite.h</b> so that it is usable from C++</li>
1457<li>Added the FULL_COLUMN_NAMES pragma. When set to "ON", the names of
1458 columns are reported back as TABLE.COLUMN instead of just COLUMN.</li>
1459<li>Added the TABLE_INFO() and INDEX_INFO() pragmas to help support the
1460 ODBC interface.</li>
1461<li>Added support for TEMPORARY tables and indices.</li>
1462}
1463
1464chng {2001 Oct 2 (2.0.1)} {
1465<li>Remove some C++ style comments from btree.c so that it will compile
1466 using compilers other than gcc.</li>
1467<li>The ".dump" output from the shell does not work if there are embedded
1468 newlines anywhere in the data. This is an old bug that was carried
1469 forward from version 1.0. To fix it, the ".dump" output no longer
1470 uses the COPY command. It instead generates INSERT statements.</li>
1471<li>Extend the expression syntax to support "expr NOT NULL" (with a
1472 space between the "NOT" and the "NULL") in addition to "expr NOTNULL"
1473 (with no space).</li>
1474}
1475
1476chng {2001 Sep 28 (2.0.0)} {
1477<li>Automatically build binaries for Linux and Windows and put them on
1478 the website.</li>
1479}
1480
1481chng {2001 Sep 28 (2.0-alpha-4)} {
1482<li>Incorporate makefile patches form A. Rottmann to use LIBTOOL</li>
1483}
1484
1485chng {2001 Sep 27 (2.0-alpha-3)} {
1486<li>SQLite now honors the UNIQUE keyword in CREATE UNIQUE INDEX. Primary
1487 keys are required to be unique.</li>
1488<li>File format changed back to what it was for alpha-1</li>
1489<li>Fixes to the rollback and locking behavior</li>
1490}
1491
1492chng {2001 Sep 20 (2.0-alpha-2)} {
1493<li>Initial release of version 2.0. The idea of renaming the library
1494 to "SQLus" was abandoned in favor of keeping the "SQLite" name and
1495 bumping the major version number.</li>
1496<li>The pager and btree subsystems added back. They are now the only
1497 available backend.</li>
1498<li>The Dbbe abstraction and the GDBM and memory drivers were removed.</li>
1499<li>Copyright on all code was disclaimed. The library is now in the
1500 public domain.</li>
1501}
1502
1503chng {2001 Jul 23 (1.0.32)} {
1504<li>Pager and btree subsystems removed. These will be used in a follow-on
1505 SQL server library named "SQLus".</li>
1506<li>Add the ability to use quoted strings as table and column names in
1507 expressions.</li>
1508}
1509
1510chng {2001 Apr 14 (1.0.31)} {
1511<li>Pager subsystem added but not yet used.</li>
1512<li>More robust handling of out-of-memory errors.</li>
1513<li>New tests added to the test suite.</li>
1514}
1515
1516chng {2001 Apr 6 (1.0.30)} {
1517<li>Remove the <b>sqlite_encoding</b> TCL variable that was introduced
1518 in the previous version.</li>
1519<li>Add options <b>-encoding</b> and <b>-tcl-uses-utf</b> to the
1520 <b>sqlite</b> TCL command.</li>
1521<li>Add tests to make sure that tclsqlite was compiled using Tcl header
1522 files and libraries that match.</li>
1523}
1524
1525chng {2001 Apr 5 (1.0.29)} {
1526<li>The library now assumes data is stored as UTF-8 if the --enable-utf8
1527 option is given to configure. The default behavior is to assume
1528 iso8859-x, as it has always done. This only makes a difference for
1529 LIKE and GLOB operators and the LENGTH and SUBSTR functions.</li>
1530<li>If the library is not configured for UTF-8 and the Tcl library
1531 is one of the newer ones that uses UTF-8 internally,
1532 then a conversion from UTF-8 to iso8859 and
1533 back again is done inside the TCL interface.</li>
1534}
1535
1536chng {2001 Apr 4 (1.0.28)} {
1537<li>Added limited support for transactions. At this point, transactions
1538 will do table locking on the GDBM backend. There is no support (yet)
1539 for rollback or atomic commit.</li>
1540<li>Added special column names ROWID, OID, and _ROWID_ that refer to the
1541 unique random integer key associated with every row of every table.</li>
1542<li>Additional tests added to the regression suite to cover the new ROWID
1543 feature and the TCL interface bugs mentioned below.</li>
1544<li>Changes to the "lemon" parser generator to help it work better when
1545 compiled using MSVC.</li>
1546<li>Bug fixes in the TCL interface identified by Oleg Oleinick.</li>
1547}
1548
1549chng {2001 Mar 20 (1.0.27)} {
1550<li>When doing DELETE and UPDATE, the library used to write the record
1551 numbers of records to be deleted or updated into a temporary file.
1552 This is changed so that the record numbers are held in memory.</li>
1553<li>The DELETE command without a WHILE clause just removes the database
1554 files from the disk, rather than going through and deleting record
1555 by record.</li>
1556}
1557
1558chng {2001 Mar 20 (1.0.26)} {
1559<li>A serious bug fixed on Windows. Windows users should upgrade.
1560 No impact to Unix.</li>
1561}
1562
1563chng {2001 Mar 15 (1.0.25)} {
1564<li>Modify the test scripts to identify tests that depend on system
1565 load and processor speed and
1566 to warn the user that a failure of one of those (rare) tests does
1567 not necessarily mean the library is malfunctioning. No changes to
1568 code.
1569 </li>
1570}
1571
1572chng {2001 Mar 14 (1.0.24)} {
1573<li>Fix a bug which was causing
1574 the UPDATE command to fail on systems where "malloc(0)" returns
1575 NULL. The problem does not appear Windows, Linux, or HPUX but does
1576 cause the library to fail on QNX.
1577 </li>
1578}
1579
1580chng {2001 Feb 19 (1.0.23)} {
1581<li>An unrelated (and minor) bug from Mark Muranwski fixed. The algorithm
1582 for figuring out where to put temporary files for a "memory:" database
1583 was not working quite right.
1584 </li>
1585}
1586
1587chng {2001 Feb 19 (1.0.22)} {
1588<li>The previous fix was not quite right. This one seems to work better.
1589 </li>
1590}
1591
1592chng {2001 Feb 19 (1.0.21)} {
1593<li>The UPDATE statement was not working when the WHERE clause contained
1594 some terms that could be satisfied using indices and other terms that
1595 could not. Fixed.</li>
1596}
1597
1598chng {2001 Feb 11 (1.0.20)} {
1599<li>Merge development changes into the main trunk. Future work toward
1600 using a BTree file structure will use a separate CVS source tree. This
1601 CVS tree will continue to support the GDBM version of SQLite only.</li>
1602}
1603
1604chng {2001 Feb 6 (1.0.19)} {
1605<li>Fix a strange (but valid) C declaration that was causing problems
1606 for QNX. No logical changes.</li>
1607}
1608
1609chng {2001 Jan 4 (1.0.18)} {
1610<li>Print the offending SQL statement when an error occurs.</li>
1611<li>Do not require commas between constraints in CREATE TABLE statements.</li>
1612<li>Added the "-echo" option to the shell.</li>
1613<li>Changes to comments.</li>
1614}
1615
1616chng {2000 Dec 10 (1.0.17)} {
1617<li>Rewrote <b>sqlite_complete()</b> to make it faster.</li>
1618<li>Minor tweaks to other code to make it run a little faster.</li>
1619<li>Added new tests for <b>sqlite_complete()</b> and for memory leaks.</li>
1620}
1621
1622chng {2000 Dec 4 (1.0.16)} {
1623<li>Documentation updates. Mostly fixing of typos and spelling errors.</li>
1624}
1625
1626chng {2000 Oct 23 (1.0.15)} {
1627<li>Documentation updates</li>
1628<li>Some sanity checking code was removed from the inner loop of vdbe.c
1629 to help the library to run a little faster. The code is only
1630 removed if you compile with -DNDEBUG.</li>
1631}
1632
1633chng {2000 Oct 19 (1.0.14)} {
1634<li>Added a "memory:" backend driver that stores its database in an
1635 in-memory hash table.</li>
1636}
1637
1638chng {2000 Oct 18 (1.0.13)} {
1639<li>Break out the GDBM driver into a separate file in anticipation
1640 to added new drivers.</li>
1641<li>Allow the name of a database to be prefixed by the driver type.
1642 For now, the only driver type is "gdbm:".</li>
1643}
1644
1645chng {2000 Oct 16 (1.0.12)} {
1646<li>Fixed an off-by-one error that was causing a coredump in
1647 the '%q' format directive of the new
1648 <b>sqlite_..._printf()</b> routines.</li>
1649<li>Added the <b>sqlite_interrupt()</b> interface.</li>
1650<li>In the shell, <b>sqlite_interrupt()</b> is invoked when the
1651 user presses Control-C</li>
1652<li>Fixed some instances where <b>sqlite_exec()</b> was
1653 returning the wrong error code.</li>
1654}
1655
1656chng {2000 Oct 11 (1.0.10)} {
1657<li>Added notes on how to compile for Windows95/98.</li>
1658<li>Removed a few variables that were not being used. Etc.</li>
1659}
1660
1661chng {2000 Oct 8 (1.0.9)} {
1662<li>Added the <b>sqlite_..._printf()</b> interface routines.</li>
1663<li>Modified the <b>sqlite</b> shell program to use the new interface
1664 routines.</li>
1665<li>Modified the <b>sqlite</b> shell program to print the schema for
1666 the built-in SQLITE_MASTER table, if explicitly requested.</li>
1667}
1668
1669chng {2000 Sep 30 (1.0.8)} {
1670<li>Begin writing documentation on the TCL interface.</li>
1671}
1672
1673chng {2000 Sep 29 (Not Released)} {
1674<li>Added the <b>sqlite_get_table()</b> API</li>
1675<li>Updated the documentation for due to the above change.</li>
1676<li>Modified the <b>sqlite</b> shell to make use of the new
1677 sqlite_get_table() API in order to print a list of tables
1678 in multiple columns, similar to the way "ls" prints filenames.</li>
1679<li>Modified the <b>sqlite</b> shell to print a semicolon at the
1680 end of each CREATE statement in the output of the ".schema" command.</li>
1681}
1682
1683chng {2000 Sep 21 (Not Released)} {
1684<li>Change the tclsqlite "eval" method to return a list of results if
1685 no callback script is specified.</li>
1686<li>Change tclsqlite.c to use the Tcl_Obj interface</li>
1687<li>Add tclsqlite.c to the libsqlite.a library</li>
1688}
1689
1690chng {2000 Sep 13 (Version 1.0.5)} {
1691<li>Changed the print format for floating point values from "%g" to "%.15g".
1692 </li>
1693<li>Changed the comparison function so that numbers in exponential notation
1694 (ex: 1.234e+05) sort in numerical order.</li>
1695}
1696
1697chng {2000 Aug 28 (Version 1.0.4)} {
1698<li>Added functions <b>length()</b> and <b>substr()</b>.</li>
1699<li>Fix a bug in the <b>sqlite</b> shell program that was causing
1700 a coredump when the output mode was "column" and the first row
1701 of data contained a NULL.</li>
1702}
1703
1704chng {2000 Aug 22 (Version 1.0.3)} {
1705<li>In the sqlite shell, print the "Database opened READ ONLY" message
1706 to stderr instead of stdout.</li>
1707<li>In the sqlite shell, now print the version number on initial startup.</li>
1708<li>Add the <b>sqlite_version[]</b> string constant to the library</li>
1709<li>Makefile updates</li>
1710<li>Bug fix: incorrect VDBE code was being generated for the following
1711 circumstance: a query on an indexed table containing a WHERE clause with
1712 an IN operator that had a subquery on its right-hand side.</li>
1713}
1714
1715chng {2000 Aug 18 (Version 1.0.1)} {
1716<li>Fix a bug in the configure script.</li>
1717<li>Minor revisions to the website.</li>
1718}
1719
1720chng {2000 Aug 17 (Version 1.0)} {
1721<li>Change the <b>sqlite</b> program so that it can read
1722 databases for which it lacks write permission. (It used to
1723 refuse all access if it could not write.)</li>
1724}
1725
1726chng {2000 Aug 9} {
1727<li>Treat carriage returns as white space.</li>
1728}
1729
1730chng {2000 Aug 8} {
1731<li>Added pattern matching to the ".table" command in the "sqlite"
1732command shell.</li>
1733}
1734
1735chng {2000 Aug 4} {
1736<li>Documentation updates</li>
1737<li>Added "busy" and "timeout" methods to the Tcl interface</li>
1738}
1739
1740chng {2000 Aug 3} {
1741<li>File format version number was being stored in sqlite_master.tcl
1742 multiple times. This was harmless, but unnecessary. It is now fixed.</li>
1743}
1744
1745chng {2000 Aug 2} {
1746<li>The file format for indices was changed slightly in order to work
1747 around an inefficiency that can sometimes come up with GDBM when
1748 there are large indices having many entries with the same key.
1749 <font color="red">** Incompatible Change **</font></li>
1750}
1751
1752chng {2000 Aug 1} {
1753<li>The parser's stack was overflowing on a very long UPDATE statement.
1754 This is now fixed.</li>
1755}
1756
1757chng {2000 July 31} {
1758<li>Finish the <a href="vdbe.html">VDBE tutorial</a>.</li>
1759<li>Added documentation on compiling to WindowsNT.</li>
1760<li>Fix a configuration program for WindowsNT.</li>
1761<li>Fix a configuration problem for HPUX.</li>
1762}
1763
1764chng {2000 July 29} {
1765<li>Better labels on column names of the result.</li>
1766}
1767
1768chng {2000 July 28} {
1769<li>Added the <b>sqlite_busy_handler()</b>
1770 and <b>sqlite_busy_timeout()</b> interface.</li>
1771}
1772
1773chng {2000 June 23} {
1774<li>Begin writing the <a href="vdbe.html">VDBE tutorial</a>.</li>
1775}
1776
1777chng {2000 June 21} {
1778<li>Clean up comments and variable names. Changes to documentation.
1779 No functional changes to the code.</li>
1780}
1781
1782chng {2000 June 19} {
1783<li>Column names in UPDATE statements were case sensitive.
1784 This mistake has now been fixed.</li>
1785}
1786
1787chng {2000 June 16} {
1788<li>Added the concatenate string operator (||)</li>
1789}
1790
1791chng {2000 June 12} {
1792<li>Added the fcnt() function to the SQL interpreter. The fcnt() function
1793 returns the number of database "Fetch" operations that have occurred.
1794 This function is designed for use in test scripts to verify that
1795 queries are efficient and appropriately optimized. Fcnt() has no other
1796 useful purpose, as far as I know.</li>
1797<li>Added a bunch more tests that take advantage of the new fcnt() function.
1798 The new tests did not uncover any new problems.</li>
1799}
1800
1801chng {2000 June 8} {
1802<li>Added lots of new test cases</li>
1803<li>Fix a few bugs discovered while adding test cases</li>
1804<li>Begin adding lots of new documentation</li>
1805}
1806
1807chng {2000 June 6} {
1808<li>Added compound select operators: <B>UNION</b>, <b>UNION ALL</B>,
1809<b>INTERSECT</b>, and <b>EXCEPT</b></li>
1810<li>Added support for using <b>(SELECT ...)</b> within expressions</li>
1811<li>Added support for <b>IN</b> and <b>BETWEEN</b> operators</li>
1812<li>Added support for <b>GROUP BY</b> and <b>HAVING</b></li>
1813<li>NULL values are now reported to the callback as a NULL pointer
1814 rather than an empty string.</li>
1815}
1816
1817chng {2000 June 3} {
1818<li>Added support for default values on columns of a table.</li>
1819<li>Improved test coverage. Fixed a few obscure bugs found by the
1820improved tests.</li>
1821}
1822
1823chng {2000 June 2} {
1824<li>All database files to be modified by an UPDATE, INSERT or DELETE are
1825now locked before any changes are made to any files.
1826This makes it safe (I think) to access
1827the same database simultaneously from multiple processes.</li>
1828<li>The code appears stable so we are now calling it "beta".</li>
1829}
1830
1831chng {2000 June 1} {
1832<li>Better support for file locking so that two or more processes
1833(or threads)
1834can access the same database simultaneously. More work needed in
1835this area, though.</li>
1836}
1837
1838chng {2000 May 31} {
1839<li>Added support for aggregate functions (Ex: <b>COUNT(*)</b>, <b>MIN(...)</b>)
1840to the SELECT statement.</li>
1841<li>Added support for <B>SELECT DISTINCT ...</B></li>
1842}
1843
1844chng {2000 May 30} {
1845<li>Added the <b>LIKE</b> operator.</li>
1846<li>Added a <b>GLOB</b> operator: similar to <B>LIKE</B>
1847but it uses Unix shell globbing wildcards instead of the '%'
1848and '_' wildcards of SQL.</li>
1849<li>Added the <B>COPY</b> command patterned after
1850<a href="http://www.postgresql.org/">PostgreSQL</a> so that SQLite
1851can now read the output of the <b>pg_dump</b> database dump utility
1852of PostgreSQL.</li>
1853<li>Added a <B>VACUUM</B> command that that calls the
1854<b>gdbm_reorganize()</b> function on the underlying database
1855files.</li>
1856<li>And many, many bug fixes...</li>
1857}
1858
1859chng {2000 May 29} {
1860<li>Initial Public Release of Alpha code</li>
1861}
1862
1863puts {
1864</DL>
1865}
1866footer {$Id:}
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/common.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/common.tcl
deleted file mode 100644
index 07129f8..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/common.tcl
+++ /dev/null
@@ -1,90 +0,0 @@
1# This file contains TCL procedures used to generate standard parts of
2# web pages.
3#
4
5proc header {txt} {
6 puts "<html><head><title>$txt</title></head>"
7 puts {<DIV class="pdf_ignore">}
8 puts \
9{<body bgcolor="white" link="#50695f" vlink="#508896">
10<table width="100%" border="0">
11<tr><td valign="top">
12<a href="index.html"><img src="sqlite.gif" border="none"></a></td>
13<td width="100%"></td>
14<td valign="bottom">
15<ul>
16<li><a href="http://www.sqlite.org/cvstrac/tktnew">bugs</a></li>
17<li><a href="changes.html">changes</a></li>
18<li><a href="contrib">contrib</a></li>
19<li><a href="download.html#cvs">cvs&nbsp;repository</a></li>
20<li><a href="docs.html">documentation</a></li>
21</ul>
22</td>
23<td width="10"></td>
24<td valign="bottom">
25<ul>
26<li><a href="download.html">download</a></li>
27<li><a href="faq.html">faq</a></li>
28<li><a href="index.html">home</a></li>
29<li><a href="copyright.html">license</a></li>
30<li><a href="index.html">news</a></li>
31</ul>
32</td>
33<td width="10"></td>
34<td valign="bottom">
35<ul>
36<li><a href="quickstart.html">quick&nbsp;start</a></li>
37<li><a href="support.html">support</a></li>
38<li><a href="lang.html">syntax</a></li>
39<li><a href="http://www.sqlite.org/cvstrac/timeline">timeline</a></li>
40<li><a href="http://www.sqlite.org/cvstrac/wiki">wiki</a></li>
41</ul>
42</td>
43</tr></table>
44<table width="100%">
45<tr><td bgcolor="#80a796"></td></tr>
46</table>}
47 puts </DIV>
48}
49
50proc footer {{rcsid {}}} {
51 puts {
52<table width="100%">
53<tr><td bgcolor="#80a796"></td></tr>
54</table>}
55 set date [lrange $rcsid 3 4]
56 if {$date!=""} {
57 puts "<small><i>This page last modified on $date</i></small>"
58 }
59 puts {</body></html>}
60}
61
62
63# The following proc is used to ensure consistent formatting in the
64# HTML generated by lang.tcl and pragma.tcl.
65#
66proc Syntax {args} {
67 puts {<table cellpadding="10" class=pdf_syntax>}
68 foreach {rule body} $args {
69 puts "<tr><td align=\"right\" valign=\"top\">"
70 puts "<i><font color=\"#ff3434\">$rule</font></i>&nbsp;::=</td>"
71 regsub -all < $body {%LT} body
72 regsub -all > $body {%GT} body
73 regsub -all %LT $body {</font></b><i><font color="#ff3434">} body
74 regsub -all %GT $body {</font></i><b><font color="#2c2cf0">} body
75 regsub -all {[]|[*?]} $body {</font></b>&<b><font color="#2c2cf0">} body
76 regsub -all "\n" [string trim $body] "<br>\n" body
77 regsub -all "\n *" $body "\n\\&nbsp;\\&nbsp;\\&nbsp;\\&nbsp;" body
78 regsub -all {[|,.*()]} $body {<big>&</big>} body
79 regsub -all { = } $body { <big>=</big> } body
80 regsub -all {STAR} $body {<big>*</big>} body
81 ## These metacharacters must be handled to undo being
82 ## treated as SQL punctuation characters above.
83 regsub -all {RPPLUS} $body {</font></b>)+<b><font color="#2c2cf0">} body
84 regsub -all {LP} $body {</font></b>(<b><font color="#2c2cf0">} body
85 regsub -all {RP} $body {</font></b>)<b><font color="#2c2cf0">} body
86 ## Place the left-hand side of the rule in the 2nd table column.
87 puts "<td><b><font color=\"#2c2cf0\">$body</font></b></td></tr>"
88 }
89 puts {</table>}
90}
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/compile.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/compile.tcl
deleted file mode 100644
index bdf7d22..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/compile.tcl
+++ /dev/null
@@ -1,278 +0,0 @@
1#
2# Run this Tcl script to generate the compile.html file.
3#
4set rcsid {$Id: compile.tcl,v 1.5 2005/03/19 15:10:45 drh Exp $ }
5source common.tcl
6header {Compilation Options For SQLite}
7
8puts {
9<h1>Compilation Options For SQLite</h1>
10
11<p>
12For most purposes, SQLite can be built just fine using the default
13compilation options. However, if required, the compile-time options
14documented below can be used to
15<a href="#omitfeatures">omit SQLite features</a> (resulting in
16a smaller compiled library size) or to change the
17<a href="#defaults">default values</a> of some parameters.
18</p>
19<p>
20Every effort has been made to ensure that the various combinations
21of compilation options work harmoniously and produce a working library.
22Nevertheless, it is strongly recommended that the SQLite test-suite
23be executed to check for errors before using an SQLite library built
24with non-standard compilation options.
25</p>
26<a name="defaults"></a>
27<h2>Options To Set Default Parameter Values</h2>
28
29<p><b>SQLITE_DEFAULT_AUTOVACUUM=<i>&lt;1 or 0&gt;</i></b><br>
30This macro determines if SQLite creates databases with the
31<a href="pragma.html#pragma_auto_vacuum">auto-vacuum</a>
32flag set by default. The default value is 0 (do not create auto-vacuum
33databases). In any case the compile-time default may be overridden by the
34"PRAGMA auto_vacuum" command.
35</p>
36
37<p><b>SQLITE_DEFAULT_CACHE_SIZE=<i>&lt;pages&gt;</i></b><br>
38This macro sets the default size of the page-cache for each attached
39database, in pages. This can be overridden by the "PRAGMA cache_size"
40comamnd. The default value is 2000.
41</p>
42
43<p><b>SQLITE_DEFAULT_PAGE_SIZE=<i>&lt;bytes&gt;</i></b><br>
44This macro is used to set the default page-size used when a
45database is created. The value assigned must be a power of 2. The
46default value is 1024. The compile-time default may be overridden at
47runtime by the "PRAGMA page_size" command.
48</p>
49
50<p><b>SQLITE_DEFAULT_TEMP_CACHE_SIZE=<i>&lt;pages&gt;</i></b><br>
51This macro sets the default size of the page-cache for temporary files
52created by SQLite to store intermediate results, in pages. It does
53not affect the page-cache for the temp database, where tables created
54using "CREATE TEMP TABLE" are stored. The default value is 500.
55</p>
56
57<p><b>SQLITE_MAX_PAGE_SIZE=<i>&lt;bytes&gt;</i></b><br>
58This is used to set the maximum allowable page-size that can
59be specified by the "PRAGMA page_size" command. The default value
60is 8192.
61</p>
62
63<a name="omitfeatures"></a>
64<h2>Options To Omit Features</h2>
65
66<p>The following options are used to reduce the size of the compiled
67library by omiting optional features. This is probably only useful
68in embedded systems where space is especially tight, as even with all
69features included the SQLite library is relatively small. Don't forget
70to tell your compiler to optimize for binary size! (the -Os option if
71using GCC).</p>
72
73<p>The macros in this section do not require values. The following
74compilation switches all have the same effect:<br>
75-DSQLITE_OMIT_ALTERTABLE<br>
76-DSQLITE_OMIT_ALTERTABLE=1<br>
77-DSQLITE_OMIT_ALTERTABLE=0
78</p>
79
80<p>If any of these options are defined, then the same set of SQLITE_OMIT_XXX
81options must also be defined when using the 'lemon' tool to generate a parse.c
82file. Because of this, these options may only used when the library is built
83from source, not from the collection of pre-packaged C files provided for
84non-UNIX like platforms on the website.
85</p>
86
87<p><b>SQLITE_OMIT_ALTERTABLE</b><br>
88When this option is defined, the
89<a href="lang_altertable.html">ALTER TABLE</a> command is not included in the
90library. Executing an ALTER TABLE statement causes a parse error.
91</p>
92
93<p><b>SQLITE_OMIT_AUTHORIZATION</b><br>
94Defining this option omits the authorization callback feature from the
95library. The <a href="capi3ref.html#sqlite3_set_authorizer">
96sqlite3_set_authorizer()</a> API function is not present in the library.
97</p>
98
99<p><b>SQLITE_OMIT_AUTOVACUUM</b><br>
100If this option is defined, the library cannot create or write to
101databases that support
102<a href="pragma.html#pragma_auto_vacuum">auto-vacuum</a>. Executing a
103"PRAGMA auto_vacuum" statement is not an error, but does not return a value
104or modify the auto-vacuum flag in the database file. If a database that
105supports auto-vacuum is opened by a library compiled with this option, it
106is automatically opened in read-only mode.
107</p>
108
109<p><b>SQLITE_OMIT_AUTOINCREMENT</b><br>
110This option is used to omit the AUTOINCREMENT functionality. When this
111is macro is defined, columns declared as "INTEGER PRIMARY KEY AUTOINCREMENT"
112behave in the same way as columns declared as "INTEGER PRIMARY KEY" when a
113NULL is inserted. The sqlite_sequence system table is neither created, nor
114respected if it already exists.
115</p>
116<p><i>TODO: Need a link here - AUTOINCREMENT is not yet documented</i><p>
117
118<p><b>SQLITE_OMIT_BLOB_LITERAL</b><br>
119When this option is defined, it is not possible to specify a blob in
120an SQL statement using the X'ABCD' syntax.</p>
121}
122#<p>WARNING: The VACUUM command depends on this syntax for vacuuming databases
123#that contain blobs, so disabling this functionality may render a database
124#unvacuumable.
125#</p>
126#<p><i>TODO: Need a link here - is that syntax documented anywhere?</i><p>
127puts {
128
129<p><b>SQLITE_OMIT_COMPLETE</b><br>
130This option causes the <a href="capi3ref.html#sqlite3_complete">
131sqlite3_complete</a> API to be omitted.
132</p>
133
134<p><b>SQLITE_OMIT_COMPOUND_SELECT</b><br>
135This option is used to omit the compound SELECT functionality.
136<a href="lang_select.html">SELECT statements</a> that use the
137UNION, UNION ALL, INTERSECT or EXCEPT compound SELECT operators will
138cause a parse error.
139</p>
140
141<p><b>SQLITE_OMIT_CONFLICT_CLAUSE</b><br>
142In the future, this option will be used to omit the
143<a href="lang_conflict.html">ON CONFLICT</a> clause from the library.
144</p>
145
146<p><b>SQLITE_OMIT_DATETIME_FUNCS</b><br>
147If this option is defined, SQLite's built-in date and time manipulation
148functions are omitted. Specifically, the SQL functions julianday(), date(),
149time(), datetime() and strftime() are not available. The default column
150values CURRENT_TIME, CURRENT_DATE and CURRENT_DATETIME are still available.
151</p>
152
153<p><b>SQLITE_OMIT_EXPLAIN</b><br>
154Defining this option causes the EXPLAIN command to be omitted from the
155library. Attempting to execute an EXPLAIN statement will cause a parse
156error.
157</p>
158
159<p><b>SQLITE_OMIT_FLOATING_POINT</b><br>
160This option is used to omit floating-point number support from the SQLite
161library. When specified, specifying a floating point number as a literal
162(i.e. "1.01") results in a parse error.
163</p>
164<p>In the future, this option may also disable other floating point
165functionality, for example the sqlite3_result_double(),
166sqlite3_bind_double(), sqlite3_value_double() and sqlite3_column_double()
167API functions.
168</p>
169
170<p><b>SQLITE_OMIT_FOREIGN_KEY</b><br>
171If this option is defined, FOREIGN KEY clauses in column declarations are
172ignored.
173</p>
174
175<p><b>SQLITE_OMIT_INTEGRITY_CHECK</b><br>
176This option may be used to omit the
177<a href="pragma.html#pragma_integrity_check">"PRAGMA integrity_check"</a>
178command from the compiled library.
179</p>
180
181<p><b>SQLITE_OMIT_MEMORYDB</b><br>
182When this is defined, the library does not respect the special database
183name ":memory:" (normally used to create an in-memory database). If
184":memory:" is passed to sqlite3_open(), a file with this name will be
185opened or created.
186</p>
187
188<p><b>SQLITE_OMIT_PAGER_PRAGMAS</b><br>
189Defining this option omits pragmas related to the pager subsystem from
190the build. Currently, the
191<a href="pragma.html#pragma_default_cache_size">default_cache_size</a> and
192<a href="pragma.html#pragma_cache_size">cache_size</a> pragmas are omitted.
193</p>
194
195<p><b>SQLITE_OMIT_PRAGMA</b><br>
196This option is used to omit the <a href="pragma.html">PRAGMA command</a>
197from the library. Note that it is useful to define the macros that omit
198specific pragmas in addition to this, as they may also remove supporting code
199in other sub-systems. This macro removes the PRAGMA command only.
200</p>
201
202<p><b>SQLITE_OMIT_PROGRESS_CALLBACK</b><br>
203This option may be defined to omit the capability to issue "progress"
204callbacks during long-running SQL statements. The
205<a href="capi3ref.html#sqlite3_progress_handler">sqlite3_progress_handler()</a>
206API function is not present in the library.
207
208<p><b>SQLITE_OMIT_REINDEX</b><br>
209When this option is defined, the <a href="lang_reindex.html">REINDEX</a>
210command is not included in the library. Executing a REINDEX statement causes
211a parse error.
212</p>
213
214<p><b>SQLITE_OMIT_SCHEMA_PRAGMAS</b><br>
215Defining this option omits pragmas for querying the database schema from
216the build. Currently, the
217<a href="pragma.html#pragma_table_info">table_info</a>,
218<a href="pragma.html#pragma_index_info">index_info</a>,
219<a href="pragma.html#pragma_index_list">index_list</a> and
220<a href="pragma.html#pragma_database_list">database_list</a>
221pragmas are omitted.
222</p>
223
224<p><b>SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS</b><br>
225Defining this option omits pragmas for querying and modifying the
226database schema version and user version from the build. Specifically, the
227<a href="pragma.html#pragma_schema_version">schema_version</a> and
228<a href="pragma.html#pragma_user_version">user_version</a>
229pragmas are omitted.
230
231<p><b>SQLITE_OMIT_SUBQUERY</b><br>
232<p>If defined, support for sub-selects and the IN() operator are omitted.
233</p>
234
235<p><b>SQLITE_OMIT_TCL_VARIABLE</b><br>
236<p>If this macro is defined, then the special "$<variable-name>" syntax
237used to automatically bind SQL variables to TCL variables is omitted.
238</p>
239
240<p><b>SQLITE_OMIT_TRIGGER</b><br>
241Defining this option omits support for VIEW objects. Neither the
242<a href="lang_createtrigger.html">CREATE TRIGGER</a> or
243<a href="lang_droptrigger.html">DROP TRIGGER</a>
244commands are available in this case, attempting to execute either will result
245in a parse error.
246</p>
247<p>
248WARNING: If this macro is defined, it will not be possible to open a database
249for which the schema contains TRIGGER objects.
250</p>
251
252<p><b>SQLITE_OMIT_UTF16</b><br>
253This macro is used to omit support for UTF16 text encoding. When this is
254defined all API functions that return or accept UTF16 encoded text are
255unavailable. These functions can be identified by the fact that they end
256with '16', for example sqlite3_prepare16(), sqlite3_column_text16() and
257sqlite3_bind_text16().
258</p>
259
260<p><b>SQLITE_OMIT_VACUUM</b><br>
261When this option is defined, the <a href="lang_vacuum.html">VACUUM</a>
262command is not included in the library. Executing a VACUUM statement causes
263a parse error.
264</p>
265
266<p><b>SQLITE_OMIT_VIEW</b><br>
267Defining this option omits support for VIEW objects. Neither the
268<a href="lang_createview.html">CREATE VIEW</a> or
269<a href="lang_dropview.html">DROP VIEW</a>
270commands are available in this case, attempting to execute either will result
271in a parse error.
272</p>
273<p>
274WARNING: If this macro is defined, it will not be possible to open a database
275for which the schema contains VIEW objects.
276</p>
277}
278footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/conflict.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/conflict.tcl
deleted file mode 100644
index 2d11639..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/conflict.tcl
+++ /dev/null
@@ -1,91 +0,0 @@
1#
2# Run this Tcl script to generate the constraint.html file.
3#
4set rcsid {$Id: conflict.tcl,v 1.4 2004/10/10 17:24:55 drh Exp $ }
5source common.tcl
6header {Constraint Conflict Resolution in SQLite}
7puts {
8<h1>Constraint Conflict Resolution in SQLite</h1>
9
10<p>
11In most SQL databases, if you have a UNIQUE constraint on
12a table and you try to do an UPDATE or INSERT that violates
13the constraint, the database will abort the operation in
14progress, back out any prior changes associated with
15UPDATE or INSERT command, and return an error.
16This is the default behavior of SQLite.
17Beginning with version 2.3.0, though, SQLite allows you to
18define alternative ways for dealing with constraint violations.
19This article describes those alternatives and how to use them.
20</p>
21
22<h2>Conflict Resolution Algorithms</h2>
23
24<p>
25SQLite defines five constraint conflict resolution algorithms
26as follows:
27</p>
28
29<dl>
30<dt><b>ROLLBACK</b></dt>
31<dd><p>When a constraint violation occurs, an immediate ROLLBACK
32occurs, thus ending the current transaction, and the command aborts
33with a return code of SQLITE_CONSTRAINT. If no transaction is
34active (other than the implied transaction that is created on every
35command) then this algorithm works the same as ABORT.</p></dd>
36
37<dt><b>ABORT</b></dt>
38<dd><p>When a constraint violation occurs, the command backs out
39any prior changes it might have made and aborts with a return code
40of SQLITE_CONSTRAINT. But no ROLLBACK is executed so changes
41from prior commands within the same transaction
42are preserved. This is the default behavior for SQLite.</p></dd>
43
44<dt><b>FAIL</b></dt>
45<dd><p>When a constraint violation occurs, the command aborts with a
46return code SQLITE_CONSTRAINT. But any changes to the database that
47the command made prior to encountering the constraint violation
48are preserved and are not backed out. For example, if an UPDATE
49statement encountered a constraint violation on the 100th row that
50it attempts to update, then the first 99 row changes are preserved
51by change to rows 100 and beyond never occur.</p></dd>
52
53<dt><b>IGNORE</b></dt>
54<dd><p>When a constraint violation occurs, the one row that contains
55the constraint violation is not inserted or changed. But the command
56continues executing normally. Other rows before and after the row that
57contained the constraint violation continue to be inserted or updated
58normally. No error is returned.</p></dd>
59
60<dt><b>REPLACE</b></dt>
61<dd><p>When a UNIQUE constraint violation occurs, the pre-existing row
62that caused the constraint violation is removed prior to inserting
63or updating the current row. Thus the insert or update always occurs.
64The command continues executing normally. No error is returned.</p></dd>
65</dl>
66
67<h2>Why So Many Choices?</h2>
68
69<p>SQLite provides multiple conflict resolution algorithms for a
70couple of reasons. First, SQLite tries to be roughly compatible with as
71many other SQL databases as possible, but different SQL database
72engines exhibit different conflict resolution strategies. For
73example, PostgreSQL always uses ROLLBACK, Oracle always uses ABORT, and
74MySQL usually uses FAIL but can be instructed to use IGNORE or REPLACE.
75By supporting all five alternatives, SQLite provides maximum
76portability.</p>
77
78<p>Another reason for supporting multiple algorithms is that sometimes
79it is useful to use an algorithm other than the default.
80Suppose, for example, you are
81inserting 1000 records into a database, all within a single
82transaction, but one of those records is malformed and causes
83a constraint error. Under PostgreSQL or Oracle, none of the
841000 records would get inserted. In MySQL, some subset of the
85records that appeared before the malformed record would be inserted
86but the rest would not. Neither behavior is especially helpful.
87What you really want is to use the IGNORE algorithm to insert
88all but the malformed record.</p>
89
90}
91footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/copyright-release.html b/libraries/sqlite/unix/sqlite-3.5.1/www/copyright-release.html
deleted file mode 100644
index bc0c764..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/copyright-release.html
+++ /dev/null
@@ -1,109 +0,0 @@
1<html>
2<body bgcolor="white">
3<h1 align="center">
4Copyright Release for<br>
5Contributions To SQLite
6</h1>
7
8<p>
9SQLite is software that implements an embeddable SQL database engine.
10SQLite is available for free download from http://www.sqlite.org/.
11The principal author and maintainer of SQLite has disclaimed all
12copyright interest in his contributions to SQLite
13and thus released his contributions into the public domain.
14In order to keep the SQLite software unencumbered by copyright
15claims, the principal author asks others who may from time to
16time contribute changes and enhancements to likewise disclaim
17their own individual copyright interest.
18</p>
19
20<p>
21Because the SQLite software found at http://www.sqlite.org/ is in the
22public domain, anyone is free to download the SQLite software
23from that website, make changes to the software, use, distribute,
24or sell the modified software, under either the original name or
25under some new name, without any need to obtain permission, pay
26royalties, acknowledge the original source of the software, or
27in any other way compensate, identify, or notify the original authors.
28Nobody is in any way compelled to contribute their SQLite changes and
29enhancements back to the SQLite website. This document concerns
30only changes and enhancements to SQLite that are intentionally and
31deliberately contributed back to the SQLite website.
32</p>
33
34<p>
35For the purposes of this document, "SQLite software" shall mean any
36computer source code, documentation, makefiles, test scripts, or
37other information that is published on the SQLite website,
38http://www.sqlite.org/. Precompiled binaries are excluded from
39the definition of "SQLite software" in this document because the
40process of compiling the software may introduce information from
41outside sources which is not properly a part of SQLite.
42</p>
43
44<p>
45The header comments on the SQLite source files exhort the reader to
46share freely and to never take more than one gives.
47In the spirit of that exhortation I make the following declarations:
48</p>
49
50<ol>
51<li><p>
52I dedicate to the public domain
53any and all copyright interest in the SQLite software that
54was publicly available on the SQLite website (http://www.sqlite.org/) prior
55to the date of the signature below and any changes or enhancements to
56the SQLite software
57that I may cause to be published on that website in the future.
58I make this dedication for the benefit of the public at large and
59to the detriment of my heirs and successors. I intend this
60dedication to be an overt act of relinquishment in perpetuity of
61all present and future rights to the SQLite software under copyright
62law.
63</p></li>
64
65<li><p>
66To the best of my knowledge and belief, the changes and enhancements that
67I have contributed to SQLite are either originally written by me
68or are derived from prior works which I have verified are also
69in the public domain and are not subject to claims of copyright
70by other parties.
71</p></li>
72
73<li><p>
74To the best of my knowledge and belief, no individual, business, organization,
75government, or other entity has any copyright interest
76in the SQLite software as it existed on the
77SQLite website as of the date on the signature line below.
78</p></li>
79
80<li><p>
81I agree never to publish any additional information
82to the SQLite website (by CVS, email, scp, FTP, or any other means) unless
83that information is an original work of authorship by me or is derived from
84prior published versions of SQLite.
85I agree never to copy and paste code into the SQLite code base from
86other sources.
87I agree never to publish on the SQLite website any information that
88would violate a law or breach a contract.
89</p></li>
90</ol>
91
92<p>
93<table width="100%" cellpadding="0" cellspacing="0">
94<tr>
95<td width="60%" valign="top">
96Signature:
97<p>&nbsp;</p>
98<p>&nbsp;</p>
99<p>&nbsp;</p>
100</td><td valign="top" align="left">
101Date:
102</td></tr>
103<td colspan=2>
104Name (printed):
105</td>
106</tr>
107</table>
108</body>
109</html>
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/copyright-release.pdf b/libraries/sqlite/unix/sqlite-3.5.1/www/copyright-release.pdf
deleted file mode 100644
index 9465d31..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/copyright-release.pdf
+++ /dev/null
Binary files differ
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/copyright.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/copyright.tcl
deleted file mode 100644
index 7468744..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/copyright.tcl
+++ /dev/null
@@ -1,126 +0,0 @@
1set rcsid {$Id: copyright.tcl,v 1.7 2007/05/06 21:20:43 drh Exp $}
2source common.tcl
3header {SQLite Copyright}
4puts {
5<h2>SQLite Copyright</h2>
6
7<table align="right" vspace="0" hspace="10" border="1" cellpadding="20">
8<tr><td align="center">
9<img src="nocopy.gif"><br>
10SQLite is in the<br>
11<a href="http://en.wikipedia.org/wiki/Public_Domain">Public Domain</a>
12</td></tr>
13</table>
14
15<p>
16All of the deliverable code in SQLite has been dedicated to the
17<a href="http://en.wikipedia.org/wiki/Public_Domain">public domain</a>
18by the authors.
19All code authors, and representatives of the companies they work for,
20have signed affidavits dedicating their contributions to
21the public domain and originals of
22those signed affidavits are stored in a firesafe at the main offices
23of <a href="http://www.hwaci.com">Hwaci</a>.
24Anyone is free to copy, modify, publish, use, compile, sell, or distribute
25the original SQLite code, either in source code form or as a compiled binary,
26for any purpose, commercial or non-commercial, and by any means.
27</p>
28
29<p>
30The previous paragraph applies to the deliverable code in SQLite -
31those parts of the SQLite library that you actually bundle and
32ship with a larger application. Portions of the documentation and
33some code used as part of the build process might fall under
34other licenses. The details here are unclear. We do not worry
35about the licensing of the documentation and build code so much
36because none of these things are part of the core deliverable
37SQLite library.
38</p>
39
40<p>
41All of the deliverable code in SQLite has been written from scratch.
42No code has been taken from other projects or from the open
43internet. Every line of code can be traced back to its original
44author, and all of those authors have public domain dedications
45on file. So the SQLite code base is clean and is
46uncontaminated with licensed code from other projects.
47</p>
48
49<h2>Obtaining An Explicit License To Use SQLite</h2>
50
51<p>
52Even though SQLite is in the public domain and does not require
53a license, some users want to obtain a license anyway. Some reasons
54for obtaining a license include:
55</p>
56
57<ul>
58<li> You are using SQLite in a jurisdiction that does not recognize
59 the public domain. </li>
60<li> You are using SQLite in a jurisdiction that does not recognize
61 the right of an author to dedicate their work to the public
62 domain. </li>
63<li> You want to hold a tangible legal document
64 as evidence that you have the legal right to use and distribute
65 SQLite. </li>
66<li> Your legal department tells you that you have to purchase a license.
67 </li>
68</ul>
69
70<p>
71If you feel like you really have to purchase a license for SQLite,
72<a href="http://www.hwaci.com/">Hwaci</a>, the company that employs
73the architect and principal developers of SQLite, will sell you
74one.
75Please contact:
76</p>
77
78<blockquote>
79D. Richard Hipp <br />
80Hwaci - Applied Software Research <br />
81704.948.4565 <br />
82<a href="mailto:drh@hwaci.com">drh@hwaci.com</a>
83</blockquote>
84
85<h2>Contributed Code</h2>
86
87<p>
88In order to keep SQLite completely free and unencumbered by copyright,
89all new contributors to the SQLite code base are asked to dedicate
90their contributions to the public domain.
91If you want to send a patch or enhancement for possible inclusion in the
92SQLite source tree, please accompany the patch with the following statement:
93</p>
94
95<blockquote><i>
96The author or authors of this code dedicate any and all copyright interest
97in this code to the public domain. We make this dedication for the benefit
98of the public at large and to the detriment of our heirs and successors.
99We intend this dedication to be an overt act of relinquishment in
100perpetuity of all present and future rights to this code under copyright law.
101</i></blockquote>
102
103<p>
104We are not able to accept patches or changes to
105SQLite that are not accompanied by a statement such as the above.
106In addition, if you make
107changes or enhancements as an employee, then a simple statement such as the
108above is insufficient. You must also send by surface mail a copyright release
109signed by a company officer.
110A signed original of the copyright release should be mailed to:</p>
111
112<blockquote>
113Hwaci<br>
1146200 Maple Cove Lane<br>
115Charlotte, NC 28269<br>
116USA
117</blockquote>
118
119<p>
120A template copyright release is available
121in <a href="copyright-release.pdf">PDF</a> or
122<a href="copyright-release.html">HTML</a>.
123You can use this release to make future changes.
124</p>
125}
126footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/datatype3.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/datatype3.tcl
deleted file mode 100644
index da400ae..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/datatype3.tcl
+++ /dev/null
@@ -1,440 +0,0 @@
1set rcsid {$Id: datatype3.tcl,v 1.17 2007/06/20 16:13:23 drh Exp $}
2source common.tcl
3header {Datatypes In SQLite Version 3}
4puts {
5<h2>Datatypes In SQLite Version 3</h2>
6
7<h3>1. Storage Classes</h3>
8
9<P>Version 2 of SQLite stores all column values as ASCII text.
10Version 3 enhances this by providing the ability to store integer and
11real numbers in a more compact format and the capability to store
12BLOB data.</P>
13
14<P>Each value stored in an SQLite database (or manipulated by the
15database engine) has one of the following storage classes:</P>
16<UL>
17 <LI><P><B>NULL</B>. The value is a NULL value.</P>
18 <LI><P><B>INTEGER</B>. The value is a signed integer, stored in 1,
19 2, 3, 4, 6, or 8 bytes depending on the magnitude of the value.</P>
20 <LI><P><B>REAL</B>. The value is a floating point value, stored as
21 an 8-byte IEEE floating point number.</P>
22 <LI><P><B>TEXT</B>. The value is a text string, stored using the
23 database encoding (UTF-8, UTF-16BE or UTF-16-LE).</P>
24 <LI><P><B>BLOB</B>. The value is a blob of data, stored exactly as
25 it was input.</P>
26</UL>
27
28<P>As in SQLite version 2, any column in a version 3 database except an INTEGER
29PRIMARY KEY may be used to store any type of value. The exception to
30this rule is described below under 'Strict Affinity Mode'.</P>
31
32<P>All values supplied to SQLite, whether as literals embedded in SQL
33statements or values bound to pre-compiled SQL statements
34are assigned a storage class before the SQL statement is executed.
35Under circumstances described below, the
36database engine may convert values between numeric storage classes
37(INTEGER and REAL) and TEXT during query execution.
38</P>
39
40<P>Storage classes are initially assigned as follows:</P>
41<UL>
42 <LI><P>Values specified as literals as part of SQL statements are
43 assigned storage class TEXT if they are enclosed by single or double
44 quotes, INTEGER if the literal is specified as an unquoted number
45 with no decimal point or exponent, REAL if the literal is an
46 unquoted number with a decimal point or exponent and NULL if the
47 value is a NULL. Literals with storage class BLOB are specified
48 using the X'ABCD' notation.</P>
49 <LI><P>Values supplied using the sqlite3_bind_* APIs are assigned
50 the storage class that most closely matches the native type bound
51 (i.e. sqlite3_bind_blob() binds a value with storage class BLOB).</P>
52</UL>
53<P>The storage class of a value that is the result of an SQL scalar
54operator depends on the outermost operator of the expression.
55User-defined functions may return values with any storage class. It
56is not generally possible to determine the storage class of the
57result of an expression at compile time.</P>
58
59<a name="affinity">
60<h3>2. Column Affinity</h3>
61
62<p>
63In SQLite version 3, the type of a value is associated with the value
64itself, not with the column or variable in which the value is stored.
65(This is sometimes called
66<a href="http://www.cliki.net/manifest%20type%20system">
67manifest typing</a>.)
68All other SQL databases engines that we are aware of use the more
69restrictive system of static typing where the type is associated with
70the container, not the value.
71</p>
72
73<p>
74In order to maximize compatibility between SQLite and other database
75engines, SQLite support the concept of "type affinity" on columns.
76The type affinity of a column is the recommended type for data stored
77in that column. The key here is that the type is recommended, not
78required. Any column can still store any type of data, in theory.
79It is just that some columns, given the choice, will prefer to use
80one storage class over another. The preferred storage class for
81a column is called its "affinity".
82</p>
83
84<P>Each column in an SQLite 3 database is assigned one of the
85following type affinities:</P>
86<UL>
87 <LI>TEXT</LI>
88 <LI>NUMERIC</LI>
89 <LI>INTEGER</LI>
90 <LI>REAL</li>
91 <LI>NONE</LI>
92</UL>
93
94<P>A column with TEXT affinity stores all data using storage classes
95NULL, TEXT or BLOB. If numerical data is inserted into a column with
96TEXT affinity it is converted to text form before being stored.</P>
97
98<P>A column with NUMERIC affinity may contain values using all five
99storage classes. When text data is inserted into a NUMERIC column, an
100attempt is made to convert it to an integer or real number before it
101is stored. If the conversion is successful, then the value is stored
102using the INTEGER or REAL storage class. If the conversion cannot be
103performed the value is stored using the TEXT storage class. No
104attempt is made to convert NULL or blob values.</P>
105
106<P>A column that uses INTEGER affinity behaves in the same way as a
107column with NUMERIC affinity, except that if a real value with no
108floating point component (or text value that converts to such) is
109inserted it is converted to an integer and stored using the INTEGER
110storage class.</P>
111
112<P>A column with REAL affinity behaves like a column with NUMERIC
113affinity except that it forces integer values into floating point
114representation. (As an optimization, integer values are stored on
115disk as integers in order to take up less space and are only converted
116to floating point as the value is read out of the table.)</P>
117
118<P>A column with affinity NONE does not prefer one storage class over
119another. It makes no attempt to coerce data before
120it is inserted.</P>
121
122<h4>2.1 Determination Of Column Affinity</h4>
123
124<P>The type affinity of a column is determined by the declared type
125of the column, according to the following rules:</P>
126<OL>
127 <LI><P>If the datatype contains the string &quot;INT&quot; then it
128 is assigned INTEGER affinity.</P>
129
130 <LI><P>If the datatype of the column contains any of the strings
131 &quot;CHAR&quot;, &quot;CLOB&quot;, or &quot;TEXT&quot; then that
132 column has TEXT affinity. Notice that the type VARCHAR contains the
133 string &quot;CHAR&quot; and is thus assigned TEXT affinity.</P>
134
135 <LI><P>If the datatype for a column
136 contains the string &quot;BLOB&quot; or if
137 no datatype is specified then the column has affinity NONE.</P>
138
139 <LI><P>If the datatype for a column
140 contains any of the strings &quot;REAL&quot;, &quot;FLOA&quot;,
141 or &quot;DOUB&quot; then the column has REAL affinity</P>
142
143 <LI><P>Otherwise, the affinity is NUMERIC.</P>
144</OL>
145
146<P>If a table is created using a "CREATE TABLE &lt;table&gt; AS
147SELECT..." statement, then all columns have no datatype specified
148and they are given no affinity.</P>
149
150<h4>2.2 Column Affinity Example</h4>
151
152<blockquote>
153<PRE>CREATE TABLE t1(
154 t TEXT,
155 nu NUMERIC,
156 i INTEGER,
157 no BLOB
158);
159
160-- Storage classes for the following row:
161-- TEXT, REAL, INTEGER, TEXT
162INSERT INTO t1 VALUES('500.0', '500.0', '500.0', '500.0');
163
164-- Storage classes for the following row:
165-- TEXT, REAL, INTEGER, REAL
166INSERT INTO t1 VALUES(500.0, 500.0, 500.0, 500.0);
167</PRE>
168</blockquote>
169
170<a name="comparisons">
171<h3>3. Comparison Expressions</h3>
172
173<P>Like SQLite version 2, version 3
174features the binary comparison operators '=',
175'&lt;', '&lt;=', '&gt;=' and '!=', an operation to test for set
176membership, 'IN', and the ternary comparison operator 'BETWEEN'.</P>
177<P>The results of a comparison depend on the storage classes of the
178two values being compared, according to the following rules:</P>
179<UL>
180 <LI><P>A value with storage class NULL is considered less than any
181 other value (including another value with storage class NULL).</P>
182
183 <LI><P>An INTEGER or REAL value is less than any TEXT or BLOB value.
184 When an INTEGER or REAL is compared to another INTEGER or REAL, a
185 numerical comparison is performed.</P>
186
187 <LI><P>A TEXT value is less than a BLOB value. When two TEXT values
188 are compared, the C library function memcmp() is usually used to
189 determine the result. However this can be overridden, as described
190 under 'User-defined collation Sequences' below.</P>
191
192 <LI><P>When two BLOB values are compared, the result is always
193 determined using memcmp().</P>
194</UL>
195
196<P>SQLite may attempt to convert values between the numeric storage
197classes (INTEGER and REAL) and TEXT before performing a comparison.
198For binary comparisons, this is done in the cases enumerated below.
199The term "expression" used in the bullet points below means any
200SQL scalar expression or literal other than a column value. Note that
201if X and Y.Z are a column names, then +X and +Y.Z are considered
202expressions.</P>
203<UL>
204 <LI><P>When a column value is compared to the result of an
205 expression, the affinity of the column is applied to the result of
206 the expression before the comparison takes place.</P>
207
208 <LI><P>When two column values are compared, if one column has
209 INTEGER or REAL or NUMERIC affinity and the other does not,
210 then NUMERIC affinity is applied to any values with storage
211 class TEXT extracted from the non-NUMERIC column.</P>
212
213 <LI><P>When the results of two expressions are compared, no
214 conversions occur. The results are compared as is. If a string
215 is compared to a number, the number will always be less than the
216 string.</P>
217</UL>
218
219<P>
220In SQLite, the expression "a BETWEEN b AND c" is equivalent to "a &gt;= b
221AND a &lt;= c", even if this means that different affinities are applied to
222'a' in each of the comparisons required to evaluate the expression.
223</P>
224
225<P>Expressions of the type "a IN (SELECT b ....)" are handled by the three
226rules enumerated above for binary comparisons (e.g. in a
227similar manner to "a = b"). For example if 'b' is a column value
228and 'a' is an expression, then the affinity of 'b' is applied to 'a'
229before any comparisons take place.</P>
230
231<P>SQLite treats the expression "a IN (x, y, z)" as equivalent to "a = +x OR
232a = +y OR a = +z". The values to the right of the IN operator (the "x", "y",
233and "z" values in this example) are considered to be expressions, even if they
234happen to be column values. If the value of the left of the IN operator is
235a column, then the affinity of that column is used. If the value is an
236expression then no conversions occur.
237</P>
238
239<h4>3.1 Comparison Example</h4>
240
241<blockquote>
242<PRE>
243CREATE TABLE t1(
244 a TEXT,
245 b NUMERIC,
246 c BLOB
247);
248
249-- Storage classes for the following row:
250-- TEXT, REAL, TEXT
251INSERT INTO t1 VALUES('500', '500', '500');
252
253-- 60 and 40 are converted to '60' and '40' and values are compared as TEXT.
254SELECT a &lt; 60, a &lt; 40 FROM t1;
2551|0
256
257-- Comparisons are numeric. No conversions are required.
258SELECT b &lt; 60, b &lt; 600 FROM t1;
2590|1
260
261-- Both 60 and 600 (storage class NUMERIC) are less than '500'
262-- (storage class TEXT).
263SELECT c &lt; 60, c &lt; 600 FROM t1;
2640|0
265</PRE>
266</blockquote>
267<h3>4. Operators</h3>
268
269<P>All mathematical operators (which is to say, all operators other
270than the concatenation operator &quot;||&quot;) apply NUMERIC
271affinity to all operands prior to being carried out. If one or both
272operands cannot be converted to NUMERIC then the result of the
273operation is NULL.</P>
274
275<P>For the concatenation operator, TEXT affinity is applied to both
276operands. If either operand cannot be converted to TEXT (because it
277is NULL or a BLOB) then the result of the concatenation is NULL.</P>
278
279<h3>5. Sorting, Grouping and Compound SELECTs</h3>
280
281<P>When values are sorted by an ORDER by clause, values with storage
282class NULL come first, followed by INTEGER and REAL values
283interspersed in numeric order, followed by TEXT values usually in
284memcmp() order, and finally BLOB values in memcmp() order. No storage
285class conversions occur before the sort.</P>
286
287<P>When grouping values with the GROUP BY clause values with
288different storage classes are considered distinct, except for INTEGER
289and REAL values which are considered equal if they are numerically
290equal. No affinities are applied to any values as the result of a
291GROUP by clause.</P>
292
293<P>The compound SELECT operators UNION,
294INTERSECT and EXCEPT perform implicit comparisons between values.
295Before these comparisons are performed an affinity may be applied to
296each value. The same affinity, if any, is applied to all values that
297may be returned in a single column of the compound SELECT result set.
298The affinity applied is the affinity of the column returned by the
299left most component SELECTs that has a column value (and not some
300other kind of expression) in that position. If for a given compound
301SELECT column none of the component SELECTs return a column value, no
302affinity is applied to the values from that column before they are
303compared.</P>
304
305<h3>6. Other Affinity Modes</h3>
306
307<P>The above sections describe the operation of the database engine
308in 'normal' affinity mode. SQLite version 3 will feature two other affinity
309modes, as follows:</P>
310<UL>
311 <LI><P><B>Strict affinity</B> mode. In this mode if a conversion
312 between storage classes is ever required, the database engine
313 returns an error and the current statement is rolled back.</P>
314
315 <LI><P><B>No affinity</B> mode. In this mode no conversions between
316 storage classes are ever performed. Comparisons between values of
317 different storage classes (except for INTEGER and REAL) are always
318 false.</P>
319</UL>
320
321<a name="collation"></a>
322<h3>7. User-defined Collation Sequences</h3>
323
324<p>
325By default, when SQLite compares two text values, the result of the
326comparison is determined using memcmp(), regardless of the encoding of the
327string. SQLite v3 provides the ability for users to supply arbitrary
328comparison functions, known as user-defined collation sequences, to be used
329instead of memcmp().
330</p>
331<p>
332Aside from the default collation sequence BINARY, implemented using
333memcmp(), SQLite features one extra built-in collation sequences
334intended for testing purposes, the NOCASE collation:
335</p>
336<UL>
337 <LI><b>BINARY</b> - Compares string data using memcmp(), regardless
338 of text encoding.</LI>
339 <LI><b>NOCASE</b> - The same as binary, except the 26 upper case
340 characters used by the English language are
341 folded to their lower case equivalents before
342 the comparison is performed. </UL>
343
344
345<h4>7.1 Assigning Collation Sequences from SQL</h4>
346
347<p>
348Each column of each table has a default collation type. If a collation type
349other than BINARY is required, a COLLATE clause is specified as part of the
350<a href="lang_createtable.html">column definition</a> to define it.
351</p>
352
353<p>
354Whenever two text values are compared by SQLite, a collation sequence is
355used to determine the results of the comparison according to the following
356rules. Sections 3 and 5 of this document describe the circumstances under
357which such a comparison takes place.
358</p>
359
360<p>
361For binary comparison operators (=, <, >, <= and >=) if either operand is a
362column, then the default collation type of the column determines the
363collation sequence to use for the comparison. If both operands are columns,
364then the collation type for the left operand determines the collation
365sequence used. If neither operand is a column, then the BINARY collation
366sequence is used. For the purposes of this paragraph, a column name
367preceded by one or more unary "+" operators is considered a column name.
368</p>
369
370<p>
371The expression "x BETWEEN y and z" is equivalent to "x &gt;= y AND x &lt;=
372z". The expression "x IN (SELECT y ...)" is handled in the same way as the
373expression "x = y" for the purposes of determining the collation sequence
374to use. The collation sequence used for expressions of the form "x IN (y, z
375...)" is the default collation type of x if x is a column, or BINARY
376otherwise.
377</p>
378
379<p>
380An <a href="lang_select.html">ORDER BY</a> clause that is part of a SELECT
381statement may be assigned a collation sequence to be used for the sort
382operation explicitly. In this case the explicit collation sequence is
383always used. Otherwise, if the expression sorted by an ORDER BY clause is
384a column, then the default collation type of the column is used to
385determine sort order. If the expression is not a column, then the BINARY
386collation sequence is used.
387</p>
388
389<h4>7.2 Collation Sequences Example</h4>
390<p>
391The examples below identify the collation sequences that would be used to
392determine the results of text comparisons that may be performed by various
393SQL statements. Note that a text comparison may not be required, and no
394collation sequence used, in the case of numeric, blob or NULL values.
395</p>
396<blockquote>
397<PRE>
398CREATE TABLE t1(
399 a, -- default collation type BINARY
400 b COLLATE BINARY, -- default collation type BINARY
401 c COLLATE REVERSE, -- default collation type REVERSE
402 d COLLATE NOCASE -- default collation type NOCASE
403);
404
405-- Text comparison is performed using the BINARY collation sequence.
406SELECT (a = b) FROM t1;
407
408-- Text comparison is performed using the NOCASE collation sequence.
409SELECT (d = a) FROM t1;
410
411-- Text comparison is performed using the BINARY collation sequence.
412SELECT (a = d) FROM t1;
413
414-- Text comparison is performed using the REVERSE collation sequence.
415SELECT ('abc' = c) FROM t1;
416
417-- Text comparison is performed using the REVERSE collation sequence.
418SELECT (c = 'abc') FROM t1;
419
420-- Grouping is performed using the NOCASE collation sequence (i.e. values
421-- 'abc' and 'ABC' are placed in the same group).
422SELECT count(*) GROUP BY d FROM t1;
423
424-- Grouping is performed using the BINARY collation sequence.
425SELECT count(*) GROUP BY (d || '') FROM t1;
426
427-- Sorting is performed using the REVERSE collation sequence.
428SELECT * FROM t1 ORDER BY c;
429
430-- Sorting is performed using the BINARY collation sequence.
431SELECT * FROM t1 ORDER BY (c || '');
432
433-- Sorting is performed using the NOCASE collation sequence.
434SELECT * FROM t1 ORDER BY c COLLATE NOCASE;
435
436</PRE>
437</blockquote>
438
439}
440footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/datatypes.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/datatypes.tcl
deleted file mode 100644
index 1b45fb6..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/datatypes.tcl
+++ /dev/null
@@ -1,243 +0,0 @@
1#
2# Run this script to generated a datatypes.html output file
3#
4set rcsid {$Id: datatypes.tcl,v 1.8 2004/10/10 17:24:55 drh Exp $}
5source common.tcl
6header {Datatypes In SQLite version 2}
7puts {
8<h2>Datatypes In SQLite Version 2</h2>
9
10<h3>1.0 &nbsp; Typelessness</h3>
11<p>
12SQLite is "typeless". This means that you can store any
13kind of data you want in any column of any table, regardless of the
14declared datatype of that column.
15(See the one exception to this rule in section 2.0 below.)
16This behavior is a feature, not
17a bug. A database is suppose to store and retrieve data and it
18should not matter to the database what format that data is in.
19The strong typing system found in most other SQL engines and
20codified in the SQL language spec is a misfeature -
21it is an example of the implementation showing through into the
22interface. SQLite seeks to overcome this misfeature by allowing
23you to store any kind of data into any kind of column and by
24allowing flexibility in the specification of datatypes.
25</p>
26
27<p>
28A datatype to SQLite is any sequence of zero or more names
29optionally followed by a parenthesized lists of one or two
30signed integers. Notice in particular that a datatype may
31be <em>zero</em> or more names. That means that an empty
32string is a valid datatype as far as SQLite is concerned.
33So you can declare tables where the datatype of each column
34is left unspecified, like this:
35</p>
36
37<blockquote><pre>
38CREATE TABLE ex1(a,b,c);
39</pre></blockquote>
40
41<p>
42Even though SQLite allows the datatype to be omitted, it is
43still a good idea to include it in your CREATE TABLE statements,
44since the data type often serves as a good hint to other
45programmers about what you intend to put in the column. And
46if you ever port your code to another database engine, that
47other engine will probably require a datatype of some kind.
48SQLite accepts all the usual datatypes. For example:
49</p>
50
51<blockquote><pre>
52CREATE TABLE ex2(
53 a VARCHAR(10),
54 b NVARCHAR(15),
55 c TEXT,
56 d INTEGER,
57 e FLOAT,
58 f BOOLEAN,
59 g CLOB,
60 h BLOB,
61 i TIMESTAMP,
62 j NUMERIC(10,5)
63 k VARYING CHARACTER (24),
64 l NATIONAL VARYING CHARACTER(16)
65);
66</pre></blockquote>
67
68<p>
69And so forth. Basically any sequence of names optionally followed by
70one or two signed integers in parentheses will do.
71</p>
72
73<h3>2.0 &nbsp; The INTEGER PRIMARY KEY</h3>
74
75<p>
76One exception to the typelessness of SQLite is a column whose type
77is INTEGER PRIMARY KEY. (And you must use "INTEGER" not "INT".
78A column of type INT PRIMARY KEY is typeless just like any other.)
79INTEGER PRIMARY KEY columns must contain a 32-bit signed integer. Any
80attempt to insert non-integer data will result in an error.
81</p>
82
83<p>
84INTEGER PRIMARY KEY columns can be used to implement the equivalent
85of AUTOINCREMENT. If you try to insert a NULL into an INTEGER PRIMARY
86KEY column, the column will actually be filled with a integer that is
87one greater than the largest key already in the table. Or if the
88largest key is 2147483647, then the column will be filled with a
89random integer. Either way, the INTEGER PRIMARY KEY column will be
90assigned a unique integer. You can retrieve this integer using
91the <b>sqlite_last_insert_rowid()</b> API function or using the
92<b>last_insert_rowid()</b> SQL function in a subsequent SELECT statement.
93</p>
94
95<h3>3.0 &nbsp; Comparison and Sort Order</h3>
96
97<p>
98SQLite is typeless for the purpose of deciding what data is allowed
99to be stored in a column. But some notion of type comes into play
100when sorting and comparing data. For these purposes, a column or
101an expression can be one of two types: <b>numeric</b> and <b>text</b>.
102The sort or comparison may give different results depending on which
103type of data is being sorted or compared.
104</p>
105
106<p>
107If data is of type <b>text</b> then the comparison is determined by
108the standard C data comparison functions <b>memcmp()</b> or
109<b>strcmp()</b>. The comparison looks at bytes from two inputs one
110by one and returns the first non-zero difference.
111Strings are '\000' terminated so shorter
112strings sort before longer strings, as you would expect.
113</p>
114
115<p>
116For numeric data, this situation is more complex. If both inputs
117look like well-formed numbers, then they are converted
118into floating point values using <b>atof()</b> and compared numerically.
119If one input is not a well-formed number but the other is, then the
120number is considered to be less than the non-number. If neither inputs
121is a well-formed number, then <b>strcmp()</b> is used to do the
122comparison.
123</p>
124
125<p>
126Do not be confused by the fact that a column might have a "numeric"
127datatype. This does not mean that the column can contain only numbers.
128It merely means that if the column does contain a number, that number
129will sort in numerical order.
130</p>
131
132<p>
133For both text and numeric values, NULL sorts before any other value.
134A comparison of any value against NULL using operators like "&lt;" or
135"&gt;=" is always false.
136</p>
137
138<h3>4.0 &nbsp; How SQLite Determines Datatypes</h3>
139
140<p>
141For SQLite version 2.6.3 and earlier, all values used the numeric datatype.
142The text datatype appears in version 2.7.0 and later. In the sequel it
143is assumed that you are using version 2.7.0 or later of SQLite.
144</p>
145
146<p>
147For an expression, the datatype of the result is often determined by
148the outermost operator. For example, arithmetic operators ("+", "*", "%")
149always return a numeric results. The string concatenation operator
150("||") returns a text result. And so forth. If you are ever in doubt
151about the datatype of an expression you can use the special <b>typeof()</b>
152SQL function to determine what the datatype is. For example:
153</p>
154
155<blockquote><pre>
156sqlite&gt; SELECT typeof('abc'+123);
157numeric
158sqlite&gt; SELECT typeof('abc'||123);
159text
160</pre></blockquote>
161
162<p>
163For table columns, the datatype is determined by the type declaration
164of the CREATE TABLE statement. The datatype is text if and only if
165the type declaration contains one or more of the following strings:
166</p>
167
168<blockquote>
169BLOB<br>
170CHAR<br>
171CLOB</br>
172TEXT
173</blockquote>
174
175<p>
176The search for these strings in the type declaration is case insensitive,
177of course. If any of the above strings occur anywhere in the type
178declaration, then the datatype of the column is text. Notice that
179the type "VARCHAR" contains "CHAR" as a substring so it is considered
180text.</p>
181
182<p>If none of the strings above occur anywhere in the type declaration,
183then the datatype is numeric. Note in particular that the datatype for columns
184with an empty type declaration is numeric.
185</p>
186
187<h3>5.0 &nbsp; Examples</h3>
188
189<p>
190Consider the following two command sequences:
191</p>
192
193<blockquote><pre>
194CREATE TABLE t1(a INTEGER UNIQUE); CREATE TABLE t2(b TEXT UNIQUE);
195INSERT INTO t1 VALUES('0'); INSERT INTO t2 VALUES(0);
196INSERT INTO t1 VALUES('0.0'); INSERT INTO t2 VALUES(0.0);
197</pre></blockquote>
198
199<p>In the sequence on the left, the second insert will fail. In this case,
200the strings '0' and '0.0' are treated as numbers since they are being
201inserted into a numeric column but 0==0.0 which violates the uniqueness
202constraint. However, the second insert in the right-hand sequence works. In
203this case, the constants 0 and 0.0 are treated a strings which means that
204they are distinct.</p>
205
206<p>SQLite always converts numbers into double-precision (64-bit) floats
207for comparison purposes. This means that a long sequence of digits that
208differ only in insignificant digits will compare equal if they
209are in a numeric column but will compare unequal if they are in a text
210column. We have:</p>
211
212<blockquote><pre>
213INSERT INTO t1 INSERT INTO t2
214 VALUES('12345678901234567890'); VALUES(12345678901234567890);
215INSERT INTO t1 INSERT INTO t2
216 VALUES('12345678901234567891'); VALUES(12345678901234567891);
217</pre></blockquote>
218
219<p>As before, the second insert on the left will fail because the comparison
220will convert both strings into floating-point number first and the only
221difference in the strings is in the 20-th digit which exceeds the resolution
222of a 64-bit float. In contrast, the second insert on the right will work
223because in that case, the numbers being inserted are strings and are
224compared using memcmp().</p>
225
226<p>
227Numeric and text types make a difference for the DISTINCT keyword too:
228</p>
229
230<blockquote><pre>
231CREATE TABLE t3(a INTEGER); CREATE TABLE t4(b TEXT);
232INSERT INTO t3 VALUES('0'); INSERT INTO t4 VALUES(0);
233INSERT INTO t3 VALUES('0.0'); INSERT INTO t4 VALUES(0.0);
234SELECT DISTINCT * FROM t3; SELECT DISTINCT * FROM t4;
235</pre></blockquote>
236
237<p>
238The SELECT statement on the left returns a single row since '0' and '0.0'
239are treated as numbers and are therefore indistinct. But the SELECT
240statement on the right returns two rows since 0 and 0.0 are treated
241a strings which are different.</p>
242}
243footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/different.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/different.tcl
deleted file mode 100644
index 1858e6f..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/different.tcl
+++ /dev/null
@@ -1,224 +0,0 @@
1set rcsid {$Id: different.tcl,v 1.8 2006/12/18 14:12:21 drh Exp $}
2source common.tcl
3header {Distinctive Features Of SQLite}
4puts {
5<p>
6This page highlights some of the characteristics of SQLite that are
7unusual and which make SQLite different from many other SQL
8database engines.
9</p>
10}
11proc feature {tag name text} {
12 puts "<a name=\"$tag\" />"
13 puts "<p><b>$name</b></p>\n"
14 puts "<blockquote>$text</blockquote>\n"
15}
16
17feature zeroconfig {Zero-Configuration} {
18 SQLite does not need to be "installed" before it is used.
19 There is no "setup" procedure. There is no
20 server process that needs to be started, stopped, or configured.
21 There is
22 no need for an administrator to create a new database instance or assign
23 access permissions to users.
24 SQLite uses no configuration files.
25 Nothing needs to be done to tell the system that SQLite is running.
26 No actions are required to recover after a system crash or power failure.
27 There is nothing to troubleshoot.
28 <p>
29 SQLite just works.
30 <p>
31 Other more familiar database engines run great once you get them going.
32 But doing the initial installation and configuration can be
33 intimidatingly complex.
34}
35
36feature serverless {Serverless} {
37 Most SQL database engines are implemented as a separate server
38 process. Programs that want to access the database communicate
39 with the server using some kind of interprocess communcation
40 (typically TCP/IP) to send requests to the server and to receive
41 back results. SQLite does not work this way. With SQLite, the
42 process that wants to access the database reads and writes
43 directly from the database files on disk. There is no intermediary
44 server process.
45 <p>
46 There are advantages and disadvantages to being serverless. The
47 main advantage is that there is no separate server process
48 to install, setup, configure, initialize, manage, and troubleshoot.
49 This is one reason why SQLite is a "zero-configuration" database
50 engine. Programs that use SQLite require no administrative support
51 for setting up the database engine before they are run. Any program
52 that is able to access the disk is able to use an SQLite database.
53 <p>
54 On the other hand, a database engine that uses a server can provide
55 better protection from bugs in the client application - stray pointers
56 in a client cannot corrupt memory on the server. And because a server
57 is a single persistent process, it is able control database access with
58 more precision, allowing for finer grain locking and better concurrancy.
59 <p>
60 Most SQL database engines are client/server based. Of those that are
61 serverless, SQLite is the only one that this author knows of that
62 allows multiple applications to access the same database at the same time.
63}
64
65feature onefile {Single Database File} {
66 An SQLite database is a single ordinary disk file that can be located
67 anywhere in the directory hierarchy. If SQLite can read
68 the disk file then it can read anything in the database. If the disk
69 file and its directory are writable, then SQLite can change anything
70 in the database. Database files can easily be copied onto a USB
71 memory stick or emailed for sharing.
72 <p>
73 Other SQL database engines tend to store data as a large collection of
74 files. Often these files are in a standard location that only the
75 database engine itself can access. This makes the data more secure,
76 but also makes it harder to access. Some SQL database engines provide
77 the option of writing directly to disk and bypassing the filesystem
78 all together. This provides added performance, but at the cost of
79 considerable setup and maintenance complexity.
80}
81
82feature small {Compact} {
83 When optimized for size, the whole SQLite library with everything enabled
84 is less than 225KiB in size (as measured on an ix86 using the "size"
85 utility from the GNU compiler suite.) Unneeded features can be disabled
86 at compile-time to further reduce the size of the library to under
87 170KiB if desired.
88 <p>
89 Most other SQL database engines are much larger than this. IBM boasts
90 that it's recently released CloudScape database engine is "only" a 2MiB
91 jar file - 10 times larger than SQLite even after it is compressed!
92 Firebird boasts that it's client-side library is only 350KiB. That's
93 50% larger than SQLite and does not even contain the database engine.
94 The Berkeley DB library from Sleepycat is 450KiB and it omits SQL
95 support, providing the programmer with only simple key/value pairs.
96}
97
98feature typing {Manifest typing} {
99 Most SQL database engines use static typing. A datatype is associated
100 with each column in a table and only values of that particular datatype
101 are allowed to be stored in that column. SQLite relaxes this restriction
102 by using manifest typing.
103 In manifest typing, the datatype is a property of the value itself, not
104 of the column in which the value is stored.
105 SQLite thus allows the user to store
106 any value of any datatype into any column regardless of the declared type
107 of that column. (There are some exceptions to this rule: An INTEGER
108 PRIMARY KEY column may only store integers. And SQLite attempts to coerce
109 values into the declared datatype of the column when it can.)
110 <p>
111 As far as we can tell, the SQL language specification allows the use
112 of manifest typing. Nevertheless, most other SQL database engines are
113 statically typed and so some people
114 feel that the use of manifest typing is a bug in SQLite. But the authors
115 of SQLite feel very strongly that this is a feature. The use of manifest
116 typing in SQLite is a deliberate design decision which has proven in practice
117 to make SQLite more reliable and easier to use, especially when used in
118 combination with dynamically typed programming languages such as Tcl and
119 Python.
120}
121
122feature flex {Variable-length records} {
123 Most other SQL database engines allocated a fixed amount of disk space
124 for each row in most tables. They play special tricks for handling
125 BLOBs and CLOBs which can be of wildly varying length. But for most
126 tables, if you declare a column to be a VARCHAR(100) then the database
127 engine will allocate
128 100 bytes of disk space regardless of how much information you actually
129 store in that column.
130 <p>
131 SQLite, in contrast, use only the amount of disk space actually
132 needed to store the information in a row. If you store a single
133 character in a VARCHAR(100) column, then only a single byte of disk
134 space is consumed. (Actually two bytes - there is some overhead at
135 the beginning of each column to record its datatype and length.)
136 <p>
137 The use of variable-length records by SQLite has a number of advantages.
138 It results in smaller database files, obviously. It also makes the
139 database run faster, since there is less information to move to and from
140 disk. And, the use of variable-length records makes it possible for
141 SQLite to employ manifest typing instead of static typing.
142}
143
144feature readable {Readable source code} {
145 The source code to SQLite is designed to be readable and accessible to
146 the average programmer. All procedures and data structures and many
147 automatic variables are carefully commented with useful information about
148 what they do. Boilerplate commenting is omitted.
149}
150
151feature vdbe {SQL statements compile into virtual machine code} {
152 Every SQL database engine compiles each SQL statement into some kind of
153 internal data structure which is then used to carry out the work of the
154 statement. But in most SQL engines that internal data structure is a
155 complex web of interlinked structures and objects. In SQLite, the compiled
156 form of statements is a short program in a machine-language like
157 representation. Users of the database can view this
158 <a href="opcode.html">virtual machine language</a>
159 by prepending the <a href="lang_explain.html">EXPLAIN</a> keyword
160 to a query.
161 <p>
162 The use of a virtual machine in SQLite has been a great benefit to
163 library's development. The virtual machine provides a crisp, well-defined
164 junction between the front-end of SQLite (the part that parses SQL
165 statements and generates virtual machine code) and the back-end (the
166 part that executes the virtual machine code and computes a result.)
167 The virtual machine allows the developers to see clearly and in an
168 easily readable form what SQLite is trying to do with each statement
169 it compiles, which is a tremendous help in debugging.
170 Depending on how it is compiled, SQLite also has the capability of
171 tracing the execution of the virtual machine - printing each
172 virtual machine instruction and its result as it executes.
173}
174
175#feature binding {Tight bindings to dynamic languages} {
176# Because it is embedded, SQLite can have a much tighter and more natural
177# binding to high-level dynamic languages such as Tcl, Perl, Python,
178# PHP, and Ruby.
179# For example,
180#}
181
182feature license {Public domain} {
183 The source code for SQLite is in the public domain. No claim of copyright
184 is made on any part of the core source code. (The documentation and test
185 code is a different matter - some sections of documentation and test logic
186 are governed by open-sources licenses.) All contributors to the
187 SQLite core software have signed affidavits specifically disavowing any
188 copyright interest in the code. This means that anybody is able to legally
189 do anything they want with the SQLite source code.
190 <p>
191 There are other SQL database engines with liberal licenses that allow
192 the code to be broadly and freely used. But those other engines are
193 still governed by copyright law. SQLite is different in that copyright
194 law simply does not apply.
195 <p>
196 The source code files for other SQL database engines typically begin
197 with a comment describing your license rights to view and copy that file.
198 The SQLite source code contains no license since it is not governed by
199 copyright. Instead of a license, the SQLite source code offers a blessing:
200 <blockquote>
201 <i>May you do good and not evil<br>
202 May you find forgiveness for yourself and forgive others<br>
203 May you share freely, never taking more than you give.</i>
204 </blockquote>
205}
206
207feature extensions {SQL language extensions} {
208 SQLite provides a number of enhancements to the SQL language
209 not normally found in other database engines.
210 The EXPLAIN keyword and manifest typing have already been mentioned
211 above. SQLite also provides statements such as
212 <a href="lang_replace.html">REPLACE</a> and the
213 <a href="lang_conflict.html">ON CONFLICT</a> clause that allow for
214 added control over the resolution of constraint conflicts.
215 SQLite supports <a href="lang_attach.html">ATTACH</a> and
216 <a href="lang_detach.html">DETACH</a> commands that allow multiple
217 independent databases to be used together in the same query.
218 And SQLite defines APIs that allows the user to add new
219 <a href="capi3ref.html#sqlite3_create_function">SQL functions</a>
220 and <a href="capi3ref.html#sqlite3_create_collation">collating sequences</a>.
221}
222
223
224footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/direct1b.gif b/libraries/sqlite/unix/sqlite-3.5.1/www/direct1b.gif
deleted file mode 100644
index 8999a84..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/direct1b.gif
+++ /dev/null
Binary files differ
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/docs.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/docs.tcl
deleted file mode 100644
index 48efba8..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/docs.tcl
+++ /dev/null
@@ -1,159 +0,0 @@
1# This script generates the "docs.html" page that describes various
2# sources of documentation available for SQLite.
3#
4set rcsid {$Id: docs.tcl,v 1.14 2006/01/30 16:20:30 drh Exp $}
5source common.tcl
6header {SQLite Documentation}
7puts {
8<h2>Available Documentation</h2>
9<table width="100%" cellpadding="5">
10}
11
12proc doc {name url desc} {
13 puts {<tr><td valign="top" align="right">}
14 regsub -all { +} $name {\&nbsp;} name
15 puts "<a href=\"$url\">$name</a></td>"
16 puts {<td width="10"></td>}
17 puts {<td valign="top" align="left">}
18 puts $desc
19 puts {</td></tr>}
20}
21
22doc {Appropriate Uses For SQLite} {whentouse.html} {
23 This document describes situations where SQLite is an approriate
24 database engine to use versus situations where a client/server
25 database engine might be a better choice.
26}
27
28doc {Distinctive Features} {different.html} {
29 This document enumerates and describes some of the features of
30 SQLite that make it different from other SQL database engines.
31}
32
33doc {SQLite In 5 Minutes Or Less} {quickstart.html} {
34 A very quick introduction to programming with SQLite.
35}
36
37doc {SQL Syntax} {lang.html} {
38 This document describes the SQL language that is understood by
39 SQLite.
40}
41doc {Version 3 C/C++ API<br>Reference} {capi3ref.html} {
42 This document describes each API function separately.
43}
44doc {Sharing Cache Mode} {sharedcache.html} {
45 Version 3.3.0 and later supports the ability for two or more
46 database connections to share the same page and schema cache.
47 This feature is useful for certain specialized applications.
48}
49doc {Tcl API} {tclsqlite.html} {
50 A description of the TCL interface bindings for SQLite.
51}
52
53doc {How SQLite Implements Atomic Commit} {
54 A description of the logic within SQLite that implements
55 transactions with atomic commit, even in the face of power
56 failures.
57}
58doc {Moving From SQLite 3.4 to 3.5} {
59 A document describing the differences between SQLite version 3.4.2
60 and 3.5.0.
61}
62
63doc {Pragma commands} {pragma.html} {
64 This document describes SQLite performance tuning options and other
65 special purpose database commands.
66}
67doc {SQLite Version 3} {version3.html} {
68 A summary of of the changes between SQLite version 2.8 and SQLite version 3.0.
69}
70doc {Version 3 C/C++ API} {capi3.html} {
71 A description of the C/C++ interface bindings for SQLite version 3.0.0
72 and following.
73}
74doc {Version 3 DataTypes } {datatype3.html} {
75 SQLite version 3 introduces the concept of manifest typing, where the
76 type of a value is associated with the value itself, not the column that
77 it is stored in.
78 This page describes data typing for SQLite version 3 in further detail.
79}
80
81doc {Locking And Concurrency<br>In SQLite Version 3} {lockingv3.html} {
82 A description of how the new locking code in version 3 increases
83 concurrancy and decreases the problem of writer starvation.
84}
85
86doc {Overview Of The Optimizer} {optoverview.html} {
87 A quick overview of the various query optimizations that are
88 attempted by the SQLite code generator.
89}
90
91
92doc {Null Handling} {nulls.html} {
93 Different SQL database engines handle NULLs in different ways. The
94 SQL standards are ambiguous. This document describes how SQLite handles
95 NULLs in comparison with other SQL database engines.
96}
97
98doc {Copyright} {copyright.html} {
99 SQLite is in the public domain. This document describes what that means
100 and the implications for contributors.
101}
102
103doc {Unsupported SQL} {omitted.html} {
104 This page describes features of SQL that SQLite does not support.
105}
106
107doc {Version 2 C/C++ API} {c_interface.html} {
108 A description of the C/C++ interface bindings for SQLite through version
109 2.8
110}
111
112
113doc {Version 2 DataTypes } {datatypes.html} {
114 A description of how SQLite version 2 handles SQL datatypes.
115 Short summary: Everything is a string.
116}
117
118doc {Release History} {changes.html} {
119 A chronology of SQLite releases going back to version 1.0.0
120}
121
122
123doc {Speed Comparison} {speed.html} {
124 The speed of version 2.7.6 of SQLite is compared against PostgreSQL and
125 MySQL.
126}
127
128doc {Architecture} {arch.html} {
129 An architectural overview of the SQLite library, useful for those who want
130 to hack the code.
131}
132
133doc {VDBE Tutorial} {vdbe.html} {
134 The VDBE is the subsystem within SQLite that does the actual work of
135 executing SQL statements. This page describes the principles of operation
136 for the VDBE in SQLite version 2.7. This is essential reading for anyone
137 who want to modify the SQLite sources.
138}
139
140doc {VDBE Opcodes} {opcode.html} {
141 This document is an automatically generated description of the various
142 opcodes that the VDBE understands. Programmers can use this document as
143 a reference to better understand the output of EXPLAIN listings from
144 SQLite.
145}
146
147doc {Compilation Options} {compile.html} {
148 This document describes the compile time options that may be set to
149 modify the default behaviour of the library or omit optional features
150 in order to reduce binary size.
151}
152
153doc {Backwards Compatibility} {formatchng.html} {
154 This document details all of the incompatible changes to the SQLite
155 file format that have occurred since version 1.0.0.
156}
157
158puts {</table>}
159footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/download.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/download.tcl
deleted file mode 100644
index b47cd5b..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/download.tcl
+++ /dev/null
@@ -1,236 +0,0 @@
1#
2# Run this TCL script to generate HTML for the download.html file.
3#
4set rcsid {$Id: download.tcl,v 1.27 2007/05/08 18:30:36 drh Exp $}
5source common.tcl
6header {SQLite Download Page}
7
8puts {
9<h2>SQLite Download Page</h1>
10<table width="100%" cellpadding="5">
11}
12
13proc Product {pattern desc} {
14 regsub {V[23]} $pattern {*} p3
15 regsub V2 $pattern {(2[0-9a-z._]+)} pattern
16 regsub V3 $pattern {(3[0-9a-z._]+)} pattern
17 set p2 [string map {* .*} $pattern]
18 set flist [glob -nocomplain $p3]
19 foreach file [lsort -dict $flist] {
20 if {![regexp ^$p2\$ $file all version]} continue
21 regsub -all _ $version . version
22 set size [file size $file]
23 set units bytes
24 if {$size>1024*1024} {
25 set size [format %.2f [expr {$size/(1024.0*1024.0)}]]
26 set units MiB
27 } elseif {$size>1024} {
28 set size [format %.2f [expr {$size/(1024.0)}]]
29 set units KiB
30 }
31 puts "<tr><td width=\"10\"></td>"
32 puts "<td valign=\"top\" align=\"right\">"
33 puts "<a href=\"$file\">$file</a><br>($size $units)</td>"
34 puts "<td width=\"5\"></td>"
35 regsub -all VERSION $desc $version d2
36 puts "<td valign=\"top\">[string trim $d2]</td></tr>"
37 }
38}
39cd doc
40
41proc Heading {title} {
42 puts "<tr><td colspan=4><big><b>$title</b></big></td></tr>"
43}
44
45Heading {Precompiled Binaries for Linux}
46
47Product sqlite3-V3.bin.gz {
48 A command-line program for accessing and modifying
49 SQLite version 3.* databases.
50 See <a href="sqlite.html">the documentation</a> for additional information.
51}
52
53Product sqlite-V3.bin.gz {
54 A command-line program for accessing and modifying
55 SQLite databases.
56 See <a href="sqlite.html">the documentation</a> for additional information.
57}
58
59Product tclsqlite-V3.so.gz {
60 Bindings for <a href="http://www.tcl.tk/">Tcl/Tk</a>.
61 You can import this shared library into either
62 tclsh or wish to get SQLite database access from Tcl/Tk.
63 See <a href="tclsqlite.html">the documentation</a> for details.
64}
65
66Product sqlite-V3.so.gz {
67 A precompiled shared-library for Linux without the TCL bindings.
68}
69
70Product fts1-V3.so.gz {
71 A precompiled
72 <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsOne">FTS1 Module</a>
73 for Linux.
74}
75
76Product fts2-V3.so.gz {
77 A precompiled
78 <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsTwo">FTS2 Module</a>
79 for Linux.
80}
81
82Product sqlite-devel-V3.i386.rpm {
83 RPM containing documentation, header files, and static library for
84 SQLite version VERSION.
85}
86Product sqlite-V3-1.i386.rpm {
87 RPM containing shared libraries and the <b>sqlite</b> command-line
88 program for SQLite version VERSION.
89}
90
91Product sqlite*_analyzer-V3.bin.gz {
92 An analysis program for database files compatible with SQLite
93 version VERSION and later.
94}
95
96Heading {Precompiled Binaries For Windows}
97
98Product sqlite-V3.zip {
99 A command-line program for accessing and modifing SQLite databases.
100 See <a href="sqlite.html">the documentation</a> for additional information.
101}
102Product tclsqlite-V3.zip {
103 Bindings for <a href="http://www.tcl.tk/">Tcl/Tk</a>.
104 You can import this shared library into either
105 tclsh or wish to get SQLite database access from Tcl/Tk.
106 See <a href="tclsqlite.html">the documentation</a> for details.
107}
108Product sqlitedll-V3.zip {
109 This is a DLL of the SQLite library without the TCL bindings.
110 The only external dependency is MSVCRT.DLL.
111}
112
113Product fts1dll-V3.zip {
114 A precompiled
115 <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsOne">FTS1 Module</a>
116 for win32.
117}
118
119Product fts2dll-V3.zip {
120 A precompiled
121 <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsTwo">FTS2 Module</a>
122 for win32.
123}
124
125Product sqlite*_analyzer-V3.zip {
126 An analysis program for database files compatible with SQLite version
127 VERSION and later.
128}
129
130
131Heading {Source Code}
132
133Product {sqlite-V3.tar.gz} {
134 A tarball of the complete source tree for SQLite version VERSION
135 including all of the documentation.
136}
137
138Product {sqlite-source-V3.zip} {
139 This ZIP archive contains preprocessed C code for the SQLite library as
140 individual source files.
141 Unlike the tarballs below, all of the preprocessing and automatic
142 code generation has already been done on these C code files, so they
143 can be converted to object code directly with any ordinary C compiler.
144}
145
146Product {sqlite-amalgamation-V3.zip} {
147 This ZIP archive contains all preprocessed C code combined into a
148 single source file (the
149 <a href="http://www.sqlite.org/cvstrac/wiki?p=TheAmalgamation">
150 amalgamation</a>).
151}
152
153Product {sqlite-V3-tea.tar.gz} {
154 A tarball of proprocessed source code together with a
155 <a href="http://www.tcl.tk/doc/tea/">Tcl Extension Architecture (TEA)</a>
156 compatible configure script and makefile.
157}
158
159Product {sqlite-V3.src.rpm} {
160 An RPM containing complete source code for SQLite version VERSION
161}
162
163Heading {Cross-Platform Binaries}
164
165Product {sqlite-V3.kit} {
166 A <a href="http://www.equi4.com/starkit.html">starkit</a> containing
167 precompiled SQLite binaries and Tcl bindings for Linux-x86, Windows,
168 and Mac OS-X ppc and x86.
169}
170
171Heading {Historical Binaries And Source Code}
172
173Product sqlite-V2.bin.gz {
174 A command-line program for accessing and modifying
175 SQLite version 2.* databases on Linux-x86.
176}
177Product sqlite-V2.zip {
178 A command-line program for accessing and modifying
179 SQLite version 2.* databases on win32.
180}
181
182Product sqlite*_analyzer-V2.bin.gz {
183 An analysis program for version 2.* database files on Linux-x86
184}
185Product sqlite*_analyzer-V2.zip {
186 An analysis program for version 2.* database files on win32.
187}
188Product {sqlite-source-V2.zip} {
189 This ZIP archive contains C source code for the SQLite library
190 version VERSION.
191}
192
193
194
195
196puts {
197</table>
198
199<a name="cvs">
200<h3>Direct Access To The Sources Via Anonymous CVS</h3>
201
202<p>
203All SQLite source code is maintained in a
204<a href="http://www.cvshome.org/">CVS</a> repository that is
205available for read-only access by anyone. You can
206interactively view the
207repository contents and download individual files
208by visiting
209<a href="http://www.sqlite.org/cvstrac/dir?d=sqlite">
210http://www.sqlite.org/cvstrac/dir?d=sqlite</a>.
211To access the repository directly, use the following
212commands:
213</p>
214
215<blockquote><pre>
216cvs -d :pserver:anonymous@www.sqlite.org:/sqlite login
217cvs -d :pserver:anonymous@www.sqlite.org:/sqlite checkout sqlite
218</pre></blockquote>
219
220<p>
221When the first command prompts you for a password, enter "anonymous".
222</p>
223
224<p>
225To access the SQLite version 2.8 sources, begin by getting the 3.0
226tree as described above. Then update to the "version_2" branch
227as follows:
228</p>
229
230<blockquote><pre>
231cvs update -r version_2
232</pre></blockquote>
233
234}
235
236footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/dynload.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/dynload.tcl
deleted file mode 100644
index 3e12b7f..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/dynload.tcl
+++ /dev/null
@@ -1,70 +0,0 @@
1#
2# Run this Tcl script to generate the dynload.html file.
3#
4set rcsid {$Id: dynload.tcl,v 1.1 2001/02/11 16:58:22 drh Exp $}
5
6puts {<html>
7<head>
8 <title>How to build a dynamically loaded Tcl extension for SQLite</title>
9</head>
10<body bgcolor=white>
11<h1 align=center>
12How To Build A Dynamically Loaded Tcl Extension
13</h1>}
14puts {<p>
15<i>This note was contributed by
16<a href="bsaunder@tampabay.rr.com.nospam">Bill Saunders</a>. Thanks, Bill!</i>
17
18<p>
19To compile the SQLite Tcl extension into a dynamically loaded module
20I did the following:
21</p>
22
23<ol>
24<li><p>Do a standard compile
25(I had a dir called bld at the same level as sqlite ie
26 /root/bld
27 /root/sqlite
28I followed the directions and did a standard build in the bld
29directory)</p></li>
30
31<li><p>
32Now do the following in the bld directory
33<blockquote><pre>
34gcc -shared -I. -lgdbm ../sqlite/src/tclsqlite.c libsqlite.a -o sqlite.so
35</pre></blockquote></p></li>
36
37<li><p>
38This should produce the file sqlite.so in the bld directory</p></li>
39
40<li><p>
41Create a pkgIndex.tcl file that contains this line
42
43<blockquote><pre>
44package ifneeded sqlite 1.0 [list load [file join $dir sqlite.so]]
45</pre></blockquote></p></li>
46
47<li><p>
48To use this put sqlite.so and pkgIndex.tcl in the same directory</p></li>
49
50<li><p>
51From that directory start wish</p></li>
52
53<li><p>
54Execute the following tcl command (tells tcl where to fine loadable
55modules)
56<blockquote><pre>
57lappend auto_path [exec pwd]
58</pre></blockquote></p></li>
59
60<li><p>
61Load the package
62<blockquote><pre>
63package require sqlite
64</pre></blockquote></p></li>
65
66<li><p>
67Have fun....</p></li>
68</ul>
69
70</body></html>}
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/faq.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/faq.tcl
deleted file mode 100644
index dd2c7cc..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/faq.tcl
+++ /dev/null
@@ -1,463 +0,0 @@
1#
2# Run this script to generated a faq.html output file
3#
4set rcsid {$Id: faq.tcl,v 1.40 2007/09/04 01:58:27 drh Exp $}
5source common.tcl
6header {SQLite Frequently Asked Questions</title>}
7
8set cnt 1
9proc faq {question answer} {
10 set ::faq($::cnt) [list [string trim $question] [string trim $answer]]
11 incr ::cnt
12}
13
14#############
15# Enter questions and answers here.
16
17faq {
18 How do I create an AUTOINCREMENT field.
19} {
20 <p>Short answer: A column declared INTEGER PRIMARY KEY will
21 autoincrement.</p>
22
23 <p>Here is the long answer:
24 If you declare a column of a table to be INTEGER PRIMARY KEY, then
25 whenever you insert a NULL
26 into that column of the table, the NULL is automatically converted
27 into an integer which is one greater than the largest value of that
28 column over all other rows in the table, or 1 if the table is empty.
29 (If the largest possible integer key, 9223372036854775807, then an
30 unused key value is chosen at random.)
31 For example, suppose you have a table like this:
32<blockquote><pre>
33CREATE TABLE t1(
34 a INTEGER PRIMARY KEY,
35 b INTEGER
36);
37</pre></blockquote>
38 <p>With this table, the statement</p>
39<blockquote><pre>
40INSERT INTO t1 VALUES(NULL,123);
41</pre></blockquote>
42 <p>is logically equivalent to saying:</p>
43<blockquote><pre>
44INSERT INTO t1 VALUES((SELECT max(a) FROM t1)+1,123);
45</pre></blockquote>
46
47 <p>There is a new API function named
48 <a href="capi3ref.html#sqlite3_last_insert_rowid">
49 sqlite3_last_insert_rowid()</a> which will return the integer key
50 for the most recent insert operation.</p>
51
52 <p>Note that the integer key is one greater than the largest
53 key that was in the table just prior to the insert. The new key
54 will be unique over all keys currently in the table, but it might
55 overlap with keys that have been previously deleted from the
56 table. To create keys that are unique over the lifetime of the
57 table, add the AUTOINCREMENT keyword to the INTEGER PRIMARY KEY
58 declaration. Then the key chosen will be one more than than the
59 largest key that has ever existed in that table. If the largest
60 possible key has previously existed in that table, then the INSERT
61 will fail with an SQLITE_FULL error code.</p>
62}
63
64faq {
65 What datatypes does SQLite support?
66} {
67 <p>See <a href="datatype3.html">http://www.sqlite.org/datatype3.html</a>.</p>
68}
69
70faq {
71 SQLite lets me insert a string into a database column of type integer!
72} {
73 <p>This is a feature, not a bug. SQLite does not enforce data type
74 constraints. Any data can be
75 inserted into any column. You can put arbitrary length strings into
76 integer columns, floating point numbers in boolean columns, or dates
77 in character columns. The datatype you assign to a column in the
78 CREATE TABLE command does not restrict what data can be put into
79 that column. Every column is able to hold
80 an arbitrary length string. (There is one exception: Columns of
81 type INTEGER PRIMARY KEY may only hold a 64-bit signed integer.
82 An error will result
83 if you try to put anything other than an integer into an
84 INTEGER PRIMARY KEY column.)</p>
85
86 <p>But SQLite does use the declared type of a column as a hint
87 that you prefer values in that format. So, for example, if a
88 column is of type INTEGER and you try to insert a string into
89 that column, SQLite will attempt to convert the string into an
90 integer. If it can, it inserts the integer instead. If not,
91 it inserts the string. This feature is sometimes
92 call <a href="datatype3.html#affinity">type or column affinity</a>.
93 </p>
94}
95
96faq {
97 Why doesn't SQLite allow me to use '0' and '0.0' as the primary
98 key on two different rows of the same table?
99} {
100 <p>Your primary key must have a numeric type. Change the datatype of
101 your primary key to TEXT and it should work.</p>
102
103 <p>Every row must have a unique primary key. For a column with a
104 numeric type, SQLite thinks that <b>'0'</b> and <b>'0.0'</b> are the
105 same value because they compare equal to one another numerically.
106 (See the previous question.) Hence the values are not unique.</p>
107}
108
109
110faq {
111 Can multiple applications or multiple instances of the same
112 application access a single database file at the same time?
113} {
114 <p>Multiple processes can have the same database open at the same
115 time. Multiple processes can be doing a SELECT
116 at the same time. But only one process can be making changes to
117 the database at any moment in time, however.</p>
118
119 <p>SQLite uses reader/writer locks to control access to the database.
120 (Under Win95/98/ME which lacks support for reader/writer locks, a
121 probabilistic simulation is used instead.)
122 But use caution: this locking mechanism might
123 not work correctly if the database file is kept on an NFS filesystem.
124 This is because fcntl() file locking is broken on many NFS implementations.
125 You should avoid putting SQLite database files on NFS if multiple
126 processes might try to access the file at the same time. On Windows,
127 Microsoft's documentation says that locking may not work under FAT
128 filesystems if you are not running the Share.exe daemon. People who
129 have a lot of experience with Windows tell me that file locking of
130 network files is very buggy and is not dependable. If what they
131 say is true, sharing an SQLite database between two or more Windows
132 machines might cause unexpected problems.</p>
133
134 <p>We are aware of no other <i>embedded</i> SQL database engine that
135 supports as much concurrancy as SQLite. SQLite allows multiple processes
136 to have the database file open at once, and for multiple processes to
137 read the database at once. When any process wants to write, it must
138 lock the entire database file for the duration of its update. But that
139 normally only takes a few milliseconds. Other processes just wait on
140 the writer to finish then continue about their business. Other embedded
141 SQL database engines typically only allow a single process to connect to
142 the database at once.</p>
143
144 <p>However, client/server database engines (such as PostgreSQL, MySQL,
145 or Oracle) usually support a higher level of concurrency and allow
146 multiple processes to be writing to the same database at the same time.
147 This is possible in a client/server database because there is always a
148 single well-controlled server process available to coordinate access.
149 If your application has a need for a lot of concurrency, then you should
150 consider using a client/server database. But experience suggests that
151 most applications need much less concurrency than their designers imagine.
152 </p>
153
154 <p>When SQLite tries to access a file that is locked by another
155 process, the default behavior is to return SQLITE_BUSY. You can
156 adjust this behavior from C code using the
157 <a href="capi3ref.html#sqlite3_busy_handler">sqlite3_busy_handler()</a> or
158 <a href="capi3ref.html#sqlite3_busy_timeout">sqlite3_busy_timeout()</a>
159 API functions.</p>
160}
161
162faq {
163 Is SQLite threadsafe?
164} {
165 <p>Yes. Sometimes. In order to be thread-safe, SQLite must be compiled
166 with the SQLITE_THREADSAFE preprocessor macro set to 1. Both the windows
167 and linux precompiled binaries in the distribution are compiled this way.
168 If you are unsure if the SQLite library you are linking against is compiled
169 to be threadsafe you can call the
170 <a href="capi3ref.html#sqlite3_threadsafe">sqlite3_threadsafe()</a>
171 interface to find out.
172 </p>
173
174 <p>Prior to version 3.3.1,
175 an <b>sqlite3</b> structure could only be used in the same thread
176 that called <a href="capi3ref.html#sqlite3_open">sqlite3_open</a>
177 to create it.
178 You could not open a
179 database in one thread then pass the handle off to another thread for
180 it to use. This was due to limitations (bugs?) in many common threading
181 implementations such as on RedHat9. Specifically, an fcntl() lock
182 created by one thread cannot be removed or modified by a different
183 thread on the troublesome systems. And since SQLite uses fcntl()
184 locks heavily for concurrency control, serious problems arose if you
185 start moving database connections across threads.</p>
186
187 <p>The restriction on moving database connections across threads
188 was relaxed somewhat in version 3.3.1. With that and subsequent
189 versions, it is safe to move a connection handle across threads
190 as long as the connection is not holding any fcntl() locks. You
191 can safely assume that no locks are being held if no
192 transaction is pending and all statements have been finalized.</p>
193
194 <p>Under UNIX, you should not carry an open SQLite database across
195 a fork() system call into the child process. Problems will result
196 if you do.</p>
197}
198
199faq {
200 How do I list all tables/indices contained in an SQLite database
201} {
202 <p>If you are running the <b>sqlite3</b> command-line access program
203 you can type "<b>.tables</b>" to get a list of all tables. Or you
204 can type "<b>.schema</b>" to see the complete database schema including
205 all tables and indices. Either of these commands can be followed by
206 a LIKE pattern that will restrict the tables that are displayed.</p>
207
208 <p>From within a C/C++ program (or a script using Tcl/Ruby/Perl/Python
209 bindings) you can get access to table and index names by doing a SELECT
210 on a special table named "<b>SQLITE_MASTER</b>". Every SQLite database
211 has an SQLITE_MASTER table that defines the schema for the database.
212 The SQLITE_MASTER table looks like this:</p>
213<blockquote><pre>
214CREATE TABLE sqlite_master (
215 type TEXT,
216 name TEXT,
217 tbl_name TEXT,
218 rootpage INTEGER,
219 sql TEXT
220);
221</pre></blockquote>
222 <p>For tables, the <b>type</b> field will always be <b>'table'</b> and the
223 <b>name</b> field will be the name of the table. So to get a list of
224 all tables in the database, use the following SELECT command:</p>
225<blockquote><pre>
226SELECT name FROM sqlite_master
227WHERE type='table'
228ORDER BY name;
229</pre></blockquote>
230 <p>For indices, <b>type</b> is equal to <b>'index'</b>, <b>name</b> is the
231 name of the index and <b>tbl_name</b> is the name of the table to which
232 the index belongs. For both tables and indices, the <b>sql</b> field is
233 the text of the original CREATE TABLE or CREATE INDEX statement that
234 created the table or index. For automatically created indices (used
235 to implement the PRIMARY KEY or UNIQUE constraints) the <b>sql</b> field
236 is NULL.</p>
237
238 <p>The SQLITE_MASTER table is read-only. You cannot change this table
239 using UPDATE, INSERT, or DELETE. The table is automatically updated by
240 CREATE TABLE, CREATE INDEX, DROP TABLE, and DROP INDEX commands.</p>
241
242 <p>Temporary tables do not appear in the SQLITE_MASTER table. Temporary
243 tables and their indices and triggers occur in another special table
244 named SQLITE_TEMP_MASTER. SQLITE_TEMP_MASTER works just like SQLITE_MASTER
245 except that it is only visible to the application that created the
246 temporary tables. To get a list of all tables, both permanent and
247 temporary, one can use a command similar to the following:
248<blockquote><pre>
249SELECT name FROM
250 (SELECT * FROM sqlite_master UNION ALL
251 SELECT * FROM sqlite_temp_master)
252WHERE type='table'
253ORDER BY name
254</pre></blockquote>
255}
256
257faq {
258 Are there any known size limits to SQLite databases?
259} {
260 <p>See <a href="limits.html">limits.html</a> for a full discussion of
261 the limits of SQLite.</p>
262}
263
264faq {
265 What is the maximum size of a VARCHAR in SQLite?
266} {
267 <p>SQLite does not enforce the length of a VARCHAR. You can declare
268 a VARCHAR(10) and SQLite will be happy to let you put 500 characters
269 in it. And it will keep all 500 characters intact - it never truncates.
270 </p>
271}
272
273faq {
274 Does SQLite support a BLOB type?
275} {
276 <p>SQLite versions 3.0 and later allow you to store BLOB data in any
277 column, even columns that are declared to hold some other type.</p>
278}
279
280faq {
281 How do I add or delete columns from an existing table in SQLite.
282} {
283 <p>SQLite has limited
284 <a href="lang_altertable.html">ALTER TABLE</a> support that you can
285 use to add a column to the end of a table or to change the name of
286 a table.
287 If you what make more complex changes the structure of a table,
288 you will have to recreate the
289 table. You can save existing data to a temporary table, drop the
290 old table, create the new table, then copy the data back in from
291 the temporary table.</p>
292
293 <p>For example, suppose you have a table named "t1" with columns
294 names "a", "b", and "c" and that you want to delete column "c" from
295 this table. The following steps illustrate how this could be done:
296 </p>
297
298 <blockquote><pre>
299BEGIN TRANSACTION;
300CREATE TEMPORARY TABLE t1_backup(a,b);
301INSERT INTO t1_backup SELECT a,b FROM t1;
302DROP TABLE t1;
303CREATE TABLE t1(a,b);
304INSERT INTO t1 SELECT a,b FROM t1_backup;
305DROP TABLE t1_backup;
306COMMIT;
307</pre></blockquote>
308}
309
310faq {
311 I deleted a lot of data but the database file did not get any
312 smaller. Is this a bug?
313} {
314 <p>No. When you delete information from an SQLite database, the
315 unused disk space is added to an internal "free-list" and is reused
316 the next time you insert data. The disk space is not lost. But
317 neither is it returned to the operating system.</p>
318
319 <p>If you delete a lot of data and want to shrink the database file,
320 run the <a href="lang_vacuum.html">VACUUM</a> command.
321 VACUUM will reconstruct
322 the database from scratch. This will leave the database with an empty
323 free-list and a file that is minimal in size. Note, however, that the
324 VACUUM can take some time to run (around a half second per megabyte
325 on the Linux box where SQLite is developed) and it can use up to twice
326 as much temporary disk space as the original file while it is running.
327 </p>
328
329 <p>As of SQLite version 3.1, an alternative to using the VACUUM command
330 is auto-vacuum mode, enabled using the
331 <a href="pragma.html#pragma_auto_vacuum">auto_vacuum pragma</a>.</p>
332}
333
334faq {
335 Can I use SQLite in my commercial product without paying royalties?
336} {
337 <p>Yes. SQLite is in the
338 <a href="copyright.html">public domain</a>. No claim of ownership is made
339 to any part of the code. You can do anything you want with it.</p>
340}
341
342faq {
343 How do I use a string literal that contains an embedded single-quote (')
344 character?
345} {
346 <p>The SQL standard specifies that single-quotes in strings are escaped
347 by putting two single quotes in a row. SQL works like the Pascal programming
348 language in the regard. SQLite follows this standard. Example:
349 </p>
350
351 <blockquote><pre>
352 INSERT INTO xyz VALUES('5 O''clock');
353 </pre></blockquote>
354}
355
356faq {What is an SQLITE_SCHEMA error, and why am I getting one?} {
357 <p>An SQLITE_SCHEMA error is returned when a
358 prepared SQL statement is no longer valid and cannot be executed.
359 When this occurs, the statement must be recompiled from SQL using
360 the
361 <a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a> API.
362 In SQLite version 3, an SQLITE_SCHEMA error can
363 only occur when using the
364 <a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a>/<a
365 href="capi3ref.html#sqlite3_step">sqlite3_step()</a>/<a
366 href="capi3ref.html#sqlite3_finalize">sqlite3_finalize()</a>
367 API to execute SQL, not when using the
368 <a href="capi3ref.html#sqlite3_exec">sqlite3_exec()</a>. This was not
369 the case in version 2.</p>
370
371 <p>The most common reason for a prepared statement to become invalid
372 is that the schema of the database was modified after the SQL was
373 prepared (possibly by another process). The other reasons this can
374 happen are:</p>
375 <ul>
376 <li>A database was <a href="lang_detach.html">DETACH</a>ed.
377 <li>The database was <a href="lang_vacuum.html">VACUUM</a>ed
378 <li>A user-function definition was deleted or changed.
379 <li>A collation sequence definition was deleted or changed.
380 <li>The authorization function was changed.
381 </ul>
382
383 <p>In all cases, the solution is to recompile the statement from SQL
384 and attempt to execute it again. Because a prepared statement can be
385 invalidated by another process changing the database schema, all code
386 that uses the
387 <a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a>/<a
388 href="capi3ref.html#sqlite3_step">sqlite3_step()</a>/<a
389 href="capi3ref.html#sqlite3_finalize">sqlite3_finalize()</a>
390 API should be prepared to handle SQLITE_SCHEMA errors. An example
391 of one approach to this follows:</p>
392
393 <blockquote><pre>
394
395 int rc;
396 sqlite3_stmt *pStmt;
397 char zSql[] = "SELECT .....";
398
399 do {
400 /* Compile the statement from SQL. Assume success. */
401 sqlite3_prepare(pDb, zSql, -1, &pStmt, 0);
402
403 while( SQLITE_ROW==sqlite3_step(pStmt) ){
404 /* Do something with the row of available data */
405 }
406
407 /* Finalize the statement. If an SQLITE_SCHEMA error has
408 ** occured, then the above call to sqlite3_step() will have
409 ** returned SQLITE_ERROR. sqlite3_finalize() will return
410 ** SQLITE_SCHEMA. In this case the loop will execute again.
411 */
412 rc = sqlite3_finalize(pStmt);
413 } while( rc==SQLITE_SCHEMA );
414
415 </pre></blockquote>
416}
417
418faq {Why does ROUND(9.95,1) return 9.9 instead of 10.0?
419 Shouldn't 9.95 round up?} {
420 <p>SQLite uses binary arithmetic and in binary, there is no
421 way to write 9.95 in a finite number of bits. The closest to
422 you can get to 9.95 in a 64-bit IEEE float (which is what
423 SQLite uses) is 9.949999999999999289457264239899814128875732421875.
424 So when you type "9.95", SQLite really understands the number to be
425 the much longer value shown above. And that value rounds down.</p>
426
427 <p>This kind of problem comes up all the time when dealing with
428 floating point binary numbers. The general rule to remember is
429 that most fractional numbers that have a finite representation in decimal
430 (a.k.a "base-10")
431 do not have a finite representation in binary (a.k.a "base-2").
432 And so they are
433 approximated using the closest binary number available. That
434 approximation is usually very close, but it will be slightly off
435 and in some cases can cause your results to be a little different
436 from what you might expect.</p>
437}
438
439# End of questions and answers.
440#############
441
442puts {<h2>Frequently Asked Questions</h2>}
443
444# puts {<DL COMPACT>}
445# for {set i 1} {$i<$cnt} {incr i} {
446# puts " <DT><A HREF=\"#q$i\">($i)</A></DT>"
447# puts " <DD>[lindex $faq($i) 0]</DD>"
448# }
449# puts {</DL>}
450puts {<OL>}
451for {set i 1} {$i<$cnt} {incr i} {
452 puts "<li><a href=\"#q$i\">[lindex $faq($i) 0]</a></li>"
453}
454puts {</OL>}
455
456for {set i 1} {$i<$cnt} {incr i} {
457 puts "<A NAME=\"q$i\"><HR />"
458 puts "<P><B>($i) [lindex $faq($i) 0]</B></P>\n"
459 puts "<BLOCKQUOTE>[lindex $faq($i) 1]</BLOCKQUOTE></LI>\n"
460}
461
462puts {</OL>}
463footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/fileformat.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/fileformat.tcl
deleted file mode 100644
index d143f08..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/fileformat.tcl
+++ /dev/null
@@ -1,785 +0,0 @@
1#
2# Run this script to generated a fileformat.html output file
3#
4set rcsid {$Id: fileformat.tcl,v 1.13 2004/10/10 17:24:55 drh Exp $}
5source common.tcl
6header {SQLite Database File Format (Version 2)}
7puts {
8<h2>SQLite 2.X Database File Format</h2>
9
10<p>
11This document describes the disk file format for SQLite versions 2.1
12through 2.8. SQLite version 3.0 and following uses a very different
13format which is described separately.
14</p>
15
16<h3>1.0 &nbsp; Layers</h3>
17
18<p>
19SQLite is implemented in layers.
20(See the <a href="arch.html">architecture description</a>.)
21The format of database files is determined by three different
22layers in the architecture.
23</p>
24
25<ul>
26<li>The <b>schema</b> layer implemented by the VDBE.</li>
27<li>The <b>b-tree</b> layer implemented by btree.c</li>
28<li>The <b>pager</b> layer implemented by pager.c</li>
29</ul>
30
31<p>
32We will describe each layer beginning with the bottom (pager)
33layer and working upwards.
34</p>
35
36<h3>2.0 &nbsp; The Pager Layer</h3>
37
38<p>
39An SQLite database consists of
40"pages" of data. Each page is 1024 bytes in size.
41Pages are numbered beginning with 1.
42A page number of 0 is used to indicate "no such page" in the
43B-Tree and Schema layers.
44</p>
45
46<p>
47The pager layer is responsible for implementing transactions
48with atomic commit and rollback. It does this using a separate
49journal file. Whenever a new transaction is started, a journal
50file is created that records the original state of the database.
51If the program terminates before completing the transaction, the next
52process to open the database can use the journal file to restore
53the database to its original state.
54</p>
55
56<p>
57The journal file is located in the same directory as the database
58file and has the same name as the database file but with the
59characters "<tt>-journal</tt>" appended.
60</p>
61
62<p>
63The pager layer does not impose any content restrictions on the
64main database file. As far as the pager is concerned, each page
65contains 1024 bytes of arbitrary data. But there is structure to
66the journal file.
67</p>
68
69<p>
70A journal file begins with 8 bytes as follows:
710xd9, 0xd5, 0x05, 0xf9, 0x20, 0xa1, 0x63, and 0xd6.
72Processes that are attempting to rollback a journal use these 8 bytes
73as a sanity check to make sure the file they think is a journal really
74is a valid journal. Prior version of SQLite used different journal
75file formats. The magic numbers for these prior formats are different
76so that if a new version of the library attempts to rollback a journal
77created by an earlier version, it can detect that the journal uses
78an obsolete format and make the necessary adjustments. This article
79describes only the newest journal format - supported as of version
802.8.0.
81</p>
82
83<p>
84Following the 8 byte prefix is a three 4-byte integers that tell us
85the number of pages that have been committed to the journal,
86a magic number used for
87sanity checking each page, and the
88original size of the main database file before the transaction was
89started. The number of committed pages is used to limit how far
90into the journal to read. The use of the checksum magic number is
91described below.
92The original size of the database is used to restore the database
93file back to its original size.
94The size is expressed in pages (1024 bytes per page).
95</p>
96
97<p>
98All three integers in the journal header and all other multi-byte
99numbers used in the journal file are big-endian.
100That means that the most significant byte
101occurs first. That way, a journal file that is
102originally created on one machine can be rolled back by another
103machine that uses a different byte order. So, for example, a
104transaction that failed to complete on your big-endian SparcStation
105can still be rolled back on your little-endian Linux box.
106</p>
107
108<p>
109After the 8-byte prefix and the three 4-byte integers, the
110journal file consists of zero or more page records. Each page
111record is a 4-byte (big-endian) page number followed by 1024 bytes
112of data and a 4-byte checksum.
113The data is the original content of the database page
114before the transaction was started. So to roll back the transaction,
115the data is simply written into the corresponding page of the
116main database file. Pages can appear in the journal in any order,
117but they are guaranteed to appear only once. All page numbers will be
118between 1 and the maximum specified by the page size integer that
119appeared at the beginning of the journal.
120</p>
121
122<p>
123The so-called checksum at the end of each record is not really a
124checksum - it is the sum of the page number and the magic number which
125was the second integer in the journal header. The purpose of this
126value is to try to detect journal corruption that might have occurred
127because of a power loss or OS crash that occurred which the journal
128file was being written to disk. It could have been the case that the
129meta-data for the journal file, specifically the size of the file, had
130been written to the disk so that when the machine reboots it appears that
131file is large enough to hold the current record. But even though the
132file size has changed, the data for the file might not have made it to
133the disk surface at the time of the OS crash or power loss. This means
134that after reboot, the end of the journal file will contain quasi-random
135garbage data. The checksum is an attempt to detect such corruption. If
136the checksum does not match, that page of the journal is not rolled back.
137</p>
138
139<p>
140Here is a summary of the journal file format:
141</p>
142
143<ul>
144<li>8 byte prefix: 0xd9, 0xd5, 0x05, 0xf9, 0x20, 0xa1, 0x63, 0xd6</li>
145<li>4 byte number of records in journal</li>
146<li>4 byte magic number used for page checksums</li>
147<li>4 byte initial database page count</li>
148<li>Zero or more instances of the following:
149 <ul>
150 <li>4 byte page number</li>
151 <li>1024 bytes of original data for the page</li>
152 <li>4 byte checksum</li>
153 </ul>
154</li>
155</ul>
156
157<h3>3.0 &nbsp; The B-Tree Layer</h3>
158
159<p>
160The B-Tree layer builds on top of the pager layer to implement
161one or more separate b-trees all in the same disk file. The
162algorithms used are taken from Knuth's <i>The Art Of Computer
163Programming.</i></p>
164
165<p>
166Page 1 of a database contains a header string used for sanity
167checking, a few 32-bit words of configuration data, and a pointer
168to the beginning of a list of unused pages in the database.
169All other pages in the
170database are either pages of a b-tree, overflow pages, or unused
171pages on the freelist.
172</p>
173
174<p>
175Each b-tree page contains zero or more database entries.
176Each entry has an unique key of one or more bytes and data of
177zero or more bytes.
178Both the key and data are arbitrary byte sequences. The combination
179of key and data are collectively known as "payload". The current
180implementation limits the amount of payload in a single entry to
1811048576 bytes. This limit can be raised to 16777216 by adjusting
182a single #define in the source code and recompiling. But most entries
183contain less than a hundred bytes of payload so a megabyte limit seems
184more than enough.
185</p>
186
187<p>
188Up to 238 bytes of payload for an entry can be held directly on
189a b-tree page. Any additional payload is contained on a linked list
190of overflow pages. This limit on the amount of payload held directly
191on b-tree pages guarantees that each b-tree page can hold at least
1924 entries. In practice, most entries are smaller than 238 bytes and
193thus most pages can hold more than 4 entries.
194</p>
195
196<p>
197A single database file can hold any number of separate, independent b-trees.
198Each b-tree is identified by its root page, which never changes.
199Child pages of the b-tree may change as entries are added and removed
200and pages split and combine. But the root page always stays the same.
201The b-tree itself does not record which pages are root pages and which
202are not. That information is handled entirely at the schema layer.
203</p>
204
205<h4>3.1 &nbsp; B-Tree Page 1 Details</h4>
206
207<p>
208Page 1 begins with the following 48-byte string:
209</p>
210
211<blockquote><pre>
212** This file contains an SQLite 2.1 database **
213</pre></blockquote>
214
215<p>
216If you count the number of characters in the string above, you will
217see that there are only 47. A '\000' terminator byte is added to
218bring the total to 48.
219</p>
220
221<p>
222A frequent question is why the string says version 2.1 when (as
223of this writing) we are up to version 2.7.0 of SQLite and any
224change to the second digit of the version is suppose to represent
225a database format change. The answer to this is that the B-tree
226layer has not changed any since version 2.1. There have been
227database format changes since version 2.1 but those changes have
228all been in the schema layer. Because the format of the b-tree
229layer is unchanged since version 2.1.0, the header string still
230says version 2.1.
231</p>
232
233<p>
234After the format string is a 4-byte integer used to determine the
235byte-order of the database. The integer has a value of
2360xdae37528. If this number is expressed as 0xda, 0xe3, 0x75, 0x28, then
237the database is in a big-endian format and all 16 and 32-bit integers
238elsewhere in the b-tree layer are also big-endian. If the number is
239expressed as 0x28, 0x75, 0xe3, and 0xda, then the database is in a
240little-endian format and all other multi-byte numbers in the b-tree
241layer are also little-endian.
242Prior to version 2.6.3, the SQLite engine was only able to read databases
243that used the same byte order as the processor they were running on.
244But beginning with 2.6.3, SQLite can read or write databases in any
245byte order.
246</p>
247
248<p>
249After the byte-order code are six 4-byte integers. Each integer is in the
250byte order determined by the byte-order code. The first integer is the
251page number for the first page of the freelist. If there are no unused
252pages in the database, then this integer is 0. The second integer is
253the number of unused pages in the database. The last 4 integers are
254not used by the b-tree layer. These are the so-called "meta" values that
255are passed up to the schema layer
256and used there for configuration and format version information.
257All bytes of page 1 past beyond the meta-value integers are unused
258and are initialized to zero.
259</p>
260
261<p>
262Here is a summary of the information contained on page 1 in the b-tree layer:
263</p>
264
265<ul>
266<li>48 byte header string</li>
267<li>4 byte integer used to determine the byte-order</li>
268<li>4 byte integer which is the first page of the freelist</li>
269<li>4 byte integer which is the number of pages on the freelist</li>
270<li>36 bytes of meta-data arranged as nine 4-byte integers</li>
271<li>928 bytes of unused space</li>
272</ul>
273
274<h4>3.2 &nbsp; Structure Of A Single B-Tree Page</h4>
275
276<p>
277Conceptually, a b-tree page contains N database entries and N+1 pointers
278to other b-tree pages.
279</p>
280
281<blockquote>
282<table border=1 cellspacing=0 cellpadding=5>
283<tr>
284<td align="center">Ptr<br>0</td>
285<td align="center">Entry<br>0</td>
286<td align="center">Ptr<br>1</td>
287<td align="center">Entry<br>1</td>
288<td align="center"><b>...</b></td>
289<td align="center">Ptr<br>N-1</td>
290<td align="center">Entry<br>N-1</td>
291<td align="center">Ptr<br>N</td>
292</tr>
293</table>
294</blockquote>
295
296<p>
297The entries are arranged in increasing order. That is, the key to
298Entry 0 is less than the key to Entry 1, and the key to Entry 1 is
299less than the key of Entry 2, and so forth. The pointers point to
300pages containing additional entries that have keys in between the
301entries on either side. So Ptr 0 points to another b-tree page that
302contains entries that all have keys less than Key 0, and Ptr 1
303points to a b-tree pages where all entries have keys greater than Key 0
304but less than Key 1, and so forth.
305</p>
306
307<p>
308Each b-tree page in SQLite consists of a header, zero or more "cells"
309each holding a single entry and pointer, and zero or more "free blocks"
310that represent unused space on the page.
311</p>
312
313<p>
314The header on a b-tree page is the first 8 bytes of the page.
315The header contains the value
316of the right-most pointer (Ptr N) and the byte offset into the page
317of the first cell and the first free block. The pointer is a 32-bit
318value and the offsets are each 16-bit values. We have:
319</p>
320
321<blockquote>
322<table border=1 cellspacing=0 cellpadding=5>
323<tr>
324<td align="center" width=30>0</td>
325<td align="center" width=30>1</td>
326<td align="center" width=30>2</td>
327<td align="center" width=30>3</td>
328<td align="center" width=30>4</td>
329<td align="center" width=30>5</td>
330<td align="center" width=30>6</td>
331<td align="center" width=30>7</td>
332</tr>
333<tr>
334<td align="center" colspan=4>Ptr N</td>
335<td align="center" colspan=2>Cell 0</td>
336<td align="center" colspan=2>Freeblock 0</td>
337</tr>
338</table>
339</blockquote>
340
341<p>
342The 1016 bytes of a b-tree page that come after the header contain
343cells and freeblocks. All 1016 bytes are covered by either a cell
344or a freeblock.
345</p>
346
347<p>
348The cells are connected in a linked list. Cell 0 contains Ptr 0 and
349Entry 0. Bytes 4 and 5 of the header point to Cell 0. Cell 0 then
350points to Cell 1 which contains Ptr 1 and Entry 1. And so forth.
351Cells vary in size. Every cell has a 12-byte header and at least 4
352bytes of payload space. Space is allocated to payload in increments
353of 4 bytes. Thus the minimum size of a cell is 16 bytes and up to
35463 cells can fit on a single page. The size of a cell is always a multiple
355of 4 bytes.
356A cell can have up to 238 bytes of payload space. If
357the payload is more than 238 bytes, then an additional 4 byte page
358number is appended to the cell which is the page number of the first
359overflow page containing the additional payload. The maximum size
360of a cell is thus 254 bytes, meaning that a least 4 cells can fit into
361the 1016 bytes of space available on a b-tree page.
362An average cell is usually around 52 to 100 bytes in size with about
36310 or 20 cells to a page.
364</p>
365
366<p>
367The data layout of a cell looks like this:
368</p>
369
370<blockquote>
371<table border=1 cellspacing=0 cellpadding=5>
372<tr>
373<td align="center" width=20>0</td>
374<td align="center" width=20>1</td>
375<td align="center" width=20>2</td>
376<td align="center" width=20>3</td>
377<td align="center" width=20>4</td>
378<td align="center" width=20>5</td>
379<td align="center" width=20>6</td>
380<td align="center" width=20>7</td>
381<td align="center" width=20>8</td>
382<td align="center" width=20>9</td>
383<td align="center" width=20>10</td>
384<td align="center" width=20>11</td>
385<td align="center" width=100>12 ... 249</td>
386<td align="center" width=20>250</td>
387<td align="center" width=20>251</td>
388<td align="center" width=20>252</td>
389<td align="center" width=20>253</td>
390</tr>
391<tr>
392<td align="center" colspan=4>Ptr</td>
393<td align="center" colspan=2>Keysize<br>(low)</td>
394<td align="center" colspan=2>Next</td>
395<td align="center" colspan=1>Ksz<br>(hi)</td>
396<td align="center" colspan=1>Dsz<br>(hi)</td>
397<td align="center" colspan=2>Datasize<br>(low)</td>
398<td align="center" colspan=1>Payload</td>
399<td align="center" colspan=4>Overflow<br>Pointer</td>
400</tr>
401</table>
402</blockquote>
403
404<p>
405The first four bytes are the pointer. The size of the key is a 24-bit
406where the upper 8 bits are taken from byte 8 and the lower 16 bits are
407taken from bytes 4 and 5 (or bytes 5 and 4 on little-endian machines.)
408The size of the data is another 24-bit value where the upper 8 bits
409are taken from byte 9 and the lower 16 bits are taken from bytes 10 and
41011 or 11 and 10, depending on the byte order. Bytes 6 and 7 are the
411offset to the next cell in the linked list of all cells on the current
412page. This offset is 0 for the last cell on the page.
413</p>
414
415<p>
416The payload itself can be any number of bytes between 1 and 1048576.
417But space to hold the payload is allocated in 4-byte chunks up to
418238 bytes. If the entry contains more than 238 bytes of payload, then
419additional payload data is stored on a linked list of overflow pages.
420A 4 byte page number is appended to the cell that contains the first
421page of this linked list.
422</p>
423
424<p>
425Each overflow page begins with a 4-byte value which is the
426page number of the next overflow page in the list. This value is
4270 for the last page in the list. The remaining
4281020 bytes of the overflow page are available for storing payload.
429Note that a full page is allocated regardless of the number of overflow
430bytes stored. Thus, if the total payload for an entry is 239 bytes,
431the first 238 are stored in the cell and the overflow page stores just
432one byte.
433</p>
434
435<p>
436The structure of an overflow page looks like this:
437</p>
438
439<blockquote>
440<table border=1 cellspacing=0 cellpadding=5>
441<tr>
442<td align="center" width=20>0</td>
443<td align="center" width=20>1</td>
444<td align="center" width=20>2</td>
445<td align="center" width=20>3</td>
446<td align="center" width=200>4 ... 1023</td>
447</tr>
448<tr>
449<td align="center" colspan=4>Next Page</td>
450<td align="center" colspan=1>Overflow Data</td>
451</tr>
452</table>
453</blockquote>
454
455<p>
456All space on a b-tree page which is not used by the header or by cells
457is filled by freeblocks. Freeblocks, like cells, are variable in size.
458The size of a freeblock is at least 4 bytes and is always a multiple of
4594 bytes.
460The first 4 bytes contain a header and the remaining bytes
461are unused. The structure of the freeblock is as follows:
462</p>
463
464<blockquote>
465<table border=1 cellspacing=0 cellpadding=5>
466<tr>
467<td align="center" width=20>0</td>
468<td align="center" width=20>1</td>
469<td align="center" width=20>2</td>
470<td align="center" width=20>3</td>
471<td align="center" width=200>4 ... 1015</td>
472</tr>
473<tr>
474<td align="center" colspan=2>Size</td>
475<td align="center" colspan=2>Next</td>
476<td align="center" colspan=1>Unused</td>
477</tr>
478</table>
479</blockquote>
480
481<p>
482Freeblocks are stored in a linked list in increasing order. That is
483to say, the first freeblock occurs at a lower index into the page than
484the second free block, and so forth. The first 2 bytes of the header
485are an integer which is the total number of bytes in the freeblock.
486The second 2 bytes are the index into the page of the next freeblock
487in the list. The last freeblock has a Next value of 0.
488</p>
489
490<p>
491When a new b-tree is created in a database, the root page of the b-tree
492consist of a header and a single 1016 byte freeblock. As entries are
493added, space is carved off of that freeblock and used to make cells.
494When b-tree entries are deleted, the space used by their cells is converted
495into freeblocks. Adjacent freeblocks are merged, but the page can still
496become fragmented. The b-tree code will occasionally try to defragment
497the page by moving all cells to the beginning and constructing a single
498freeblock at the end to take up all remaining space.
499</p>
500
501<h4>3.3 &nbsp; The B-Tree Free Page List</h4>
502
503<p>
504When information is removed from an SQLite database such that one or
505more pages are no longer needed, those pages are added to a list of
506free pages so that they can be reused later when new information is
507added. This subsection describes the structure of this freelist.
508</p>
509
510<p>
511The 32-bit integer beginning at byte-offset 52 in page 1 of the database
512contains the address of the first page in a linked list of free pages.
513If there are no free pages available, this integer has a value of 0.
514The 32-bit integer at byte-offset 56 in page 1 contains the number of
515free pages on the freelist.
516</p>
517
518<p>
519The freelist contains a trunk and many branches. The trunk of
520the freelist is composed of overflow pages. That is to say, each page
521contains a single 32-bit integer at byte offset 0 which
522is the page number of the next page on the freelist trunk.
523The payload area
524of each trunk page is used to record pointers to branch pages.
525The first 32-bit integer in the payload area of a trunk page
526is the number of branch pages to follow (between 0 and 254)
527and each subsequent 32-bit integer is a page number for a branch page.
528The following diagram shows the structure of a trunk freelist page:
529</p>
530
531<blockquote>
532<table border=1 cellspacing=0 cellpadding=5>
533<tr>
534<td align="center" width=20>0</td>
535<td align="center" width=20>1</td>
536<td align="center" width=20>2</td>
537<td align="center" width=20>3</td>
538<td align="center" width=20>4</td>
539<td align="center" width=20>5</td>
540<td align="center" width=20>6</td>
541<td align="center" width=20>7</td>
542<td align="center" width=200>8 ... 1023</td>
543</tr>
544<tr>
545<td align="center" colspan=4>Next trunk page</td>
546<td align="center" colspan=4># of branch pages</td>
547<td align="center" colspan=1>Page numbers for branch pages</td>
548</tr>
549</table>
550</blockquote>
551
552<p>
553It is important to note that only the pages on the trunk of the freelist
554contain pointers to other pages. The branch pages contain no
555data whatsoever. The fact that the branch pages are completely
556blank allows for an important optimization in the paging layer. When
557a branch page is removed from the freelist to be reused, it is not
558necessary to write the original content of that page into the rollback
559journal. The branch page contained no data to begin with, so there is
560no need to restore the page in the event of a rollback. Similarly,
561when a page is not longer needed and is added to the freelist as a branch
562page, it is not necessary to write the content of that page
563into the database file.
564Again, the page contains no real data so it is not necessary to record the
565content of that page. By reducing the amount of disk I/O required,
566these two optimizations allow some database operations
567to go four to six times faster than they would otherwise.
568</p>
569
570<h3>4.0 &nbsp; The Schema Layer</h3>
571
572<p>
573The schema layer implements an SQL database on top of one or more
574b-trees and keeps track of the root page numbers for all b-trees.
575Where the b-tree layer provides only unformatted data storage with
576a unique key, the schema layer allows each entry to contain multiple
577columns. The schema layer also allows indices and non-unique key values.
578</p>
579
580<p>
581The schema layer implements two separate data storage abstractions:
582tables and indices. Each table and each index uses its own b-tree
583but they use the b-tree capabilities in different ways. For a table,
584the b-tree key is a unique 4-byte integer and the b-tree data is the
585content of the table row, encoded so that columns can be separately
586extracted. For indices, the b-tree key varies in size depending on the
587size of the fields being indexed and the b-tree data is empty.
588</p>
589
590<h4>4.1 &nbsp; SQL Table Implementation Details</h4>
591
592<p>Each row of an SQL table is stored in a single b-tree entry.
593The b-tree key is a 4-byte big-endian integer that is the ROWID
594or INTEGER PRIMARY KEY for that table row.
595The key is stored in a big-endian format so
596that keys will sort in numerical order using memcmp() function.</p>
597
598<p>The content of a table row is stored in the data portion of
599the corresponding b-tree table. The content is encoded to allow
600individual columns of the row to be extracted as necessary. Assuming
601that the table has N columns, the content is encoded as N+1 offsets
602followed by N column values, as follows:
603</p>
604
605<blockquote>
606<table border=1 cellspacing=0 cellpadding=5>
607<tr>
608<td>offset 0</td>
609<td>offset 1</td>
610<td><b>...</b></td>
611<td>offset N-1</td>
612<td>offset N</td>
613<td>value 0</td>
614<td>value 1</td>
615<td><b>...</b></td>
616<td>value N-1</td>
617</tr>
618</table>
619</blockquote>
620
621<p>
622The offsets can be either 8-bit, 16-bit, or 24-bit integers depending
623on how much data is to be stored. If the total size of the content
624is less than 256 bytes then 8-bit offsets are used. If the total size
625of the b-tree data is less than 65536 then 16-bit offsets are used.
62624-bit offsets are used otherwise. Offsets are always little-endian,
627which means that the least significant byte occurs first.
628</p>
629
630<p>
631Data is stored as a nul-terminated string. Any empty string consists
632of just the nul terminator. A NULL value is an empty string with no
633nul-terminator. Thus a NULL value occupies zero bytes and an empty string
634occupies 1 byte.
635</p>
636
637<p>
638Column values are stored in the order that they appear in the CREATE TABLE
639statement. The offsets at the beginning of the record contain the
640byte index of the corresponding column value. Thus, Offset 0 contains
641the byte index for Value 0, Offset 1 contains the byte offset
642of Value 1, and so forth. The number of bytes in a column value can
643always be found by subtracting offsets. This allows NULLs to be
644recovered from the record unambiguously.
645</p>
646
647<p>
648Most columns are stored in the b-tree data as described above.
649The one exception is column that has type INTEGER PRIMARY KEY.
650INTEGER PRIMARY KEY columns correspond to the 4-byte b-tree key.
651When an SQL statement attempts to read the INTEGER PRIMARY KEY,
652the 4-byte b-tree key is read rather than information out of the
653b-tree data. But there is still an Offset associated with the
654INTEGER PRIMARY KEY, just like any other column. But the Value
655associated with that offset is always NULL.
656</p>
657
658<h4>4.2 &nbsp; SQL Index Implementation Details</h4>
659
660<p>
661SQL indices are implement using a b-tree in which the key is used
662but the data is always empty. The purpose of an index is to map
663one or more column values into the ROWID for the table entry that
664contains those column values.
665</p>
666
667<p>
668Each b-tree in an index consists of one or more column values followed
669by a 4-byte ROWID. Each column value is nul-terminated (even NULL values)
670and begins with a single character that indicates the datatype for that
671column value. Only three datatypes are supported: NULL, Number, and
672Text. NULL values are encoded as the character 'a' followed by the
673nul terminator. Numbers are encoded as the character 'b' followed by
674a string that has been crafted so that sorting the string using memcmp()
675will sort the corresponding numbers in numerical order. (See the
676sqliteRealToSortable() function in util.c of the SQLite sources for
677additional information on this encoding.) Numbers are also nul-terminated.
678Text values consists of the character 'c' followed by a copy of the
679text string and a nul-terminator. These encoding rules result in
680NULLs being sorted first, followed by numerical values in numerical
681order, followed by text values in lexicographical order.
682</p>
683
684<h4>4.4 &nbsp; SQL Schema Storage And Root B-Tree Page Numbers</h4>
685
686<p>
687The database schema is stored in the database in a special tabled named
688"sqlite_master" and which always has a root b-tree page number of 2.
689This table contains the original CREATE TABLE,
690CREATE INDEX, CREATE VIEW, and CREATE TRIGGER statements used to define
691the database to begin with. Whenever an SQLite database is opened,
692the sqlite_master table is scanned from beginning to end and
693all the original CREATE statements are played back through the parser
694in order to reconstruct an in-memory representation of the database
695schema for use in subsequent command parsing. For each CREATE TABLE
696and CREATE INDEX statement, the root page number for the corresponding
697b-tree is also recorded in the sqlite_master table so that SQLite will
698know where to look for the appropriate b-tree.
699</p>
700
701<p>
702SQLite users can query the sqlite_master table just like any other table
703in the database. But the sqlite_master table cannot be directly written.
704The sqlite_master table is automatically updated in response to CREATE
705and DROP statements but it cannot be changed using INSERT, UPDATE, or
706DELETE statements as that would risk corrupting the database.
707</p>
708
709<p>
710SQLite stores temporary tables and indices in a separate
711file from the main database file. The temporary table database file
712is the same structure as the main database file. The schema table
713for the temporary tables is stored on page 2 just as in the main
714database. But the schema table for the temporary database named
715"sqlite_temp_master" instead of "sqlite_master". Other than the
716name change, it works exactly the same.
717</p>
718
719<h4>4.4 &nbsp; Schema Version Numbering And Other Meta-Information</h4>
720
721<p>
722The nine 32-bit integers that are stored beginning at byte offset
72360 of Page 1 in the b-tree layer are passed up into the schema layer
724and used for versioning and configuration information. The meaning
725of the first four integers is shown below. The other five are currently
726unused.
727</p>
728
729<ol>
730<li>The schema version number</li>
731<li>The format version number</li>
732<li>The recommended pager cache size</li>
733<li>The safety level</li>
734</ol>
735
736<p>
737The first meta-value, the schema version number, is used to detect when
738the schema of the database is changed by a CREATE or DROP statement.
739Recall that when a database is first opened the sqlite_master table is
740scanned and an internal representation of the tables, indices, views,
741and triggers for the database is built in memory. This internal
742representation is used for all subsequent SQL command parsing and
743execution. But what if another process were to change the schema
744by adding or removing a table, index, view, or trigger? If the original
745process were to continue using the old schema, it could potentially
746corrupt the database by writing to a table that no longer exists.
747To avoid this problem, the schema version number is changed whenever
748a CREATE or DROP statement is executed. Before each command is
749executed, the current schema version number for the database file
750is compared against the schema version number from when the sqlite_master
751table was last read. If those numbers are different, the internal
752schema representation is erased and the sqlite_master table is reread
753to reconstruct the internal schema representation.
754(Calls to sqlite_exec() generally return SQLITE_SCHEMA when this happens.)
755</p>
756
757<p>
758The second meta-value is the schema format version number. This
759number tells what version of the schema layer should be used to
760interpret the file. There have been changes to the schema layer
761over time and this number is used to detect when an older database
762file is being processed by a newer version of the library.
763As of this writing (SQLite version 2.7.0) the current format version
764is "4".
765</p>
766
767<p>
768The third meta-value is the recommended pager cache size as set
769by the DEFAULT_CACHE_SIZE pragma. If the value is positive it
770means that synchronous behavior is enable (via the DEFAULT_SYNCHRONOUS
771pragma) and if negative it means that synchronous behavior is
772disabled.
773</p>
774
775<p>
776The fourth meta-value is safety level added in version 2.8.0.
777A value of 1 corresponds to a SYNCHRONOUS setting of OFF. In other
778words, SQLite does not pause to wait for journal data to reach the disk
779surface before overwriting pages of the database. A value of 2 corresponds
780to a SYNCHRONOUS setting of NORMAL. A value of 3 corresponds to a
781SYNCHRONOUS setting of FULL. If the value is 0, that means it has not
782been initialized so the default synchronous setting of NORMAL is used.
783</p>
784}
785footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/formatchng.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/formatchng.tcl
deleted file mode 100644
index 83a2dcf..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/formatchng.tcl
+++ /dev/null
@@ -1,285 +0,0 @@
1#
2# Run this Tcl script to generate the formatchng.html file.
3#
4set rcsid {$Id: formatchng.tcl,v 1.20 2007/09/03 20:32:45 drh Exp $ }
5source common.tcl
6header {File Format Changes in SQLite}
7puts {
8<h2>File Format Changes in SQLite</h2>
9
10<p>
11Every effort is made to keep SQLite fully backwards compatible from
12one release to the next. Rarely, however, some
13enhancements or bug fixes may require a change to
14the underlying file format. When this happens and you
15must convert the contents of your
16databases into a portable ASCII representation using the old version
17of the library then reload the data using the new version of the
18library.
19</p>
20
21<p>
22You can tell if you should reload your databases by comparing the
23version numbers of the old and new libraries. If the first digit
24of the version number is different, then a reload of the database will
25be required. If the second digit changes, newer versions of SQLite
26will be able to read and write older database files, but older versions
27of the library may have difficulty reading or writing newer database
28files.
29For example, upgrading from
30version 2.8.14 to 3.0.0 requires a reload. Going from
31version 3.0.8 to 3.1.0 is backwards compatible but not necessarily
32forwards compatible.
33</p>
34
35<p>
36The following table summarizes the SQLite file format changes that have
37occurred since version 1.0.0:
38</p>
39
40<blockquote>
41<table border=2 cellpadding=5>
42<tr>
43 <th>Version Change</th>
44 <th>Approx. Date</th>
45 <th>Description Of File Format Change</th>
46</tr>
47<tr>
48 <td valign="top">1.0.32 to 2.0.0</td>
49 <td valign="top">2001-Sep-20</td>
50 <td>Version 1.0.X of SQLite used the GDBM library as its backend
51 interface to the disk. Beginning in version 2.0.0, GDBM was replaced
52 by a custom B-Tree library written especially for SQLite. The new
53 B-Tree backend is twice as fast as GDBM, supports atomic commits and
54 rollback, and stores an entire database in a single disk file instead
55 using a separate file for each table as GDBM does. The two
56 file formats are not even remotely similar.</td>
57</tr>
58<tr>
59 <td valign="top">2.0.8 to 2.1.0</td>
60 <td valign="top">2001-Nov-12</td>
61 <td>The same basic B-Tree format is used but the details of the
62 index keys were changed in order to provide better query
63 optimization opportunities. Some of the headers were also changed in order
64 to increase the maximum size of a row from 64KB to 24MB.<p>
65
66 This change is an exception to the version number rule described above
67 in that it is neither forwards or backwards compatible. A complete
68 reload of the database is required. This is the only exception.</td>
69</tr>
70<tr>
71 <td valign="top">2.1.7 to 2.2.0</td>
72 <td valign="top">2001-Dec-21</td>
73 <td>Beginning with version 2.2.0, SQLite no longer builds an index for
74 an INTEGER PRIMARY KEY column. Instead, it uses that column as the actual
75 B-Tree key for the main table.<p>Version 2.2.0 and later of the library
76 will automatically detect when it is reading a 2.1.x database and will
77 disable the new INTEGER PRIMARY KEY feature. In other words, version
78 2.2.x is backwards compatible to version 2.1.x. But version 2.1.x is not
79 forward compatible with version 2.2.x. If you try to open
80 a 2.2.x database with an older 2.1.x library and that database contains
81 an INTEGER PRIMARY KEY, you will likely get a coredump. If the database
82 schema does not contain any INTEGER PRIMARY KEYs, then the version 2.1.x
83 and version 2.2.x database files will be identical and completely
84 interchangeable.</p>
85</tr>
86<tr>
87 <td valign="top">2.2.5 to 2.3.0</td>
88 <td valign="top">2002-Jan-30</td>
89 <td>Beginning with version 2.3.0, SQLite supports some additional syntax
90 (the "ON CONFLICT" clause) in the CREATE TABLE and CREATE INDEX statements
91 that are stored in the SQLITE_MASTER table. If you create a database that
92 contains this new syntax, then try to read that database using version 2.2.5
93 or earlier, the parser will not understand the new syntax and you will get
94 an error. Otherwise, databases for 2.2.x and 2.3.x are interchangeable.</td>
95</tr>
96<tr>
97 <td valign="top">2.3.3 to 2.4.0</td>
98 <td valign="top">2002-Mar-10</td>
99 <td>Beginning with version 2.4.0, SQLite added support for views.
100 Information about views is stored in the SQLITE_MASTER table. If an older
101 version of SQLite attempts to read a database that contains VIEW information
102 in the SQLITE_MASTER table, the parser will not understand the new syntax
103 and initialization will fail. Also, the
104 way SQLite keeps track of unused disk blocks in the database file
105 changed slightly.
106 If an older version of SQLite attempts to write a database that
107 was previously written by version 2.4.0 or later, then it may leak disk
108 blocks.</td>
109</tr>
110<tr>
111 <td valign="top">2.4.12 to 2.5.0</td>
112 <td valign="top">2002-Jun-17</td>
113 <td>Beginning with version 2.5.0, SQLite added support for triggers.
114 Information about triggers is stored in the SQLITE_MASTER table. If an older
115 version of SQLite attempts to read a database that contains a CREATE TRIGGER
116 in the SQLITE_MASTER table, the parser will not understand the new syntax
117 and initialization will fail.
118 </td>
119</tr>
120<tr>
121 <td valign="top">2.5.6 to 2.6.0</td>
122 <td valign="top">2002-July-17</td>
123 <td>A design flaw in the layout of indices required a file format change
124 to correct. This change appeared in version 2.6.0.<p>
125
126 If you use version 2.6.0 or later of the library to open a database file
127 that was originally created by version 2.5.6 or earlier, an attempt to
128 rebuild the database into the new format will occur automatically.
129 This can take some time for a large database. (Allow 1 or 2 seconds
130 per megabyte of database under Unix - longer under Windows.) This format
131 conversion is irreversible. It is <strong>strongly</strong> suggested
132 that you make a backup copy of older database files prior to opening them
133 with version 2.6.0 or later of the library, in case there are errors in
134 the format conversion logic.<p>
135
136 Version 2.6.0 or later of the library cannot open read-only database
137 files from version 2.5.6 or earlier, since read-only files cannot be
138 upgraded to the new format.</p>
139 </td>
140</tr>
141<tr>
142 <td valign="top">2.6.3 to 2.7.0</td>
143 <td valign="top">2002-Aug-13</td>
144 <td><p>Beginning with version 2.7.0, SQLite understands two different
145 datatypes: text and numeric. Text data sorts in memcmp() order.
146 Numeric data sorts in numerical order if it looks like a number,
147 or in memcmp() order if it does not.</p>
148
149 <p>When SQLite version 2.7.0 or later opens a 2.6.3 or earlier database,
150 it assumes all columns of all tables have type "numeric". For 2.7.0
151 and later databases, columns have type "text" if their datatype
152 string contains the substrings "char" or "clob" or "blob" or "text".
153 Otherwise they are of type "numeric".</p>
154
155 <p>Because "text" columns have a different sort order from numeric,
156 indices on "text" columns occur in a different order for version
157 2.7.0 and later database. Hence version 2.6.3 and earlier of SQLite
158 will be unable to read a 2.7.0 or later database. But version 2.7.0
159 and later of SQLite will read earlier databases.</p>
160 </td>
161</tr>
162<tr>
163 <td valign="top">2.7.6 to 2.8.0</td>
164 <td valign="top">2003-Feb-14</td>
165 <td><p>Version 2.8.0 introduces a change to the format of the rollback
166 journal file. The main database file format is unchanged. Versions
167 2.7.6 and earlier can read and write 2.8.0 databases and vice versa.
168 Version 2.8.0 can rollback a transaction that was started by version
169 2.7.6 and earlier. But version 2.7.6 and earlier cannot rollback a
170 transaction started by version 2.8.0 or later.</p>
171
172 <p>The only time this would ever be an issue is when you have a program
173 using version 2.8.0 or later that crashes with an incomplete
174 transaction, then you try to examine the database using version 2.7.6 or
175 earlier. The 2.7.6 code will not be able to read the journal file
176 and thus will not be able to rollback the incomplete transaction
177 to restore the database.</p>
178 </td>
179</tr>
180<tr>
181 <td valign="top">2.8.14 to 3.0.0</td>
182 <td valign="top">2004-Jun-18</td>
183 <td><p>Version 3.0.0 is a major upgrade for SQLite that incorporates
184 support for UTF-16, BLOBs, and a more compact encoding that results
185 in database files that are typically 25% to 50% smaller. The new file
186 format is very different and is completely incompatible with the
187 version 2 file format.</p>
188 </td>
189</tr>
190<tr>
191 <td valign="top">3.0.8 to 3.1.0</td>
192 <td valign="top">2005-Jan-21</td>
193 <td><p>Version 3.1.0 adds support for
194 <a href="pragma.html#pragma_auto_vacuum">autovacuum mode</a>.
195 Prior versions of SQLite will be able to read an autovacuumed
196 database but will not be able to write it. If autovaccum is disabled
197 (which is the default condition)
198 then databases are fully forwards and backwards compatible.</p>
199 </td>
200</tr>
201<tr>
202 <td valign="top">3.1.6 to 3.2.0</td>
203 <td valign="top">2005-Mar-19</td>
204 <td><p>Version 3.2.0 adds support for the
205 <a href="lang_altertable.html">ALTER TABLE ADD COLUMN</a>
206 command. A database that has been modified by this command can
207 not be read by a version of SQLite prior to 3.1.4. Running
208 <a href="lang_vacuum.html">VACUUM</a>
209 after the ALTER TABLE
210 restores the database to a format such that it can be read by earlier
211 SQLite versions.</p>
212 </td>
213</tr>
214<tr>
215 <td valign="top">3.2.8 to 3.3.0</td>
216 <td valign="top">2006-Jan-10</td>
217 <td><p>Version 3.3.0 adds support for descending indices and
218 uses a new encoding for boolean values that requires
219 less disk space. Version 3.3.0 can read and write database
220 files created by prior versions of SQLite. But prior versions
221 of SQLite will not be able to read or write databases created
222 by Version 3.3.0</p>
223 <p>If you need backwards and forwards capatibility, you can
224 compile with -DSQLITE_DEFAULT_FILE_FORMAT=1. Or at runtime
225 you can say "PRAGMA legacy_file_format=ON" prior to creating
226 a new database file</p>
227 <p>Once a database file is created, its format is fixed. So
228 a database file created by SQLite 3.2.8 and merely modified
229 by version 3.3.0 or later will retain the old format. Except,
230 the VACUUM command recreates the database so running VACUUM
231 on 3.3.0 or later will change the file format to the latest
232 edition.</p>
233 </td>
234</tr>
235<tr>
236 <td valign="top">3.3.6 to 3.3.7</td>
237 <td valign="top">2006-Aug-12</td>
238 <td><p>The previous file format change has caused so much
239 grief that the default behavior has been changed back to
240 the original file format. This means that DESC option on
241 indices is ignored by default that the more efficient encoding
242 of boolean values is not used. In that way, older versions
243 of SQLite can read and write databases created by newer
244 versions. If the new features are desired, they can be
245 enabled using pragma: "PRAGMA legacy_file_format=OFF".</p>
246 <p>To be clear: both old and new file formats continue to
247 be understood and continue to work. But the old file format
248 is used by default instead of the new. This might change
249 again in some future release - we may go back to generating
250 the new file format by default - but probably not until
251 all users have upgraded to a version of SQLite that will
252 understand the new file format. That might take several
253 years.</p></td>
254</tr>
255<tr>
256 <td valign="top">3.4.2 to 3.5.0</td>
257 <td valign="top">2007-Sep-3</td>
258 <td><p>The design of the OS interface layer was changed for
259 release 3.5.0. Applications that implemented a custom OS
260 interface will need to be modified in order to upgrade.
261 There are also some subtly different semantics a few obscure
262 APIs. An <a href="34to35.html">article</a> is avilable which
263 describing the changes in detail.</p>
264
265 <p>The on-disk file format is unchanged.</p>
266 </td>
267</tr>
268</table>
269</blockquote>
270
271<p>
272To perform a database reload, have ready versions of the
273<b>sqlite</b> command-line utility for both the old and new
274version of SQLite. Call these two executables "<b>sqlite-old</b>"
275and "<b>sqlite-new</b>". Suppose the name of your old database
276is "<b>old.db</b>" and you want to create a new database with
277the same information named "<b>new.db</b>". The command to do
278this is as follows:
279</p>
280
281<blockquote>
282 sqlite-old old.db .dump | sqlite-new new.db
283</blockquote>
284}
285footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/fullscanb.gif b/libraries/sqlite/unix/sqlite-3.5.1/www/fullscanb.gif
deleted file mode 100644
index becb514..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/fullscanb.gif
+++ /dev/null
Binary files differ
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/index-ex1-x-b.gif b/libraries/sqlite/unix/sqlite-3.5.1/www/index-ex1-x-b.gif
deleted file mode 100644
index 37354ce..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/index-ex1-x-b.gif
+++ /dev/null
Binary files differ
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/index.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/index.tcl
deleted file mode 100644
index 2eb5cef..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/index.tcl
+++ /dev/null
@@ -1,126 +0,0 @@
1#!/usr/bin/tclsh
2source common.tcl
3header {SQLite home page}
4puts {
5<table width="100%" border="0" cellspacing="5">
6<tr>
7<td width="50%" valign="top">
8<h2>About SQLite</h2>
9<p>
10 <table align="right" border="0"><tr><td>
11 <a href="http://osdir.com/Article6677.phtml">
12 <img src="2005osaward.gif"></a>
13 </td></tr></table>
14SQLite is a small
15C library that implements a self-contained, embeddable,
16zero-configuration
17SQL database engine.
18Features include:
19</p>
20
21<p><ul>
22<li>Transactions are atomic, consistent, isolated, and durable (ACID)
23 even after system crashes and power failures.
24<li>Zero-configuration - no setup or administration needed.</li>
25<li>Implements most of SQL92.
26 (<a href="omitted.html">Features not supported</a>)</li>
27<li>A complete database is stored in a single disk file.</li>
28<li>Database files can be freely shared between machines with
29 different byte orders.</li>
30<li>Supports terabyte-sized databases and gigabyte-sized strings
31 and blobs. (See <a href="limits.html">limits.html</a>.)
32<li>Small code footprint:
33 <a href="http://www.sqlite.org/cvstrac/wiki?p=SizeOfSqlite">
34 less than 250KiB</a> fully configured or less
35 than 150KiB with optional features omitted.</li>
36<li><a href="speed.html">Faster</a> than popular client/server database
37 engines for most common operations.</li>
38<li>Simple, easy to use <a href="capi3.html">API</a>.</li>
39<li><a href="tclsqlite.html">TCL bindings</a> included.
40 Bindings for many other languages
41 <a href="http://www.sqlite.org/cvstrac/wiki?p=SqliteWrappers">
42 available separately.</a></li>
43<li>Well-commented source code with over 98% test coverage.</li>
44<li>Available as a
45 <a href="http://www.sqlite.org/cvstrac/wiki?p=TheAmalgamation">
46 single ANSI-C source-code file</a> that you can easily drop into
47 another project.
48<li>Self-contained: no external dependencies.</li>
49<li>Sources are in the <a href="copyright.html">public domain</a>.
50 Use for any purpose.</li>
51</ul>
52</p>
53
54<p>
55The SQLite distribution comes with a standalone command-line
56access program (<a href="sqlite.html">sqlite</a>) that can
57be used to administer an SQLite database and which serves as
58an example of how to use the SQLite library.
59</p>
60
61</td>
62<td width="1" bgcolor="#80a796"></td>
63<td valign="top" width="50%">
64<h2>News</h2>
65}
66
67proc newsitem {date title text} {
68 puts "<h3>$date - $title</h3>"
69 regsub -all "\n( *\n)+" $text "</p>\n\n<p>" txt
70 puts "<p>$txt</p>"
71 puts "<hr width=\"50%\">"
72}
73
74newsitem {2007-Oct-04} {Version 3.5.1} {
75 Fix a long-standing bug that might cause database corruption if a
76 disk-full error occurs in the middle of a transaction and that
77 transaction is not rolled back.
78 <a href="http://www.sqlite.org/cvstrac/tktview?tn=2686">Ticket #2686.</a>
79
80 The new VFS layer is stable. However, we still reserve the right to
81 make tweaks to the interface definition of the VFS if necessary.
82}
83
84newsitem {2007-Sep-04} {Version 3.5.0 alpha} {
85 The OS interface layer and the memory allocation subsystems in
86 SQLite have been reimplemented. The published API is largely unchanged
87 but the (unpublished) OS interface has been modified extensively.
88 Applications that implement their own OS interface will require
89 modification. See
90 <a href="34to35.html">34to35.html</a> for details.<p>
91
92 This is a large change. Approximately 10% of the source code was
93 modified. We are calling this first release "alpha" in order to give
94 the user community time to test and evaluate the changes before we
95 freeze the new design.
96}
97
98newsitem {2007-Aug-13} {Version 3.4.2} {
99 While stress-testing the
100 <a href="capi3ref.html#sqlite3_soft_heap_limit">soft_heap_limit</a>
101 feature, a bug that could lead to
102 <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption">database
103 corruption</a> was <a href="http://www.sqlite.org/cvstrac/tktview?tn=2565">
104 discovered and fixed</a>.
105 Though the consequences of this bug are severe, the chances of hitting
106 it in a typical application are remote. Upgrading is recommended
107 only if you use the
108 <a href="capi3ref.html#sqlite3_soft_heap_limit">sqlite3_soft_heap_limit</a>
109 interface.
110}
111
112newsitem {2007-Jly-20} {Version 3.4.1} {
113 This release fixes a bug in <a href="lang_vacuum.html">VACUUM</a> that
114 can lead to <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption">
115 database corruption</a>. The bug was introduced in version
116 <a href="changes.html#version_3_3_14">3.3.14</a>.
117 Upgrading is recommended for all users. Also included are a slew of
118 other more routine
119 <a href="changes.html#version_3_4_1">enhancements and bug fixes</a>.
120}
121
122puts {
123<p align="right"><a href="oldnews.html">Old news...</a></p>
124</td></tr></table>
125}
126footer {$Id: index.tcl,v 1.164 2007/10/03 20:32:17 drh Exp $}
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/indirect1b1.gif b/libraries/sqlite/unix/sqlite-3.5.1/www/indirect1b1.gif
deleted file mode 100644
index 25285d5..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/indirect1b1.gif
+++ /dev/null
Binary files differ
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/lang.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/lang.tcl
deleted file mode 100644
index 1c8b1e7..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/lang.tcl
+++ /dev/null
@@ -1,2203 +0,0 @@
1#
2# Run this Tcl script to generate the lang-*.html files.
3#
4set rcsid {$Id: lang.tcl,v 1.136 2007/10/03 20:15:28 drh Exp $}
5source common.tcl
6
7if {[llength $argv]>0} {
8 set outputdir [lindex $argv 0]
9} else {
10 set outputdir ""
11}
12
13header {Query Language Understood by SQLite}
14puts {
15<h1 class="pdf_section">SQL As Understood By SQLite</h1>
16
17<p>The SQLite library understands most of the standard SQL
18language. But it does <a href="omitted.html">omit some features</a>
19while at the same time
20adding a few features of its own. This document attempts to
21describe precisely what parts of the SQL language SQLite does
22and does not support. A list of <a href="lang_keywords.html">keywords</a> is
23also provided.</p>
24
25<p>In all of the syntax diagrams that follow, literal text is shown in
26bold blue. Non-terminal symbols are shown in italic red. Operators
27that are part of the syntactic markup itself are shown in black roman.</p>
28
29<p>This document is just an overview of the SQL syntax implemented
30by SQLite. Many low-level productions are omitted. For detailed information
31on the language that SQLite understands, refer to the source code and
32the grammar file "parse.y".</p>
33
34<div class="pdf_ignore">
35<p>SQLite implements the follow syntax:</p>
36<p><ul>
37}
38
39proc slink {label} {
40 if {[string match *.html $label]} {
41 return $label
42 }
43 if {[string length $::outputdir]==0} {
44 return #$label
45 } else {
46 return lang_$label.html
47 }
48}
49
50foreach {section} [lsort -index 0 -dictionary {
51 {{CREATE TABLE} createtable}
52 {{CREATE VIRTUAL TABLE} createvtab}
53 {{CREATE INDEX} createindex}
54 {VACUUM vacuum}
55 {{DROP TABLE} droptable}
56 {{DROP INDEX} dropindex}
57 {INSERT insert}
58 {REPLACE replace}
59 {DELETE delete}
60 {UPDATE update}
61 {SELECT select}
62 {comment comment}
63 {COPY copy}
64 {EXPLAIN explain}
65 {expression expr}
66 {{BEGIN TRANSACTION} transaction}
67 {{COMMIT TRANSACTION} transaction}
68 {{END TRANSACTION} transaction}
69 {{ROLLBACK TRANSACTION} transaction}
70 {PRAGMA pragma.html}
71 {{ON CONFLICT clause} conflict}
72 {{CREATE VIEW} createview}
73 {{DROP VIEW} dropview}
74 {{CREATE TRIGGER} createtrigger}
75 {{DROP TRIGGER} droptrigger}
76 {{ATTACH DATABASE} attach}
77 {{DETACH DATABASE} detach}
78 {REINDEX reindex}
79 {{ALTER TABLE} altertable}
80 {{ANALYZE} analyze}
81}] {
82 foreach {s_title s_tag} $section {}
83 puts "<li><a href=\"[slink $s_tag]\">$s_title</a></li>"
84}
85puts {</ul></p>
86</div>
87
88<p>Details on the implementation of each command are provided in
89the sequel.</p>
90}
91
92proc Operator {name} {
93 return "<font color=\"#2c2cf0\"><big>$name</big></font>"
94}
95proc Nonterminal {name} {
96 return "<i><font color=\"#ff3434\">$name</font></i>"
97}
98proc Keyword {name} {
99 return "<font color=\"#2c2cf0\">$name</font>"
100}
101proc Example {text} {
102 puts "<blockquote><pre>$text</pre></blockquote>"
103}
104
105proc Section {name label} {
106 global outputdir
107
108 if {[string length $outputdir]!=0} {
109 if {[llength [info commands puts_standard]]>0} {
110 footer $::rcsid
111 }
112
113 if {[string length $label]>0} {
114 rename puts puts_standard
115 proc puts {str} {
116 regsub -all {href="#([a-z]+)"} $str {href="lang_\1.html"} str
117 puts_standard $::section_file $str
118 }
119 rename footer footer_standard
120 proc footer {id} {
121 footer_standard $id
122 rename footer ""
123 rename puts ""
124 rename puts_standard puts
125 rename footer_standard footer
126 }
127 set ::section_file [open [file join $outputdir lang_$label.html] w]
128 header "Query Language Understood by SQLite: $name"
129 puts "<h1>SQL As Understood By SQLite</h1>"
130 puts "<a href=\"lang.html\">\[Contents\]</a>"
131 puts "<h2>$name</h2>"
132 return
133 }
134 }
135 puts "\n<hr />"
136 if {$label!=""} {
137 puts "<a name=\"$label\"></a>"
138 }
139 puts "<h1>$name</h1>\n"
140}
141
142Section {ALTER TABLE} altertable
143
144Syntax {sql-statement} {
145ALTER TABLE [<database-name> .] <table-name> <alteration>
146} {alteration} {
147RENAME TO <new-table-name>
148} {alteration} {
149ADD [COLUMN] <column-def>
150}
151
152puts {
153<p>SQLite's version of the ALTER TABLE command allows the user to
154rename or add a new column to an existing table. It is not possible
155to remove a column from a table.
156</p>
157
158<p>The RENAME TO syntax is used to rename the table identified by
159<i>[database-name.]table-name</i> to <i>new-table-name</i>. This command
160cannot be used to move a table between attached databases, only to rename
161a table within the same database.</p>
162
163<p>If the table being renamed has triggers or indices, then these remain
164attached to the table after it has been renamed. However, if there are
165any view definitions, or statements executed by triggers that refer to
166the table being renamed, these are not automatically modified to use the new
167table name. If this is required, the triggers or view definitions must be
168dropped and recreated to use the new table name by hand.
169</p>
170
171<p>The ADD [COLUMN] syntax is used to add a new column to an existing table.
172The new column is always appended to the end of the list of existing columns.
173<i>Column-def</i> may take any of the forms permissable in a CREATE TABLE
174statement, with the following restrictions:
175<ul>
176<li>The column may not have a PRIMARY KEY or UNIQUE constraint.</li>
177<li>The column may not have a default value of CURRENT_TIME, CURRENT_DATE
178 or CURRENT_TIMESTAMP.</li>
179<li>If a NOT NULL constraint is specified, then the column must have a
180 default value other than NULL.
181</ul>
182
183<p>The execution time of the ALTER TABLE command is independent of
184the amount of data in the table. The ALTER TABLE command runs as quickly
185on a table with 10 million rows as it does on a table with 1 row.
186</p>
187
188<p>After ADD COLUMN has been run on a database, that database will not
189be readable by SQLite version 3.1.3 and earlier until the database
190is <a href="lang_vacuum.html">VACUUM</a>ed.</p>
191}
192
193Section {ANALYZE} analyze
194
195Syntax {sql-statement} {
196 ANALYZE
197}
198Syntax {sql-statement} {
199 ANALYZE <database-name>
200}
201Syntax {sql-statement} {
202 ANALYZE [<database-name> .] <table-name>
203}
204
205puts {
206<p>The ANALYZE command gathers statistics about indices and stores them
207in a special tables in the database where the query optimizer can use
208them to help make better index choices.
209If no arguments are given, all indices in all attached databases are
210analyzed. If a database name is given as the argument, all indices
211in that one database are analyzed. If the argument is a table name,
212then only indices associated with that one table are analyzed.</p>
213
214<p>The initial implementation stores all statistics in a single
215table named <b>sqlite_stat1</b>. Future enhancements may create
216additional tables with the same name pattern except with the "1"
217changed to a different digit. The <b>sqlite_stat1</b> table cannot
218be <a href="#droptable">DROP</a>ped,
219but all the content can be <a href="#delete">DELETE</a>d which has the
220same effect.</p>
221}
222
223Section {ATTACH DATABASE} attach
224
225Syntax {sql-statement} {
226ATTACH [DATABASE] <database-filename> AS <database-name>
227}
228
229puts {
230<p>The ATTACH DATABASE statement adds another database
231file to the current database connection. If the filename contains
232punctuation characters it must be quoted. The names 'main' and
233'temp' refer to the main database and the database used for
234temporary tables. These cannot be detached. Attached databases
235are removed using the <a href="#detach">DETACH DATABASE</a>
236statement.</p>
237
238<p>You can read from and write to an attached database and you
239can modify the schema of the attached database. This is a new
240feature of SQLite version 3.0. In SQLite 2.8, schema changes
241to attached databases were not allowed.</p>
242
243<p>You cannot create a new table with the same name as a table in
244an attached database, but you can attach a database which contains
245tables whose names are duplicates of tables in the main database. It is
246also permissible to attach the same database file multiple times.</p>
247
248<p>Tables in an attached database can be referred to using the syntax
249<i>database-name.table-name</i>. If an attached table doesn't have
250a duplicate table name in the main database, it doesn't require a
251database name prefix. When a database is attached, all of its
252tables which don't have duplicate names become the default table
253of that name. Any tables of that name attached afterwards require the table
254prefix. If the default table of a given name is detached, then
255the last table of that name attached becomes the new default.</p>
256
257<p>
258Transactions involving multiple attached databases are atomic,
259assuming that the main database is not ":memory:". If the main
260database is ":memory:" then
261transactions continue to be atomic within each individual
262database file. But if the host computer crashes in the middle
263of a COMMIT where two or more database files are updated,
264some of those files might get the changes where others
265might not.
266Atomic commit of attached databases is a new feature of SQLite version 3.0.
267In SQLite version 2.8, all commits to attached databases behaved as if
268the main database were ":memory:".
269</p>
270
271<p>There is a compile-time limit of 10 attached database files.</p>
272}
273
274
275Section {BEGIN TRANSACTION} transaction
276
277Syntax {sql-statement} {
278BEGIN [ DEFERRED | IMMEDIATE | EXCLUSIVE ] [TRANSACTION [<name>]]
279}
280Syntax {sql-statement} {
281END [TRANSACTION [<name>]]
282}
283Syntax {sql-statement} {
284COMMIT [TRANSACTION [<name>]]
285}
286Syntax {sql-statement} {
287ROLLBACK [TRANSACTION [<name>]]
288}
289
290puts {
291
292<p>
293No changes can be made to the database except within a transaction.
294Any command that changes the database (basically, any SQL command
295other than SELECT) will automatically start a transaction if
296one is not already in effect. Automatically started transactions
297are committed at the conclusion of the command.
298</p>
299
300<p>
301Transactions can be started manually using the BEGIN
302command. Such transactions usually persist until the next
303COMMIT or ROLLBACK command. But a transaction will also
304ROLLBACK if the database is closed or if an error occurs
305and the ROLLBACK conflict resolution algorithm is specified.
306See the documentation on the <a href="#conflict">ON CONFLICT</a>
307clause for additional information about the ROLLBACK
308conflict resolution algorithm.
309</p>
310
311<p>
312END TRANSACTION is an alias for COMMIT.
313</p>
314
315<p>The optional transaction name is current ignored. SQLite
316does not recognize nested transactions at this time.
317However, future versions of SQLite may be enhanced to support nested
318transactions and the transaction name would then become significant.
319Application are advised not to use the transaction name in order
320to avoid future compatibility problems.</p>
321
322<p>
323Transactions can be deferred, immediate, or exclusive.
324The default transaction behavior is deferred.
325Deferred means that no locks are acquired
326on the database until the database is first accessed. Thus with a
327deferred transaction, the BEGIN statement itself does nothing. Locks
328are not acquired until the first read or write operation. The first read
329operation against a database creates a SHARED lock and the first
330write operation creates a RESERVED lock. Because the acquisition of
331locks is deferred until they are needed, it is possible that another
332thread or process could create a separate transaction and write to
333the database after the BEGIN on the current thread has executed.
334If the transaction is immediate, then RESERVED locks
335are acquired on all databases as soon as the BEGIN command is
336executed, without waiting for the
337database to be used. After a BEGIN IMMEDIATE, you are guaranteed that
338no other thread or process will be able to write to the database or
339do a BEGIN IMMEDIATE or BEGIN EXCLUSIVE. Other processes can continue
340to read from the database, however. An exclusive transaction causes
341EXCLUSIVE locks to be acquired on all databases. After a BEGIN
342EXCLUSIVE, you are guaranteed that no other thread or process will
343be able to read or write the database until the transaction is
344complete.
345</p>
346
347<p>
348A description of the meaning of SHARED, RESERVED, and EXCLUSIVE locks
349is available <a href="lockingv3.html">separately</a>.
350</p>
351
352<p>
353The COMMIT command does not actually perform a commit until all
354pending SQL commands finish. Thus if two or more SELECT statements
355are in the middle of processing and a COMMIT is executed, the commit
356will not actually occur until all SELECT statements finish.
357</p>
358
359<p>
360An attempt to execute COMMIT might result in an SQLITE_BUSY return code.
361This indicates that another thread or process had a read lock on the database
362that prevented the database from being updated. When COMMIT fails in this
363way, the transaction remains active and the COMMIT can be retried later
364after the reader has had a chance to clear.
365</p>
366
367<h3>Response To Errors Within A Transaction</h3>
368
369<p>If certain kinds of errors occur within a transaction, the
370transaction may or may not be rolled back automatically. The
371errors that cause the behavior include:</p>
372
373<ul>
374<li> SQLITE_FULL: database or disk full
375<li> SQLITE_IOERR: disk I/O error
376<li> SQLITE_BUSY: database in use by another process
377<li> SQLITE_NOMEM: out or memory
378<li> SQLITE_INTERRUPT: processing interrupted by user request
379</ul>
380
381<p>
382For all of these errors, SQLite attempts to undo just the one statement
383it was working on and leave changes from prior statements within the
384same transaction intact and continue with the transaction. However,
385depending on the statement being evaluated and the point at which the
386error occurs, it might be necessary for SQLite to rollback and
387cancel the transaction. An application can tell which
388course of action SQLite took by using the
389<a href="capi3ref.html#sqlite3_get_autocommit">sqlite3_get_autocommit()</a>
390C-language interface.</p>
391
392<p>It is recommended that applications respond to the errors
393listed above by explicitly issuing a ROLLBACK command. If the
394transaction has already been rolled back automatically
395by the error response, then the ROLLBACK command will fail with an
396error, but no harm is caused by this.</p>
397
398<p>Future versions of SQLite may extend the list of errors which
399might cause automatic transaction rollback. Future versions of
400SQLite might change the error response. In particular, we may
401choose to simplify the interface in future versions of SQLite by
402causing the errors above to force an unconditional rollback.</p>
403}
404
405
406Section comment comment
407
408Syntax {comment} {<SQL-comment> | <C-comment>
409} {SQL-comment} {-- <single-line>
410} {C-comment} {/STAR <multiple-lines> [STAR/]
411}
412
413puts {
414<p> Comments aren't SQL commands, but can occur in SQL queries. They are
415treated as whitespace by the parser. They can begin anywhere whitespace
416can be found, including inside expressions that span multiple lines.
417</p>
418
419<p> SQL comments only extend to the end of the current line.</p>
420
421<p> C comments can span any number of lines. If there is no terminating
422delimiter, they extend to the end of the input. This is not treated as
423an error. A new SQL statement can begin on a line after a multiline
424comment ends. C comments can be embedded anywhere whitespace can occur,
425including inside expressions, and in the middle of other SQL statements.
426C comments do not nest. SQL comments inside a C comment will be ignored.
427</p>
428}
429
430
431Section COPY copy
432
433Syntax {sql-statement} {
434COPY [ OR <conflict-algorithm> ] [<database-name> .] <table-name> FROM <filename>
435[ USING DELIMITERS <delim> ]
436}
437
438puts {
439<p>The COPY command is available in SQLite version 2.8 and earlier.
440The COPY command has been removed from SQLite version 3.0 due to
441complications in trying to support it in a mixed UTF-8/16 environment.
442In version 3.0, the <a href="sqlite.html">command-line shell</a>
443contains a new command <b>.import</b> that can be used as a substitute
444for COPY.
445</p>
446
447<p>The COPY command is an extension used to load large amounts of
448data into a table. It is modeled after a similar command found
449in PostgreSQL. In fact, the SQLite COPY command is specifically
450designed to be able to read the output of the PostgreSQL dump
451utility <b>pg_dump</b> so that data can be easily transferred from
452PostgreSQL into SQLite.</p>
453
454<p>The table-name is the name of an existing table which is to
455be filled with data. The filename is a string or identifier that
456names a file from which data will be read. The filename can be
457the <b>STDIN</b> to read data from standard input.</p>
458
459<p>Each line of the input file is converted into a single record
460in the table. Columns are separated by tabs. If a tab occurs as
461data within a column, then that tab is preceded by a baskslash "\"
462character. A baskslash in the data appears as two backslashes in
463a row. The optional USING DELIMITERS clause can specify a delimiter
464other than tab.</p>
465
466<p>If a column consists of the character "\N", that column is filled
467with the value NULL.</p>
468
469<p>The optional conflict-clause allows the specification of an alternative
470constraint conflict resolution algorithm to use for this one command.
471See the section titled
472<a href="#conflict">ON CONFLICT</a> for additional information.</p>
473
474<p>When the input data source is STDIN, the input can be terminated
475by a line that contains only a baskslash and a dot:}
476puts "\"[Operator \\.]\".</p>"
477
478
479Section {CREATE INDEX} createindex
480
481Syntax {sql-statement} {
482CREATE [UNIQUE] INDEX [IF NOT EXISTS] [<database-name> .] <index-name>
483ON <table-name> ( <column-name> [, <column-name>]* )
484} {column-name} {
485<name> [ COLLATE <collation-name>] [ ASC | DESC ]
486}
487
488puts {
489<p>The CREATE INDEX command consists of the keywords "CREATE INDEX" followed
490by the name of the new index, the keyword "ON", the name of a previously
491created table that is to be indexed, and a parenthesized list of names of
492columns in the table that are used for the index key.
493Each column name can be followed by one of the "ASC" or "DESC" keywords
494to indicate sort order, but the sort order is ignored in the current
495implementation. Sorting is always done in ascending order.</p>
496
497<p>The COLLATE clause following each column name defines a collating
498sequence used for text entires in that column. The default collating
499sequence is the collating sequence defined for that column in the
500CREATE TABLE statement. Or if no collating sequence is otherwise defined,
501the built-in BINARY collating sequence is used.</p>
502
503<p>There are no arbitrary limits on the number of indices that can be
504attached to a single table, nor on the number of columns in an index.</p>
505
506<p>If the UNIQUE keyword appears between CREATE and INDEX then duplicate
507index entries are not allowed. Any attempt to insert a duplicate entry
508will result in an error.</p>
509
510<p>The exact text
511of each CREATE INDEX statement is stored in the <b>sqlite_master</b>
512or <b>sqlite_temp_master</b> table, depending on whether the table
513being indexed is temporary. Every time the database is opened,
514all CREATE INDEX statements
515are read from the <b>sqlite_master</b> table and used to regenerate
516SQLite's internal representation of the index layout.</p>
517
518<p>If the optional IF NOT EXISTS clause is present and another index
519with the same name aleady exists, then this command becomes a no-op.</p>
520
521<p>Indexes are removed with the <a href="#dropindex">DROP INDEX</a>
522command.</p>
523}
524
525
526Section {CREATE TABLE} {createtable}
527
528Syntax {sql-command} {
529CREATE [TEMP | TEMPORARY] TABLE [IF NOT EXISTS] [<database-name> .] <table-name> (
530 <column-def> [, <column-def>]*
531 [, <constraint>]*
532)
533} {sql-command} {
534CREATE [TEMP | TEMPORARY] TABLE [<database-name>.] <table-name> AS <select-statement>
535} {column-def} {
536<name> [<type>] [[CONSTRAINT <name>] <column-constraint>]*
537} {type} {
538<typename> |
539<typename> ( <number> ) |
540<typename> ( <number> , <number> )
541} {column-constraint} {
542NOT NULL [ <conflict-clause> ] |
543PRIMARY KEY [<sort-order>] [ <conflict-clause> ] [AUTOINCREMENT] |
544UNIQUE [ <conflict-clause> ] |
545CHECK ( <expr> ) |
546DEFAULT <value> |
547COLLATE <collation-name>
548} {constraint} {
549PRIMARY KEY ( <column-list> ) [ <conflict-clause> ] |
550UNIQUE ( <column-list> ) [ <conflict-clause> ] |
551CHECK ( <expr> )
552} {conflict-clause} {
553ON CONFLICT <conflict-algorithm>
554}
555
556puts {
557<p>A CREATE TABLE statement is basically the keywords "CREATE TABLE"
558followed by the name of a new table and a parenthesized list of column
559definitions and constraints. The table name can be either an identifier
560or a string. Tables names that begin with "<b>sqlite_</b>" are reserved
561for use by the engine.</p>
562
563<p>Each column definition is the name of the column followed by the
564datatype for that column, then one or more optional column constraints.
565The datatype for the column does not restrict what data may be put
566in that column.
567See <a href="datatype3.html">Datatypes In SQLite Version 3</a> for
568additional information.
569The UNIQUE constraint causes an index to be created on the specified
570columns. This index must contain unique keys.
571The COLLATE clause specifies what text <a href="datatype3.html#collation">
572collating function</a> to use when comparing text entries for the column.
573The built-in BINARY collating function is used by default.
574<p>
575The DEFAULT constraint specifies a default value to use when doing an INSERT.
576The value may be NULL, a string constant or a number. Starting with version
5773.1.0, the default value may also be one of the special case-independant
578keywords CURRENT_TIME, CURRENT_DATE or CURRENT_TIMESTAMP. If the value is
579NULL, a string constant or number, it is literally inserted into the column
580whenever an INSERT statement that does not specify a value for the column is
581executed. If the value is CURRENT_TIME, CURRENT_DATE or CURRENT_TIMESTAMP, then
582the current UTC date and/or time is inserted into the columns. For
583CURRENT_TIME, the format is HH:MM:SS. For CURRENT_DATE, YYYY-MM-DD. The format
584for CURRENT_TIMESTAMP is "YYYY-MM-DD HH:MM:SS".
585</p>
586
587<p>Specifying a PRIMARY KEY normally just creates a UNIQUE index
588on the corresponding columns. However, if primary key is on a single column
589that has datatype INTEGER, then that column is used internally
590as the actual key of the B-Tree for the table. This means that the column
591may only hold unique integer values. (Except for this one case,
592SQLite ignores the datatype specification of columns and allows
593any kind of data to be put in a column regardless of its declared
594datatype.) If a table does not have an INTEGER PRIMARY KEY column,
595then the B-Tree key will be a automatically generated integer.
596<a name="rowid"> The
597B-Tree key for a row can always be accessed using one of the
598special names "<b>ROWID</b>", "<b>OID</b>", or "<b>_ROWID_</b>".
599This is true regardless of whether or not there is an INTEGER
600PRIMARY KEY. An INTEGER PRIMARY KEY column can also include the
601keyword AUTOINCREMENT. The AUTOINCREMENT keyword modified the way
602that B-Tree keys are automatically generated. Additional detail
603on automatic B-Tree key generation is available
604<a href="autoinc.html">separately</a>.</p>
605
606<p>According to the SQL standard, PRIMARY KEY should imply NOT NULL.
607Unfortunately, due to a long-standing coding oversight, this is not
608the case in SQLite. SQLite allows NULL values
609in a PRIMARY KEY column. We could change SQLite to conform to the
610standard (and we might do so in the future), but by the time the
611oversight was discovered, SQLite was in such wide use that we feared
612breaking legacy code if we fixed the problem. So for now we have
613chosen to contain allowing NULLs in PRIMARY KEY columns.
614Developers should be aware, however, that we may change SQLite to
615conform to the SQL standard in future and should design new programs
616accordingly.</p>
617
618<p>If the "TEMP" or "TEMPORARY" keyword occurs in between "CREATE"
619and "TABLE" then the table that is created is only visible
620within that same database connection
621and is automatically deleted when
622the database connection is closed. Any indices created on a temporary table
623are also temporary. Temporary tables and indices are stored in a
624separate file distinct from the main database file.</p>
625
626<p> If a &lt;database-name&gt; is specified, then the table is created in
627the named database. It is an error to specify both a &lt;database-name&gt;
628and the TEMP keyword, unless the &lt;database-name&gt; is "temp". If no
629database name is specified, and the TEMP keyword is not present,
630the table is created in the main database.</p>
631
632<p>The optional conflict-clause following each constraint
633allows the specification of an alternative default
634constraint conflict resolution algorithm for that constraint.
635The default is abort ABORT. Different constraints within the same
636table may have different default conflict resolution algorithms.
637If an COPY, INSERT, or UPDATE command specifies a different conflict
638resolution algorithm, then that algorithm is used in place of the
639default algorithm specified in the CREATE TABLE statement.
640See the section titled
641<a href="#conflict">ON CONFLICT</a> for additional information.</p>
642
643<p>CHECK constraints are supported as of version 3.3.0. Prior
644to version 3.3.0, CHECK constraints were parsed but not enforced.</p>
645
646<p>There are no arbitrary limits on the number
647of columns or on the number of constraints in a table.
648The total amount of data in a single row is limited to about
6491 megabytes in version 2.8. In version 3.0 there is no arbitrary
650limit on the amount of data in a row.</p>
651
652
653<p>The CREATE TABLE AS form defines the table to be
654the result set of a query. The names of the table columns are
655the names of the columns in the result.</p>
656
657<p>The exact text
658of each CREATE TABLE statement is stored in the <b>sqlite_master</b>
659table. Every time the database is opened, all CREATE TABLE statements
660are read from the <b>sqlite_master</b> table and used to regenerate
661SQLite's internal representation of the table layout.
662If the original command was a CREATE TABLE AS then then an equivalent
663CREATE TABLE statement is synthesized and store in <b>sqlite_master</b>
664in place of the original command.
665The text of CREATE TEMPORARY TABLE statements are stored in the
666<b>sqlite_temp_master</b> table.
667</p>
668
669<p>If the optional IF NOT EXISTS clause is present and another table
670with the same name aleady exists, then this command becomes a no-op.</p>
671
672<p>Tables are removed using the <a href="#droptable">DROP TABLE</a>
673statement. </p>
674}
675
676
677Section {CREATE TRIGGER} createtrigger
678
679Syntax {sql-statement} {
680CREATE [TEMP | TEMPORARY] TRIGGER [IF NOT EXISTS] <trigger-name> [ BEFORE | AFTER ]
681<database-event> ON [<database-name> .] <table-name>
682<trigger-action>
683}
684
685Syntax {sql-statement} {
686CREATE [TEMP | TEMPORARY] TRIGGER [IF NOT EXISTS] <trigger-name> INSTEAD OF
687<database-event> ON [<database-name> .] <view-name>
688<trigger-action>
689}
690
691Syntax {database-event} {
692DELETE |
693INSERT |
694UPDATE |
695UPDATE OF <column-list>
696}
697
698Syntax {trigger-action} {
699[ FOR EACH ROW ] [ WHEN <expression> ]
700BEGIN
701 <trigger-step> ; [ <trigger-step> ; ]*
702END
703}
704
705Syntax {trigger-step} {
706<update-statement> | <insert-statement> |
707<delete-statement> | <select-statement>
708}
709
710puts {
711<p>The CREATE TRIGGER statement is used to add triggers to the
712database schema. Triggers are database operations (the <i>trigger-action</i>)
713that are automatically performed when a specified database event (the
714<i>database-event</i>) occurs. </p>
715
716<p>A trigger may be specified to fire whenever a DELETE, INSERT or UPDATE of a
717particular database table occurs, or whenever an UPDATE of one or more
718specified columns of a table are updated.</p>
719
720<p>At this time SQLite supports only FOR EACH ROW triggers, not FOR EACH
721STATEMENT triggers. Hence explicitly specifying FOR EACH ROW is optional. FOR
722EACH ROW implies that the SQL statements specified as <i>trigger-steps</i>
723may be executed (depending on the WHEN clause) for each database row being
724inserted, updated or deleted by the statement causing the trigger to fire.</p>
725
726<p>Both the WHEN clause and the <i>trigger-steps</i> may access elements of
727the row being inserted, deleted or updated using references of the form
728"NEW.<i>column-name</i>" and "OLD.<i>column-name</i>", where
729<i>column-name</i> is the name of a column from the table that the trigger
730is associated with. OLD and NEW references may only be used in triggers on
731<i>trigger-event</i>s for which they are relevant, as follows:</p>
732
733<table border=0 cellpadding=10>
734<tr>
735<td valign="top" align="right" width=120><i>INSERT</i></td>
736<td valign="top">NEW references are valid</td>
737</tr>
738<tr>
739<td valign="top" align="right" width=120><i>UPDATE</i></td>
740<td valign="top">NEW and OLD references are valid</td>
741</tr>
742<tr>
743<td valign="top" align="right" width=120><i>DELETE</i></td>
744<td valign="top">OLD references are valid</td>
745</tr>
746</table>
747</p>
748
749<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>
750
751<p>The specified <i>trigger-time</i> determines when the <i>trigger-steps</i>
752will be executed relative to the insertion, modification or removal of the
753associated row.</p>
754
755<p>An ON CONFLICT clause may be specified as part of an UPDATE or INSERT
756<i>trigger-step</i>. However if an ON CONFLICT clause is specified as part of
757the statement causing the trigger to fire, then this conflict handling
758policy is used instead.</p>
759
760<p>Triggers are automatically dropped when the table that they are
761associated with is dropped.</p>
762
763<p>Triggers may be created on views, as well as ordinary tables, by specifying
764INSTEAD OF in the CREATE TRIGGER statement. If one or more ON INSERT, ON DELETE
765or ON UPDATE triggers are defined on a view, then it is not an error to execute
766an INSERT, DELETE or UPDATE statement on the view, respectively. Thereafter,
767executing an INSERT, DELETE or UPDATE on the view causes the associated
768 triggers to fire. The real tables underlying the view are not modified
769 (except possibly explicitly, by a trigger program).</p>
770
771<p><b>Example:</b></p>
772
773<p>Assuming that customer records are stored in the "customers" table, and
774that order records are stored in the "orders" table, the following trigger
775ensures that all associated orders are redirected when a customer changes
776his or her address:</p>
777}
778Example {
779CREATE TRIGGER update_customer_address UPDATE OF address ON customers
780 BEGIN
781 UPDATE orders SET address = new.address WHERE customer_name = old.name;
782 END;
783}
784puts {
785<p>With this trigger installed, executing the statement:</p>
786}
787
788Example {
789UPDATE customers SET address = '1 Main St.' WHERE name = 'Jack Jones';
790}
791puts {
792<p>causes the following to be automatically executed:</p>
793}
794Example {
795UPDATE orders SET address = '1 Main St.' WHERE customer_name = 'Jack Jones';
796}
797
798puts {
799<p>Note that currently, triggers may behave oddly when created on tables
800 with INTEGER PRIMARY KEY fields. If a BEFORE trigger program modifies the
801 INTEGER PRIMARY KEY field of a row that will be subsequently updated by the
802 statement that causes the trigger to fire, then the update may not occur.
803 The workaround is to declare the table with a PRIMARY KEY column instead
804 of an INTEGER PRIMARY KEY column.</p>
805}
806
807puts {
808<p>A special SQL function RAISE() may be used within a trigger-program, with the following syntax</p>
809}
810Syntax {raise-function} {
811RAISE ( ABORT, <error-message> ) |
812RAISE ( FAIL, <error-message> ) |
813RAISE ( ROLLBACK, <error-message> ) |
814RAISE ( IGNORE )
815}
816puts {
817<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
818 ROLLBACK) and the current query terminates. An error code of SQLITE_CONSTRAINT is returned to the user, along with the specified error message.</p>
819
820<p>When RAISE(IGNORE) is called, the remainder of the current trigger program,
821the statement that caused the trigger program to execute and any subsequent
822 trigger programs that would of been executed are abandoned. No database
823 changes are rolled back. If the statement that caused the trigger program
824 to execute is itself part of a trigger program, then that trigger program
825 resumes execution at the beginning of the next step.
826</p>
827
828<p>Triggers are removed using the <a href="#droptrigger">DROP TRIGGER</a>
829statement.</p>
830}
831
832
833Section {CREATE VIEW} {createview}
834
835Syntax {sql-command} {
836CREATE [TEMP | TEMPORARY] VIEW [IF NOT EXISTS] [<database-name>.] <view-name> AS <select-statement>
837}
838
839puts {
840<p>The CREATE VIEW command assigns a name to a pre-packaged
841<a href="#select">SELECT</a>
842statement. Once the view is created, it can be used in the FROM clause
843of another SELECT in place of a table name.
844</p>
845
846<p>If the "TEMP" or "TEMPORARY" keyword occurs in between "CREATE"
847and "VIEW" then the view that is created is only visible to the
848process that opened the database and is automatically deleted when
849the database is closed.</p>
850
851<p> If a &lt;database-name&gt; is specified, then the view is created in
852the named database. It is an error to specify both a &lt;database-name&gt;
853and the TEMP keyword, unless the &lt;database-name&gt; is "temp". If no
854database name is specified, and the TEMP keyword is not present,
855the table is created in the main database.</p>
856
857<p>You cannot COPY, DELETE, INSERT or UPDATE a view. Views are read-only
858in SQLite. However, in many cases you can use a <a href="#createtrigger">
859TRIGGER</a> on the view to accomplish the same thing. Views are removed
860with the <a href="#dropview">DROP VIEW</a>
861command.</p>
862}
863
864Section {CREATE VIRTUAL TABLE} {createvtab}
865
866Syntax {sql-command} {
867CREATE VIRTUAL TABLE [<database-name> .] <table-name> USING <module-name> [( <arguments> )]
868}
869
870puts {
871<p>A virtual table is an interface to an external storage or computation
872engine that appears to be a table but does not actually store information
873in the database file.</p>
874
875<p>In general, you can do anything with a virtual table that can be done
876with an ordinary table, except that you cannot create triggers on a
877virtual table. Some virtual table implementations might impose additional
878restrictions. For example, many virtual tables are read-only.</p>
879
880<p>The &lt;module-name&gt; is the name of an object that implements
881the virtual table. The &lt;module-name&gt; must be registered with
882the SQLite database connection using
883<a href="capi3ref.html#sqlite3_create_module">sqlite3_create_module</a>
884prior to issuing the CREATE VIRTUAL TABLE statement.
885The module takes zero or more comma-separated arguments.
886The arguments can be just about any text as long as it has balanced
887parentheses. The argument syntax is sufficiently general that the
888arguments can be made to appear as column definitions in a traditional
889<a href="#createtable">CREATE TABLE</a> statement.
890SQLite passes the module arguments directly
891to the module without any interpretation. It is the responsibility
892of the module implementation to parse and interpret its own arguments.</p>
893
894<p>A virtual table is destroyed using the ordinary
895<a href="#droptable">DROP TABLE</a> statement. There is no
896DROP VIRTUAL TABLE statement.</p>
897}
898
899Section DELETE delete
900
901Syntax {sql-statement} {
902DELETE FROM [<database-name> .] <table-name> [WHERE <expr>]
903}
904
905puts {
906<p>The DELETE command is used to remove records from a table.
907The command consists of the "DELETE FROM" keywords followed by
908the name of the table from which records are to be removed.
909</p>
910
911<p>Without a WHERE clause, all rows of the table are removed.
912If a WHERE clause is supplied, then only those rows that match
913the expression are removed.</p>
914}
915
916
917Section {DETACH DATABASE} detach
918
919Syntax {sql-command} {
920DETACH [DATABASE] <database-name>
921}
922
923puts {
924<p>This statement detaches an additional database connection previously
925attached using the <a href="#attach">ATTACH DATABASE</a> statement. It
926is possible to have the same database file attached multiple times using
927different names, and detaching one connection to a file will leave the
928others intact.</p>
929
930<p>This statement will fail if SQLite is in the middle of a transaction.</p>
931}
932
933
934Section {DROP INDEX} dropindex
935
936Syntax {sql-command} {
937DROP INDEX [IF EXISTS] [<database-name> .] <index-name>
938}
939
940puts {
941<p>The DROP INDEX statement removes an index added
942with the <a href="#createindex">
943CREATE INDEX</a> statement. The index named is completely removed from
944the disk. The only way to recover the index is to reenter the
945appropriate CREATE INDEX command.</p>
946
947<p>The DROP INDEX statement does not reduce the size of the database
948file in the default mode.
949Empty space in the database is retained for later INSERTs. To
950remove free space in the database, use the <a href="#vacuum">VACUUM</a>
951command. If AUTOVACUUM mode is enabled for a database then space
952will be freed automatically by DROP INDEX.</p>
953}
954
955
956Section {DROP TABLE} droptable
957
958Syntax {sql-command} {
959DROP TABLE [IF EXISTS] [<database-name>.] <table-name>
960}
961
962puts {
963<p>The DROP TABLE statement removes a table added with the <a href=
964"#createtable">CREATE TABLE</a> statement. The name specified is the
965table name. It is completely removed from the database schema and the
966disk file. The table can not be recovered. All indices associated
967with the table are also deleted.</p>
968
969<p>The DROP TABLE statement does not reduce the size of the database
970file in the default mode. Empty space in the database is retained for
971later INSERTs. To
972remove free space in the database, use the <a href="#vacuum">VACUUM</a>
973command. If AUTOVACUUM mode is enabled for a database then space
974will be freed automatically by DROP TABLE.</p>
975
976<p>The optional IF EXISTS clause suppresses the error that would normally
977result if the table does not exist.</p>
978}
979
980
981Section {DROP TRIGGER} droptrigger
982Syntax {sql-statement} {
983DROP TRIGGER [IF EXISTS] [<database-name> .] <trigger-name>
984}
985puts {
986<p>The DROP TRIGGER statement removes a trigger created by the
987<a href="#createtrigger">CREATE TRIGGER</a> statement. The trigger is
988deleted from the database schema. Note that triggers are automatically
989dropped when the associated table is dropped.</p>
990}
991
992
993Section {DROP VIEW} dropview
994
995Syntax {sql-command} {
996DROP VIEW [IF EXISTS] <view-name>
997}
998
999puts {
1000<p>The DROP VIEW statement removes a view created by the <a href=
1001"#createview">CREATE VIEW</a> statement. The name specified is the
1002view name. It is removed from the database schema, but no actual data
1003in the underlying base tables is modified.</p>
1004}
1005
1006
1007Section EXPLAIN explain
1008
1009Syntax {sql-statement} {
1010EXPLAIN <sql-statement>
1011}
1012
1013puts {
1014<p>The EXPLAIN command modifier is a non-standard extension. The
1015idea comes from a similar command found in PostgreSQL, but the operation
1016is completely different.</p>
1017
1018<p>If the EXPLAIN keyword appears before any other SQLite SQL command
1019then instead of actually executing the command, the SQLite library will
1020report back the sequence of virtual machine instructions it would have
1021used to execute the command had the EXPLAIN keyword not been present.
1022For additional information about virtual machine instructions see
1023the <a href="arch.html">architecture description</a> or the documentation
1024on <a href="opcode.html">available opcodes</a> for the virtual machine.</p>
1025}
1026
1027
1028Section expression expr
1029
1030Syntax {expr} {
1031<expr> <binary-op> <expr> |
1032<expr> [NOT] <like-op> <expr> [ESCAPE <expr>] |
1033<unary-op> <expr> |
1034( <expr> ) |
1035<column-name> |
1036<table-name> . <column-name> |
1037<database-name> . <table-name> . <column-name> |
1038<literal-value> |
1039<parameter> |
1040<function-name> ( <expr-list> | STAR ) |
1041<expr> ISNULL |
1042<expr> NOTNULL |
1043<expr> [NOT] BETWEEN <expr> AND <expr> |
1044<expr> [NOT] IN ( <value-list> ) |
1045<expr> [NOT] IN ( <select-statement> ) |
1046<expr> [NOT] IN [<database-name> .] <table-name> |
1047[EXISTS] ( <select-statement> ) |
1048CASE [<expr>] LP WHEN <expr> THEN <expr> RPPLUS [ELSE <expr>] END |
1049CAST ( <expr> AS <type> ) |
1050<expr> COLLATE <collation-name>
1051} {like-op} {
1052LIKE | GLOB | REGEXP | MATCH
1053}
1054
1055puts {
1056<p>This section is different from the others. Most other sections of
1057this document talks about a particular SQL command. This section does
1058not talk about a standalone command but about "expressions" which are
1059subcomponents of most other commands.</p>
1060
1061<p>SQLite understands the following binary operators, in order from
1062highest to lowest precedence:</p>
1063
1064<blockquote><pre>
1065<font color="#2c2cf0"><big>||
1066* / %
1067+ -
1068&lt;&lt; &gt;&gt; &amp; |
1069&lt; &lt;= &gt; &gt;=
1070= == != &lt;&gt; </big>IN
1071AND
1072OR</font>
1073</pre></blockquote>
1074
1075<p>Supported unary prefix operators are these:</p>
1076
1077<blockquote><pre>
1078<font color="#2c2cf0"><big>- + ! ~ NOT</big></font>
1079</pre></blockquote>
1080
1081<p>The COLLATE operator can be thought of as a unary postfix
1082operator. The COLLATE operator has the highest precedence.
1083It always binds more tightly than any prefix unary operator or
1084any binary operator.</p>
1085
1086<p>The unary operator [Operator +] is a no-op. It can be applied
1087to strings, numbers, or blobs and it always gives as its result the
1088value of the operand.</p>
1089
1090<p>Note that there are two variations of the equals and not equals
1091operators. Equals can be either}
1092puts "[Operator =] or [Operator ==].
1093The non-equals operator can be either
1094[Operator !=] or [Operator {&lt;&gt;}].
1095The [Operator ||] operator is \"concatenate\" - it joins together
1096the two strings of its operands.
1097The operator [Operator %] outputs the remainder of its left
1098operand modulo its right operand.</p>
1099
1100<p>The result of any binary operator is a numeric value, except
1101for the [Operator ||] concatenation operator which gives a string
1102result.</p>"
1103
1104puts {
1105
1106<a name="literal_value"></a>
1107<p>
1108A literal value is an integer number or a floating point number.
1109Scientific notation is supported. The "." character is always used
1110as the decimal point even if the locale setting specifies "," for
1111this role - the use of "," for the decimal point would result in
1112syntactic ambiguity. A string constant is formed by enclosing the
1113string in single quotes ('). A single quote within the string can
1114be encoded by putting two single quotes in a row - as in Pascal.
1115C-style escapes using the backslash character are not supported because
1116they are not standard SQL.
1117BLOB literals are string literals containing hexadecimal data and
1118preceded by a single "x" or "X" character. For example:</p>
1119
1120<blockquote><pre>
1121X'53514C697465'
1122</pre></blockquote>
1123
1124<p>
1125A literal value can also be the token "NULL".
1126</p>
1127
1128<p>
1129A parameter specifies a placeholder in the expression for a literal
1130value that is filled in at runtime using the
1131<a href="capi3ref.html#sqlite3_bind_int">sqlite3_bind</a> API.
1132Parameters can take several forms:
1133</p
1134
1135<blockquote>
1136<table class="pdf_functions">
1137<tr>
1138<td align="right" valign="top"><b>?</b><i>NNN</i></td><td width="20"></td>
1139<td>A question mark followed by a number <i>NNN</i> holds a spot for the
1140NNN-th parameter. NNN must be between 1 and 999.</td>
1141</tr>
1142<tr>
1143<td align="right" valign="top"><b>?</b></td><td width="20"></td>
1144<td>A question mark that is not followed by a number holds a spot for
1145the next unused parameter.</td>
1146</tr>
1147<tr>
1148<td align="right" valign="top"><b>:</b><i>AAAA</i></td><td width="20"></td>
1149<td>A colon followed by an identifier name holds a spot for a named
1150parameter with the name AAAA. Named parameters are also numbered.
1151The number assigned is the next unused number. To avoid confusion,
1152it is best to avoid mixing named and numbered parameters.</td>
1153</tr>
1154<tr>
1155<td align="right" valign="top"><b>@</b><i>AAAA</i></td><td width="20"></td>
1156<td>An "at" sign works exactly like a colon.</td>
1157</tr>
1158<tr>
1159<td align="right" valign="top"><b>$</b><i>AAAA</i></td><td width="20"></td>
1160<td>A dollar-sign followed by an identifier name also holds a spot for a named
1161parameter with the name AAAA. The identifier name in this case can include
1162one or more occurances of "::" and a suffix enclosed in "(...)" containing
1163any text at all. This syntax is the form of a variable name in the Tcl
1164programming language.</td>
1165</tr>
1166</table>
1167</blockquote>
1168
1169<p>Parameters that are not assigned values using
1170<a href="capi3ref.html#sqlite3_bind_int">sqlite3_bind</a> are treated
1171as NULL.</p>
1172
1173<a name="like"></a>
1174<p>The LIKE operator does a pattern matching comparison. The operand
1175to the right contains the pattern, the left hand operand contains the
1176string to match against the pattern.
1177}
1178puts "A percent symbol [Operator %] in the pattern matches any
1179sequence of zero or more characters in the string. An underscore
1180[Operator _] in the pattern matches any single character in the
1181string. Any other character matches itself or it's lower/upper case
1182equivalent (i.e. case-insensitive matching). (A bug: SQLite only
1183understands upper/lower case for 7-bit Latin characters. Hence the
1184LIKE operator is case sensitive for 8-bit iso8859 characters or UTF-8
1185characters. For example, the expression <b>'a'&nbsp;LIKE&nbsp;'A'</b>
1186is TRUE but <b>'&aelig;'&nbsp;LIKE&nbsp;'&AElig;'</b> is FALSE.).</p>"
1187
1188puts {
1189<p>If the optional ESCAPE clause is present, then the expression
1190following the ESCAPE keyword must evaluate to a string consisting of
1191a single character. This character may be used in the LIKE pattern
1192to include literal percent or underscore characters. The escape
1193character followed by a percent symbol, underscore or itself matches a
1194literal percent symbol, underscore or escape character in the string,
1195respectively. The infix LIKE operator is implemented by calling the
1196user function <a href="#likeFunc"> like(<i>X</i>,<i>Y</i>)</a>.</p>
1197}
1198
1199puts {
1200The LIKE operator is not case sensitive and will match upper case
1201characters on one side against lower case characters on the other.
1202(A bug: SQLite only understands upper/lower case for 7-bit Latin
1203characters. Hence the LIKE operator is case sensitive for 8-bit
1204iso8859 characters or UTF-8 characters. For example, the expression
1205<b>'a'&nbsp;LIKE&nbsp;'A'</b> is TRUE but
1206<b>'&aelig;'&nbsp;LIKE&nbsp;'&AElig;'</b> is FALSE.).</p>
1207
1208<p>The infix LIKE
1209operator is implemented by calling the user function <a href="#likeFunc">
1210like(<i>X</i>,<i>Y</i>)</a>. If an ESCAPE clause is present, it adds
1211a third parameter to the function call. If the functionality of LIKE can be
1212overridden by defining an alternative implementation of the
1213like() SQL function.</p>
1214</p>
1215
1216<a name="glob"></a>
1217<p>The GLOB operator is similar to LIKE but uses the Unix
1218file globbing syntax for its wildcards. Also, GLOB is case
1219sensitive, unlike LIKE. Both GLOB and LIKE may be preceded by
1220the NOT keyword to invert the sense of the test. The infix GLOB
1221operator is implemented by calling the user function <a href="#globFunc">
1222glob(<i>X</i>,<i>Y</i>)</a> and can be modified by overriding
1223that function.</p>
1224
1225<a name="regexp"></a>
1226<p>The REGEXP operator is a special syntax for the regexp()
1227user function. No regexp() user function is defined by default
1228and so use of the REGEXP operator will normally result in an
1229error message. If a user-defined function named "regexp"
1230is added at run-time, that function will be called in order
1231to implement the REGEXP operator.</p>
1232
1233<a name="match"></a>
1234<p>The MATCH operator is a special syntax for the match()
1235user function. The default match() function implementation
1236raises and exception and is not really useful for anything.
1237But extensions can override the match() function with more
1238helpful logic.</p>
1239
1240<p>A column name can be any of the names defined in the CREATE TABLE
1241statement or one of the following special identifiers: "<b>ROWID</b>",
1242"<b>OID</b>", or "<b>_ROWID_</b>".
1243These special identifiers all describe the
1244unique integer key (the "row key") associated with every
1245row of every table.
1246The special identifiers only refer to the row key if the CREATE TABLE
1247statement does not define a real column with the same name. Row keys
1248act like read-only columns. A row key can be used anywhere a regular
1249column can be used, except that you cannot change the value
1250of a row key in an UPDATE or INSERT statement.
1251"SELECT * ..." does not return the row key.</p>
1252
1253<p>SELECT statements can appear in expressions as either the
1254right-hand operand of the IN operator, as a scalar quantity, or
1255as the operand of an EXISTS operator.
1256As a scalar quantity or the operand of an IN operator,
1257the SELECT should have only a single column in its
1258result. Compound SELECTs (connected with keywords like UNION or
1259EXCEPT) are allowed.
1260With the EXISTS operator, the columns in the result set of the SELECT are
1261ignored and the expression returns TRUE if one or more rows exist
1262and FALSE if the result set is empty.
1263If no terms in the SELECT expression refer to value in the containing
1264query, then the expression is evaluated once prior to any other
1265processing and the result is reused as necessary. If the SELECT expression
1266does contain variables from the outer query, then the SELECT is reevaluated
1267every time it is needed.</p>
1268
1269<p>When a SELECT is the right operand of the IN operator, the IN
1270operator returns TRUE if the result of the left operand is any of
1271the values generated by the select. The IN operator may be preceded
1272by the NOT keyword to invert the sense of the test.</p>
1273
1274<p>When a SELECT appears within an expression but is not the right
1275operand of an IN operator, then the first row of the result of the
1276SELECT becomes the value used in the expression. If the SELECT yields
1277more than one result row, all rows after the first are ignored. If
1278the SELECT yields no rows, then the value of the SELECT is NULL.</p>
1279
1280<p>A CAST expression changes the datatype of the <expr> into the
1281type specified by &lt;type&gt;.
1282&lt;type&gt; can be any non-empty type name that is valid
1283for the type in a column definition of a CREATE TABLE statement.</p>
1284
1285<p>Both simple and aggregate functions are supported. A simple
1286function can be used in any expression. Simple functions return
1287a result immediately based on their inputs. Aggregate functions
1288may only be used in a SELECT statement. Aggregate functions compute
1289their result across all rows of the result set.</p>
1290
1291<a name="corefunctions"></a>
1292<b>Core Functions</b>
1293
1294<p>The core functions shown below are available by default. Additional
1295functions may be written in C and added to the database engine using
1296the <a href="capi3ref.html#cfunc">sqlite3_create_function()</a>
1297API.</p>
1298
1299<table border=0 cellpadding=10 class="pdf_functions">
1300<tr>
1301<td valign="top" align="right" width=120>abs(<i>X</i>)</td>
1302<td valign="top">Return the absolute value of argument <i>X</i>.</td>
1303</tr>
1304
1305<tr>
1306<td valign="top" align="right">coalesce(<i>X</i>,<i>Y</i>,...)</td>
1307<td valign="top">Return a copy of the first non-NULL argument. If
1308all arguments are NULL then NULL is returned. There must be at least
13092 arguments.</td>
1310</tr>
1311
1312<tr>
1313<td valign="top" align="right">
1314<a name="globFunc"></a>
1315glob(<i>X</i>,<i>Y</i>)</td>
1316<td valign="top">This function is used to implement the
1317"<b>X GLOB Y</b>" syntax of SQLite. The
1318<a href="capi3ref.html#sqlite3_create_function">sqlite3_create_function()</a>
1319interface can
1320be used to override this function and thereby change the operation
1321of the <a href="#globFunc">GLOB</a> operator.</td>
1322</tr>
1323
1324<tr>
1325<td valign="top" align="right">ifnull(<i>X</i>,<i>Y</i>)</td>
1326<td valign="top">Return a copy of the first non-NULL argument. If
1327both arguments are NULL then NULL is returned. This behaves the same as
1328<b>coalesce()</b> above.</td>
1329</tr>
1330
1331<tr>
1332<td valign="top" align="right">
1333<a name="hexFunc">
1334hex(<i>X</i>)</td>
1335<td valign="top">The argument is interpreted as a BLOB. The result
1336is a hexadecimal rendering of the content of that blob.</td>
1337</tr>
1338
1339<tr>
1340<td valign="top" align="right">last_insert_rowid()</td>
1341<td valign="top">Return the <a href="lang_createtable.html#rowid">ROWID</a>
1342of the last row insert from this
1343connection to the database. This is the same value that would be returned
1344from the <b>sqlite_last_insert_rowid()</b> API function.</td>
1345</tr>
1346
1347<tr>
1348<td valign="top" align="right">length(<i>X</i>)</td>
1349<td valign="top">Return the string length of <i>X</i> in characters.
1350If SQLite is configured to support UTF-8, then the number of UTF-8
1351characters is returned, not the number of bytes.</td>
1352</tr>
1353
1354<tr>
1355<td valign="top" align="right">
1356<a name="likeFunc"></a>
1357like(<i>X</i>,<i>Y</i>)<br>
1358like(<i>X</i>,<i>Y</i>,<i>Z</i>)</td>
1359<td valign="top">
1360This function is used to implement the "<b>X LIKE Y [ESCAPE Z]</b>"
1361syntax of SQL. If the optional ESCAPE clause is present, then the
1362user-function is invoked with three arguments. Otherwise, it is
1363invoked with two arguments only. The
1364<a href="capi3ref.html#sqlite3_create_function">
1365sqlite_create_function()</a> interface can be used to override this
1366function and thereby change the operation of the <a
1367href= "#like">LIKE</a> operator. When doing this, it may be important
1368to override both the two and three argument versions of the like()
1369function. Otherwise, different code may be called to implement the
1370LIKE operator depending on whether or not an ESCAPE clause was
1371specified.</td>
1372</tr>
1373
1374<tr>
1375<td valign="top" align="right">load_extension(<i>X</i>)<br>
1376load_extension(<i>X</i>,<i>Y</i>)</td>
1377<td valign="top">Load SQLite extensions out of the shared library
1378file named <i>X</i> using the entry point <i>Y</i>. The result
1379is a NULL. If <i>Y</i> is omitted then the default entry point
1380of <b>sqlite3_extension_init</b> is used. This function raises
1381an exception if the extension fails to load or initialize correctly.
1382
1383<p>This function will fail if the extension attempts to modify
1384or delete a SQL function or collating sequence. The
1385extension can add new functions or collating sequences, but cannot
1386modify or delete existing functions or collating sequences because
1387those functions and/or collating sequences might be used elsewhere
1388in the currently running SQL statement. To load an extension that
1389changes or deletes functions or collating sequences, use the
1390<a href="capi3ref.html#sqlite3_load_extension">sqlite3_load_extension()</a>
1391C-language API.</p>
1392</tr>
1393
1394<tr>
1395<td valign="top" align="right">lower(<i>X</i>)</td>
1396<td valign="top">Return a copy of string <i>X</i> will all characters
1397converted to lower case. The C library <b>tolower()</b> routine is used
1398for the conversion, which means that this function might not
1399work correctly on UTF-8 characters.</td>
1400</tr>
1401
1402<tr>
1403<td valign="top" align="right">
1404<a name="ltrimFunc">
1405ltrim(<i>X</i>)<br>ltrim(<i>X</i>,<i>Y</i>)</td>
1406<td valign="top">Return a string formed by removing any and all
1407characters that appear in <i>Y</i> from the left side of <i>X</i>.
1408If the <i>Y</i> argument is omitted, spaces are removed.</td>
1409</tr>
1410
1411
1412<tr>
1413<td valign="top" align="right">max(<i>X</i>,<i>Y</i>,...)</td>
1414<td valign="top">Return the argument with the maximum value. Arguments
1415may be strings in addition to numbers. The maximum value is determined
1416by the usual sort order. Note that <b>max()</b> is a simple function when
1417it has 2 or more arguments but converts to an aggregate function if given
1418only a single argument.</td>
1419</tr>
1420
1421<tr>
1422<td valign="top" align="right">min(<i>X</i>,<i>Y</i>,...)</td>
1423<td valign="top">Return the argument with the minimum value. Arguments
1424may be strings in addition to numbers. The minimum value is determined
1425by the usual sort order. Note that <b>min()</b> is a simple function when
1426it has 2 or more arguments but converts to an aggregate function if given
1427only a single argument.</td>
1428</tr>
1429
1430<tr>
1431<td valign="top" align="right">nullif(<i>X</i>,<i>Y</i>)</td>
1432<td valign="top">Return the first argument if the arguments are different,
1433otherwise return NULL.</td>
1434</tr>
1435
1436<tr>
1437<td valign="top" align="right">quote(<i>X</i>)</td>
1438<td valign="top">This routine returns a string which is the value of
1439its argument suitable for inclusion into another SQL statement.
1440Strings are surrounded by single-quotes with escapes on interior quotes
1441as needed. BLOBs are encoded as hexadecimal literals.
1442The current implementation of VACUUM uses this function. The function
1443is also useful when writing triggers to implement undo/redo functionality.
1444</td>
1445</tr>
1446
1447<tr>
1448<td valign="top" align="right">random(*)</td>
1449<td valign="top">Return a pseudo-random integer
1450between -9223372036854775808 and +9223372036854775807.</td>
1451</tr>
1452
1453<tr>
1454<td valign="top" align="right">
1455<a name="replaceFunc">
1456replace(<i>X</i>,<i>Y</i>,<i>Z</i>)</td>
1457<td valign="top">Return a string formed by substituting string <i>Z</i> for
1458every occurrance of string <i>Y</i> in string <i>X</i>. The BINARY
1459collating sequence is used for comparisons.</td>
1460</tr>
1461
1462<tr>
1463<td valign="top" align="right">
1464<a name="randomblobFunc">
1465randomblob(<i>N</i>)</td>
1466<td valign="top">Return a <i>N</i>-byte blob containing pseudo-random bytes.
1467<i>N</i> should be a postive integer.</td>
1468</tr>
1469
1470<tr>
1471<td valign="top" align="right">round(<i>X</i>)<br>round(<i>X</i>,<i>Y</i>)</td>
1472<td valign="top">Round off the number <i>X</i> to <i>Y</i> digits to the
1473right of the decimal point. If the <i>Y</i> argument is omitted, 0 is
1474assumed.</td>
1475</tr>
1476
1477<tr>
1478<td valign="top" align="right">
1479<a name="rtrimFunc">
1480rtrim(<i>X</i>)<br>rtrim(<i>X</i>,<i>Y</i>)</td>
1481<td valign="top">Return a string formed by removing any and all
1482characters that appear in <i>Y</i> from the right side of <i>X</i>.
1483If the <i>Y</i> argument is omitted, spaces are removed.</td>
1484</tr>
1485
1486<tr>
1487<td valign="top" align="right">soundex(<i>X</i>)</td>
1488<td valign="top">Compute the soundex encoding of the string <i>X</i>.
1489The string "?000" is returned if the argument is NULL.
1490This function is omitted from SQLite by default.
1491It is only available the -DSQLITE_SOUNDEX=1 compiler option
1492is used when SQLite is built.</td>
1493</tr>
1494
1495<tr>
1496<td valign="top" align="right">sqlite_version(*)</td>
1497<td valign="top">Return the version string for the SQLite library
1498that is running. Example: "2.8.0"</td>
1499</tr>
1500
1501<tr>
1502<td valign="top" align="right">substr(<i>X</i>,<i>Y</i>,<i>Z</i>)</td>
1503<td valign="top">Return a substring of input string <i>X</i> that begins
1504with the <i>Y</i>-th character and which is <i>Z</i> characters long.
1505The left-most character of <i>X</i> is number 1. If <i>Y</i> is negative
1506the the first character of the substring is found by counting from the
1507right rather than the left. If <i>X</i> is string
1508then characters indices refer to actual UTF-8 characters. If
1509<i>X</i> is a BLOB then the indices refer to bytes.</td>
1510</tr>
1511
1512<tr>
1513<td valign="top" align="right">
1514<a name="trimFunc">
1515trim(<i>X</i>)<br>trim(<i>X</i>,<i>Y</i>)</td>
1516<td valign="top">Return a string formed by removing any and all
1517characters that appear in <i>Y</i> from both ends of <i>X</i>.
1518If the <i>Y</i> argument is omitted, spaces are removed.</td>
1519</tr>
1520
1521
1522<tr>
1523<td valign="top" align="right">typeof(<i>X</i>)</td>
1524<td valign="top">Return the type of the expression <i>X</i>. The only
1525return values are "null", "integer", "real", "text", and "blob".
1526SQLite's type handling is
1527explained in <a href="datatype3.html">Datatypes in SQLite Version 3</a>.</td>
1528</tr>
1529
1530<tr>
1531<td valign="top" align="right">upper(<i>X</i>)</td>
1532<td valign="top">Return a copy of input string <i>X</i> converted to all
1533upper-case letters. The implementation of this function uses the C library
1534routine <b>toupper()</b> which means it may not work correctly on
1535UTF-8 strings.</td>
1536</tr>
1537
1538<tr>
1539<td valign="top" align="right">zeroblob(<i>N</i>)</td>
1540<td valign="top"><a name="zeroblob">
1541Return a BLOB consisting of N bytes of 0x00. SQLite
1542manages these zeroblobs very efficiently. Zeroblobs can be used to
1543reserve space for a BLOB that is later written using
1544<a href="capi3ref.html#sqlite3_blob_open">incremental BLOB I/O</a>.</td>
1545</tr>
1546
1547</table>
1548
1549<b>Date And Time Functions</b>
1550
1551<p>Date and time functions are documented in the
1552<a href="http://www.sqlite.org/cvstrac/wiki?p=DateAndTimeFunctions">
1553SQLite Wiki</a>.</p>
1554
1555<a name="aggregatefunctions"></a>
1556<b>Aggregate Functions</b>
1557
1558<p>
1559The aggregate functions shown below are available by default. Additional
1560aggregate functions written in C may be added using the
1561<a href="capi3ref.html#sqlite3_create_function">sqlite3_create_function()</a>
1562API.</p>
1563
1564<p>
1565In any aggregate function that takes a single argument, that argument
1566can be preceeded by the keyword DISTINCT. In such cases, duplicate
1567elements are filtered before being passed into the aggregate function.
1568For example, the function "count(distinct X)" will return the number
1569of distinct values of column X instead of the total number of non-null
1570values in column X.
1571</p>
1572
1573<table border=0 cellpadding=10 class="pdf_functions">
1574<tr>
1575<td valign="top" align="right" width=120>avg(<i>X</i>)</td>
1576<td valign="top">Return the average value of all non-NULL <i>X</i> within a
1577group. String and BLOB values that do not look like numbers are
1578interpreted as 0.
1579The result of avg() is always a floating point value even if all
1580inputs are integers. </p></td>
1581</tr>
1582
1583<tr>
1584<td valign="top" align="right">count(<i>X</i>)<br>count(*)</td>
1585<td valign="top">The first form return a count of the number of times
1586that <i>X</i> is not NULL in a group. The second form (with no argument)
1587returns the total number of rows in the group.</td>
1588</tr>
1589
1590<tr>
1591<td valign="top" align="right">max(<i>X</i>)</td>
1592<td valign="top">Return the maximum value of all values in the group.
1593The usual sort order is used to determine the maximum.</td>
1594</tr>
1595
1596<tr>
1597<td valign="top" align="right">min(<i>X</i>)</td>
1598<td valign="top">Return the minimum non-NULL value of all values in the group.
1599The usual sort order is used to determine the minimum. NULL is only returned
1600if all values in the group are NULL.</td>
1601</tr>
1602
1603<tr>
1604<td valign="top" align="right">sum(<i>X</i>)<br>total(<i>X</i>)</td>
1605<td valign="top">Return the numeric sum of all non-NULL values in the group.
1606 If there are no non-NULL input rows then sum() returns
1607 NULL but total() returns 0.0.
1608 NULL is not normally a helpful result for the sum of no rows
1609 but the SQL standard requires it and most other
1610 SQL database engines implement sum() that way so SQLite does it in the
1611 same way in order to be compatible. The non-standard total() function
1612 is provided as a convenient way to work around this design problem
1613 in the SQL language.</p>
1614
1615 <p>The result of total() is always a floating point value.
1616 The result of sum() is an integer value if all non-NULL inputs are integers.
1617 If any input to sum() is neither an integer or a NULL
1618 then sum() returns a floating point value
1619 which might be an approximation to the true sum.</p>
1620
1621 <p>Sum() will throw an "integer overflow" exception if all inputs
1622 are integers or NULL
1623 and an integer overflow occurs at any point during the computation.
1624 Total() never throws an exception.</p>
1625</tr>
1626</table>
1627}
1628
1629
1630Section INSERT insert
1631
1632Syntax {sql-statement} {
1633INSERT [OR <conflict-algorithm>] INTO [<database-name> .] <table-name> [(<column-list>)] VALUES(<value-list>) |
1634INSERT [OR <conflict-algorithm>] INTO [<database-name> .] <table-name> [(<column-list>)] <select-statement>
1635}
1636
1637puts {
1638<p>The INSERT statement comes in two basic forms. The first form
1639(with the "VALUES" keyword) creates a single new row in an existing table.
1640If no column-list is specified then the number of values must
1641be the same as the number of columns in the table. If a column-list
1642is specified, then the number of values must match the number of
1643specified columns. Columns of the table that do not appear in the
1644column list are filled with the default value, or with NULL if no
1645default value is specified.
1646</p>
1647
1648<p>The second form of the INSERT statement takes it data from a
1649SELECT statement. The number of columns in the result of the
1650SELECT must exactly match the number of columns in the table if
1651no column list is specified, or it must match the number of columns
1652name in the column list. A new entry is made in the table
1653for every row of the SELECT result. The SELECT may be simple
1654or compound.</p>
1655
1656<p>The optional conflict-clause allows the specification of an alternative
1657constraint conflict resolution algorithm to use during this one command.
1658See the section titled
1659<a href="#conflict">ON CONFLICT</a> for additional information.
1660For compatibility with MySQL, the parser allows the use of the
1661single keyword <a href="#replace">REPLACE</a> as an alias for "INSERT OR REPLACE".
1662</p>
1663}
1664
1665
1666Section {ON CONFLICT clause} conflict
1667
1668Syntax {conflict-clause} {
1669ON CONFLICT <conflict-algorithm>
1670} {conflict-algorithm} {
1671ROLLBACK | ABORT | FAIL | IGNORE | REPLACE
1672}
1673
1674puts {
1675<p>The ON CONFLICT clause is not a separate SQL command. It is a
1676non-standard clause that can appear in many other SQL commands.
1677It is given its own section in this document because it is not
1678part of standard SQL and therefore might not be familiar.</p>
1679
1680<p>The syntax for the ON CONFLICT clause is as shown above for
1681the CREATE TABLE command. For the INSERT and
1682UPDATE commands, the keywords "ON CONFLICT" are replaced by "OR", to make
1683the syntax seem more natural. For example, instead of
1684"INSERT ON CONFLICT IGNORE" we have "INSERT OR IGNORE".
1685The keywords change but the meaning of the clause is the same
1686either way.</p>
1687
1688<p>The ON CONFLICT clause specifies an algorithm used to resolve
1689constraint conflicts. There are five choices: ROLLBACK, ABORT,
1690FAIL, IGNORE, and REPLACE. The default algorithm is ABORT. This
1691is what they mean:</p>
1692
1693<dl>
1694<dt><b>ROLLBACK</b></dt>
1695<dd><p>When a constraint violation occurs, an immediate ROLLBACK
1696occurs, thus ending the current transaction, and the command aborts
1697with a return code of SQLITE_CONSTRAINT. If no transaction is
1698active (other than the implied transaction that is created on every
1699command) then this algorithm works the same as ABORT.</p></dd>
1700
1701<dt><b>ABORT</b></dt>
1702<dd><p>When a constraint violation occurs, the command backs out
1703any prior changes it might have made and aborts with a return code
1704of SQLITE_CONSTRAINT. But no ROLLBACK is executed so changes
1705from prior commands within the same transaction
1706are preserved. This is the default behavior.</p></dd>
1707
1708<dt><b>FAIL</b></dt>
1709<dd><p>When a constraint violation occurs, the command aborts with a
1710return code SQLITE_CONSTRAINT. But any changes to the database that
1711the command made prior to encountering the constraint violation
1712are preserved and are not backed out. For example, if an UPDATE
1713statement encountered a constraint violation on the 100th row that
1714it attempts to update, then the first 99 row changes are preserved
1715but changes to rows 100 and beyond never occur.</p></dd>
1716
1717<dt><b>IGNORE</b></dt>
1718<dd><p>When a constraint violation occurs, the one row that contains
1719the constraint violation is not inserted or changed. But the command
1720continues executing normally. Other rows before and after the row that
1721contained the constraint violation continue to be inserted or updated
1722normally. No error is returned.</p></dd>
1723
1724<dt><b>REPLACE</b></dt>
1725<dd><p>When a UNIQUE constraint violation occurs, the pre-existing rows
1726that are causing the constraint violation are removed prior to inserting
1727or updating the current row. Thus the insert or update always occurs.
1728The command continues executing normally. No error is returned.
1729If a NOT NULL constraint violation occurs, the NULL value is replaced
1730by the default value for that column. If the column has no default
1731value, then the ABORT algorithm is used. If a CHECK constraint violation
1732occurs then the IGNORE algorithm is used.</p>
1733
1734<p>When this conflict resolution strategy deletes rows in order to
1735satisfy a constraint, it does not invoke delete triggers on those
1736rows. This behavior might change in a future release.</p>
1737</dl>
1738
1739<p>The algorithm specified in the OR clause of a INSERT or UPDATE
1740overrides any algorithm specified in a CREATE TABLE.
1741If no algorithm is specified anywhere, the ABORT algorithm is used.</p>
1742}
1743
1744Section REINDEX reindex
1745
1746Syntax {sql-statement} {
1747 REINDEX <collation name>
1748}
1749Syntax {sql-statement} {
1750 REINDEX [<database-name> .] <table/index-name>
1751}
1752
1753puts {
1754<p>The REINDEX command is used to delete and recreate indices from scratch.
1755This is useful when the definition of a collation sequence has changed.
1756</p>
1757
1758<p>In the first form, all indices in all attached databases that use the
1759named collation sequence are recreated. In the second form, if
1760<i>[database-name.]table/index-name</i> identifies a table, then all indices
1761associated with the table are rebuilt. If an index is identified, then only
1762this specific index is deleted and recreated.
1763</p>
1764
1765<p>If no <i>database-name</i> is specified and there exists both a table or
1766index and a collation sequence of the specified name, then indices associated
1767with the collation sequence only are reconstructed. This ambiguity may be
1768dispelled by always specifying a <i>database-name</i> when reindexing a
1769specific table or index.
1770}
1771
1772Section REPLACE replace
1773
1774Syntax {sql-statement} {
1775REPLACE INTO [<database-name> .] <table-name> [( <column-list> )] VALUES ( <value-list> ) |
1776REPLACE INTO [<database-name> .] <table-name> [( <column-list> )] <select-statement>
1777}
1778
1779puts {
1780<p>The REPLACE command is an alias for the "INSERT OR REPLACE" variant
1781of the <a href="#insert">INSERT</a> command. This alias is provided for
1782compatibility with MySQL. See the
1783<a href="#insert">INSERT</a> command documentation for additional
1784information.</p>
1785}
1786
1787
1788Section SELECT select
1789
1790Syntax {sql-statement} {
1791SELECT [ALL | DISTINCT] <result> [FROM <table-list>]
1792[WHERE <expr>]
1793[GROUP BY <expr-list>]
1794[HAVING <expr>]
1795[<compound-op> <select>]*
1796[ORDER BY <sort-expr-list>]
1797[LIMIT <integer> [LP OFFSET | , RP <integer>]]
1798} {result} {
1799<result-column> [, <result-column>]*
1800} {result-column} {
1801STAR | <table-name> . STAR | <expr> [ [AS] <string> ]
1802} {table-list} {
1803<table> [<join-op> <table> <join-args>]*
1804} {table} {
1805<table-name> [AS <alias>] |
1806( <select> ) [AS <alias>]
1807} {join-op} {
1808, | [NATURAL] [LEFT | RIGHT | FULL] [OUTER | INNER | CROSS] JOIN
1809} {join-args} {
1810[ON <expr>] [USING ( <id-list> )]
1811} {sort-expr-list} {
1812<expr> [<sort-order>] [, <expr> [<sort-order>]]*
1813} {sort-order} {
1814[ COLLATE <collation-name> ] [ ASC | DESC ]
1815} {compound_op} {
1816UNION | UNION ALL | INTERSECT | EXCEPT
1817}
1818
1819puts {
1820<p>The SELECT statement is used to query the database. The
1821result of a SELECT is zero or more rows of data where each row
1822has a fixed number of columns. The number of columns in the
1823result is specified by the expression list in between the
1824SELECT and FROM keywords. Any arbitrary expression can be used
1825as a result. If a result expression is }
1826puts "[Operator *] then all columns of all tables are substituted"
1827puts {for that one expression. If the expression is the name of}
1828puts "a table followed by [Operator .*] then the result is all columns"
1829puts {in that one table.</p>
1830
1831<p>The DISTINCT keyword causes a subset of result rows to be returned,
1832in which each result row is different. NULL values are not treated as
1833distinct from each other. The default behavior is that all result rows
1834be returned, which can be made explicit with the keyword ALL.</p>
1835
1836<p>The query is executed against one or more tables specified after
1837the FROM keyword. If multiple tables names are separated by commas,
1838then the query is against the cross join of the various tables.
1839The full SQL-92 join syntax can also be used to specify joins.
1840A sub-query
1841in parentheses may be substituted for any table name in the FROM clause.
1842The entire FROM clause may be omitted, in which case the result is a
1843single row consisting of the values of the expression list.
1844</p>
1845
1846<p>The WHERE clause can be used to limit the number of rows over
1847which the query operates.</p>
1848
1849<p>The GROUP BY clauses causes one or more rows of the result to
1850be combined into a single row of output. This is especially useful
1851when the result contains aggregate functions. The expressions in
1852the GROUP BY clause do <em>not</em> have to be expressions that
1853appear in the result. The HAVING clause is similar to WHERE except
1854that HAVING applies after grouping has occurred. The HAVING expression
1855may refer to values, even aggregate functions, that are not in the result.</p>
1856
1857<p>The ORDER BY clause causes the output rows to be sorted.
1858The argument to ORDER BY is a list of expressions that are used as the
1859key for the sort. The expressions do not have to be part of the
1860result for a simple SELECT, but in a compound SELECT each sort
1861expression must exactly match one of the result columns. Each
1862sort expression may be optionally followed by a COLLATE keyword and
1863the name of a collating function used for ordering text and/or
1864keywords ASC or DESC to specify the sort order.</p>
1865
1866<p>The LIMIT clause places an upper bound on the number of rows
1867returned in the result. A negative LIMIT indicates no upper bound.
1868The optional OFFSET following LIMIT specifies how many
1869rows to skip at the beginning of the result set.
1870In a compound query, the LIMIT clause may only appear on the
1871final SELECT statement.
1872The limit is applied to the entire query not
1873to the individual SELECT statement to which it is attached.
1874Note that if the OFFSET keyword is used in the LIMIT clause, then the
1875limit is the first number and the offset is the second number. If a
1876comma is used instead of the OFFSET keyword, then the offset is the
1877first number and the limit is the second number. This seeming
1878contradition is intentional - it maximizes compatibility with legacy
1879SQL database systems.
1880</p>
1881
1882<p>A compound SELECT is formed from two or more simple SELECTs connected
1883by one of the operators UNION, UNION ALL, INTERSECT, or EXCEPT. In
1884a compound SELECT, all the constituent SELECTs must specify the
1885same number of result columns. There may be only a single ORDER BY
1886clause at the end of the compound SELECT. The UNION and UNION ALL
1887operators combine the results of the SELECTs to the right and left into
1888a single big table. The difference is that in UNION all result rows
1889are distinct where in UNION ALL there may be duplicates.
1890The INTERSECT operator takes the intersection of the results of the
1891left and right SELECTs. EXCEPT takes the result of left SELECT after
1892removing the results of the right SELECT. When three or more SELECTs
1893are connected into a compound, they group from left to right.</p>
1894}
1895
1896
1897Section UPDATE update
1898
1899Syntax {sql-statement} {
1900UPDATE [ OR <conflict-algorithm> ] [<database-name> .] <table-name>
1901SET <assignment> [, <assignment>]*
1902[WHERE <expr>]
1903} {assignment} {
1904<column-name> = <expr>
1905}
1906
1907puts {
1908<p>The UPDATE statement is used to change the value of columns in
1909selected rows of a table. Each assignment in an UPDATE specifies
1910a column name to the left of the equals sign and an arbitrary expression
1911to the right. The expressions may use the values of other columns.
1912All expressions are evaluated before any assignments are made.
1913A WHERE clause can be used to restrict which rows are updated.</p>
1914
1915<p>The optional conflict-clause allows the specification of an alternative
1916constraint conflict resolution algorithm to use during this one command.
1917See the section titled
1918<a href="#conflict">ON CONFLICT</a> for additional information.</p>
1919}
1920
1921
1922Section VACUUM vacuum
1923
1924Syntax {sql-statement} {
1925VACUUM [<index-or-table-name>]
1926}
1927
1928puts {
1929<p>The VACUUM command is an SQLite extension modeled after a similar
1930command found in PostgreSQL. If VACUUM is invoked with the name of a
1931table or index then it is suppose to clean up the named table or index.
1932In version 1.0 of SQLite, the VACUUM command would invoke
1933<b>gdbm_reorganize()</b> to clean up the backend database file.</p>
1934
1935<p>
1936VACUUM became a no-op when the GDBM backend was removed from
1937SQLITE in version 2.0.0.
1938VACUUM was reimplemented in version 2.8.1.
1939The index or table name argument is now ignored.
1940</p>
1941
1942<p>When an object (table, index, or trigger) is dropped from the
1943database, it leaves behind empty space. This makes the database
1944file larger than it needs to be, but can speed up inserts. In time
1945inserts and deletes can leave the database file structure fragmented,
1946which slows down disk access to the database contents.
1947
1948The VACUUM command cleans
1949the main database by copying its contents to a temporary database file and
1950reloading the original database file from the copy. This eliminates
1951free pages, aligns table data to be contiguous, and otherwise cleans
1952up the database file structure.</p>
1953
1954<p>The VACUUM command may change the
1955<a href="lang_createtable.html#rowid">ROWID</a> of entires in tables that do
1956not have an explicit INTEGER PRIMARY KEY.</p>
1957
1958<p>VACUUM only works on the main database.
1959It is not possible to VACUUM an attached database file.</p>
1960
1961<p>The VACUUM command will fail if there is an active transaction.
1962The VACUUM command is a no-op for in-memory databases.</p>
1963
1964<p>As of SQLite version 3.1, an alternative to using the VACUUM command
1965is auto-vacuum mode, enabled using the
1966<a href="pragma.html#pragma_auto_vacuum">auto_vacuum pragma</a>.
1967When auto-vacuum is enabled for a database, large deletes cause
1968the size of the database file to shrink. However, auto-vacuum
1969also causes excess fragmentation of the database file. And auto-vacuum
1970does not compact partially filled pages of the database as VACUUM
1971does.
1972</p>
1973}
1974
1975# A list of keywords. A asterisk occurs after the keyword if it is on
1976# the fallback list.
1977#
1978set keyword_list [lsort {
1979 ABORT*
1980 ADD
1981 AFTER*
1982 ALL
1983 ALTER
1984 ANALYZE*
1985 AND
1986 AS
1987 ASC*
1988 ATTACH*
1989 AUTOINCREMENT
1990 BEFORE*
1991 BEGIN*
1992 BETWEEN
1993 BY
1994 CASCADE*
1995 CASE
1996 CAST*
1997 CHECK
1998 COLLATE
1999 COMMIT
2000 CONFLICT*
2001 CONSTRAINT
2002 CREATE
2003 CROSS
2004 CURRENT_DATE*
2005 CURRENT_TIME*
2006 CURRENT_TIMESTAMP*
2007 DATABASE*
2008 DEFAULT
2009 DEFERRED*
2010 DEFERRABLE
2011 DELETE
2012 DESC*
2013 DETACH*
2014 DISTINCT
2015 DROP
2016 END*
2017 EACH*
2018 ELSE
2019 ESCAPE
2020 EXCEPT
2021 EXCLUSIVE*
2022 EXPLAIN*
2023 FAIL*
2024 FOR*
2025 FOREIGN
2026 FROM
2027 FULL
2028 GLOB*
2029 GROUP
2030 HAVING
2031 IF*
2032 IGNORE*
2033 IMMEDIATE*
2034 IN
2035 INDEX
2036 INITIALLY*
2037 INNER
2038 INSERT
2039 INSTEAD*
2040 INTERSECT
2041 INTO
2042 IS
2043 ISNULL
2044 JOIN
2045 KEY*
2046 LEFT
2047 LIKE*
2048 LIMIT
2049 MATCH*
2050 NATURAL
2051 NOT
2052 NOTNULL
2053 NULL
2054 OF*
2055 OFFSET*
2056 ON
2057 OR
2058 ORDER
2059 OUTER
2060 PLAN*
2061 PRAGMA*
2062 PRIMARY
2063 QUERY*
2064 RAISE*
2065 REFERENCES
2066 REINDEX*
2067 RENAME*
2068 REPLACE*
2069 RESTRICT*
2070 RIGHT
2071 ROLLBACK
2072 ROW*
2073 SELECT
2074 SET
2075 TABLE
2076 TEMP*
2077 TEMPORARY*
2078 THEN
2079 TO
2080 TRANSACTION
2081 TRIGGER*
2082 UNION
2083 UNIQUE
2084 UPDATE
2085 USING
2086 VACUUM*
2087 VALUES
2088 VIEW*
2089 VIRTUAL*
2090 WHEN
2091 WHERE
2092}]
2093
2094
2095
2096puts {<DIV class="pdf_section">}
2097Section {SQLite Keywords} keywords
2098puts {</DIV>}
2099
2100puts {
2101<p>The SQL standard specifies a huge number of keywords which may not
2102be used as the names of tables, indices, columns, databases, user-defined
2103functions, collations, virtual table modules, or any other named object.
2104The list of keywords is so long that few people can remember them all.
2105For most SQL code, your safest bet is to never use any English language
2106word as the name of a user-defined object.</p>
2107
2108<p>If you want to use a keyword as a name, you need to quote it. There
2109are three ways of quoting keywords in SQLite:</p>
2110
2111<p>
2112<blockquote>
2113<table class="pdf_functions">
2114<tr> <td valign="top"><b>'keyword'</b></td><td width="20"></td>
2115 <td>A keyword in single quotes is interpreted as a literal string
2116 if it occurs in a context where a string literal is allowed, otherwise
2117 it is understood as an identifier.</td></tr>
2118<tr> <td valign="top"><b>"keyword"</b></td><td></td>
2119 <td>A keyword in double-quotes is interpreted as an identifier if
2120 it matches a known identifier. Otherwise it is interpreted as a
2121 string literal.</td></tr>
2122<tr> <td valign="top"><b>[keyword]</b></td><td></td>
2123 <td>A keyword enclosed in square brackets is always understood as
2124 an identifier. This is not standard SQL. This quoting mechanism
2125 is used by MS Access and SQL Server and is included in SQLite for
2126 compatibility.</td></tr>
2127</table>
2128</blockquote>
2129</p>
2130
2131<p>Quoted keywords are unaesthetic.
2132To help you avoid them, SQLite allows many keywords to be used unquoted
2133as the names of databases, tables, indices, triggers, views, columns,
2134user-defined functions, collations, attached databases, and virtual
2135function modules.
2136In the list of keywords that follows, those that can be used as identifiers
2137are shown in an italic font. Keywords that must be quoted in order to be
2138used as identifiers are shown in bold.</p>
2139
2140<p>
2141SQLite adds new keywords from time to time when it take on new features.
2142So to prevent your code from being broken by future enhancements, you should
2143normally quote any indentifier that is an English language word, even if
2144you do not have to.
2145</p>
2146
2147<p>
2148The following are the keywords currently recognized by SQLite:
2149</p>
2150
2151<blockquote>
2152<table width="100%" class="pdf_keywords">
2153<tr>
2154<td align="left" valign="top" width="20%">
2155}
2156
2157set n [llength $keyword_list]
2158set nCol 5
2159set nRow [expr {($n+$nCol-1)/$nCol}]
2160set i 0
2161foreach word $keyword_list {
2162 if {[string index $word end]=="*"} {
2163 set word [string range $word 0 end-1]
2164 set font i
2165 } else {
2166 set font b
2167 }
2168 if {$i==$nRow} {
2169 puts "</td><td valign=\"top\" align=\"left\" width=\"20%\">"
2170 set i 1
2171 } else {
2172 incr i
2173 }
2174 puts "<$font>$word</$font><br>"
2175}
2176
2177puts {
2178</td></tr></table></blockquote>
2179
2180<h2>Special names</h2>
2181
2182<p>The following are not keywords in SQLite, but are used as names of
2183system objects. They can be used as an identifier for a different
2184type of object.</p>
2185
2186<blockquote class="pdf_keywords"><b>
2187 _ROWID_<br>
2188 MAIN<br>
2189 OID<br>
2190 ROWID<br>
2191 SQLITE_MASTER<br>
2192 SQLITE_SEQUENCE<br>
2193 SQLITE_TEMP_MASTER<br>
2194 TEMP<br>
2195</b></blockquote>
2196}
2197
2198puts {<DIV class="pdf_ignore">}
2199footer $rcsid
2200if {[string length $outputdir]} {
2201 footer $rcsid
2202}
2203puts {</DIV>}
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/limits.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/limits.tcl
deleted file mode 100644
index cf85e38..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/limits.tcl
+++ /dev/null
@@ -1,318 +0,0 @@
1#
2# Run this script to generate the limits.html output file
3#
4set rcsid {$Id: limits.tcl,v 1.5 2007/08/09 00:00:26 drh Exp $}
5source common.tcl
6header {Implementation Limits For SQLite}
7puts {
8<h2>Limits In SQLite</h2>
9
10<p>
11"Limits" in the context of this article means sizes or
12quantities that can not be exceeded. We are concerned
13with things like the maximum number of bytes in a
14BLOB or the maximum number of columns in a table.
15</p>
16
17<p>
18SQLite was originally designed with a policy of avoiding
19arbitrary limits.
20Of course, every program that runs on a machine with finite
21memory and disk space has limits of some kind. But in SQLite,
22those limits
23were not well defined. The policy was that if it would fit
24in memory and you could count it with a 32-bit integer, then
25it should work.
26</p>
27
28<p>
29Unfortunately, the no-limits policy has been shown to create
30problems. Because the upper bounds were not well
31defined, they were not tested, and bugs (including possible
32security exploits) were often found when pushing SQLite to
33extremes. For this reason, newer versions of SQLite have
34well-defined limits and those limits are tested as part of
35the test suite.
36</p>
37
38<p>
39This article defines what the limits of SQLite are and how they
40can be customized for specific applications. The default settings
41for limits are normally quite large and adequate for almost every
42application. Some applications may what to increase a limit here
43or there, but we expect such needs to be rare. More commonly,
44an application might want to recompile SQLite with much lower
45limits to avoid excess resource utilization in the event of
46bug in higher-level SQL statement generators or to help thwart
47attackers who inject malicious SQL statements.
48</p>
49}
50proc limititem {title text} {
51 puts "<li><p><b>$title</b></p>\n$text</li>"
52}
53puts {
54<ol>
55}
56
57limititem {Maximum length of a string or BLOB} {
58<p>
59The maximum number of bytes in a string or BLOB in SQLite is defined
60by the preprocessor macro SQLITE_MAX_LENGTH. The default value
61of this macro is 1 billion (1 thousand million or 1,000,000,000).
62You can raise or lower this value at compile-time using a command-line
63option like this:
64</p>
65
66<blockquote>-DSQLITE_MAX_LENGTH=123456789</blockquote>
67
68<p>
69The current implementation will only support a string or BLOB
70length up to 2<small><sup>31</sup></small>-1 or 2147483647. And
71some built-in functions such as hex() might fail well before that
72point. In security-sensitive applications it is best not to
73try to increase the maximum string and blob length. In fact,
74you might do well to lower the maximum string and blob length
75to something more in the range of a few million if that is
76possible.
77</p>
78
79<p>
80During part of SQLite's INSERT and SELECT processing, the complete
81content of each row in the database is encoded as a single BLOB.
82So the SQLITE_MAX_LENGTH parameter also determines the maximum
83number of bytes in a row.
84</p>
85}
86
87limititem {Maximum Number Of Columns} {
88<p>
89The SQLITE_MAX_COLUMN compile-time parameter is used to set an upper
90bound on:
91</p>
92
93<ul>
94<li>The number of columns in a table</li>
95<li>The number of columns in an index</li>
96<li>The number of columns in a view</li>
97<li>The number of terms in the SET clause of an UPDATE statement</li>
98<li>The number of columns in the result set of a SELECT statement</li>
99<li>The number of terms in a GROUP BY or ORDER BY clause</li>
100<li>The number of values in an INSERT statement</li>
101</ul>
102
103<p>
104The default setting for SQLITE_MAX_COLUMN is 2000. You can change it
105at compile time to values as large as 32676. You might be able to
106redefine this value to be as large as billions, though nobody has ever
107tried doing that so we do not know if it will work. On the other hand, there
108are people who will argue that a well-normalized database design
109will never need a value larger than about 100.
110</p>
111
112<p>
113In most applications, the number of columns is small - a few dozen.
114There are places in the SQLite code generator that use algorithms
115that are O(N&sup2;) where N is the number of columns.
116So if you redefine SQLITE_MAX_COLUMN to be a
117really huge number and you generate SQL that uses a large number of
118columns, you may find that
119<a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a>
120runs slowly.
121}
122
123limititem {Maximum Length Of An SQL Statement} {
124<p>
125The maximum number of bytes in the text of an SQL statement is
126limited to SQLITE_MAX_SQL_LENGTH which defaults to 1000000. You
127can redefine this limit to be as large as the smaller of SQLITE_MAX_LENGTH
128and 1073741824.
129</p>
130
131<p>
132If an SQL statement is limited to be a million bytes in length, then
133obviously you will not be able to insert multi-million byte strings
134by embedding them as literals inside of INSERT statements. But
135you should not do that anyway. Use host parameters
136for your data. Prepare short SQL statements like this:
137</p>
138
139<blockquote>
140INSERT INTO tab1 VALUES(?,?,?);
141</blockquote>
142
143<p>
144Then use the
145<a href="capi3ref.html#sqlite3_bind_text">sqlite3_bind_XXXX()</a> functions
146to bind your large string values to the SQL statement. The use of binding
147obviates the need to escape quote characters in the string, reducing the
148risk of SQL injection attacks. It is also runs faster since the large
149string does not need to be parsed or copied as much.
150</p>
151}
152
153limititem {Maximum Number Of Tables In A Join} {
154<p>
155SQLite does not support joins containing more than 64 tables.
156This limit arises from the fact that the SQLite code generator
157uses bitmaps with one bit per join-table in the query optimizer.
158</p>
159}
160
161limititem {Maximum Depth Of An Expression Tree} {
162<p>
163SQLite parses expressions into a tree for processing. During
164code generation, SQLite walks this tree recursively. The depth
165of expression trees is therefore limited in order to avoid
166using too much stack space.
167</p>
168
169<p>
170The SQLITE_MAX_EXPR_DEPTH parameter determines the maximum expression
171tree depth. If the value is 0, then no limit is enforced. The
172current implementation has a default value of 1000.
173</p>
174}
175
176limititem {Maximum Number Of Arguments On A Function} {
177<p>
178The SQLITE_MAX_FUNCTION_ARG parameter determines the maximum number
179of parameters that can be passed to an SQL function. The default value
180of this limit is 100. We know of no
181technical reason why SQLite would not work with functions that have
182millions of parameters. However, we suspect that anybody who tries
183to invoke a function with millions of parameters is really
184trying to find security exploits in systems that use SQLite,
185not do useful work,
186and so for that reason we have set this parameter relatively low.
187}
188
189limititem {Maximum Number Of Terms In A Compound SELECT Statement} {
190<p>
191A compound SELECT statement is two or more SELECT statements connected
192by operators UNION, UNION ALL, EXCEPT, or INTERSECT. We call each
193individual SELECT statement within a compound SELECT a "term".
194</p>
195
196<p>
197The code generator in SQLite processes compound SELECT statements using
198a recursive algorithm. In order to limit the size of the stack, we
199therefore limit the number of terms in a compound SELECT. The maximum
200number of terms is SQLITE_MAX_COMPOUND_SELECT which defaults to 500.
201We think this is a generous allotment since in practice we almost
202never see the number of terms in a compound select exceed single digits.
203</p>
204}
205
206limititem {Maximum Length Of A LIKE Or GLOB Pattern} {
207<p>
208The pattern matching algorithm used in the default LIKE and GLOB
209implementation of SQLite can exhibit O(N&sup2) performance (where
210N is the number of characters in the pattern) for certain pathological
211cases. To avoid denial-of-service attacks from miscreants who are able
212to specify their own LIKE or GLOB patterns, the length of the LIKE
213or GLOB pattern is limited to SQLITE_MAX_LIKE_PATTERN_LENGTH bytes.
214The default value of this limit is 50000. A modern workstation can
215evaluate even a pathological LIKE or GLOB pattern of 50000 bytes
216relatively quickly. The denial of service problem only comes into
217play when the pattern length gets into millions of bytes. Nevertheless,
218since most useful LIKE or GLOB patterns are at most a few dozen bytes
219in length, paranoid application developers may want to reduce this
220parameter to something in the range of a few hundred if they know that
221external users are able to generate arbitrary patterns.
222</p>
223}
224
225limititem {Maximum Number Of Host Parameters In A Single SQL Statement} {
226<p>
227A host parameter is a place-holder in an SQL statement that is filled
228in using one of the
229<a href="capi3ref.html#sqlite3_bind_blob">sqlite3_bind_XXXX()</a> interfaces.
230Many SQL programmers are familiar with using a question mark ("?") as a
231host parameter. SQLite also supports named host parameters prefaced
232by ":", "$", or "@" and numbered host parameters of the form "?123".
233</p>
234
235<p>
236Each host parameter in an SQLite statement is assigned a number. The
237numbers normally begin with 1 and increase by one with each new
238parameter. However, when the "?123" form is used, the host parameter
239number is the number that follows the question mark.
240</p>
241
242<p>
243The maximum value of a host parameter number is SQLITE_MAX_VARIABLE_NUMBER.
244This setting defaults to 999.
245</p>
246}
247
248limititem {Maximum Number Of Attached Databases} {
249<p>
250The <a href="lang_attach.html">ATTACH</a> statement is an SQLite extension
251that allows two or more databases to be associated to the same database
252connection and to operate as if they were a single database. The number
253of simulataneously attached databases is limited to SQLITE_MAX_ATTACHED
254which is set to 10 by default.
255The code generator in SQLite uses bitmaps
256to keep track of attached databases. That means that the number of
257attached databases cannot be increased above 30 on a 32-bit machine
258or 62 on a 64-bit machine.
259}
260
261limititem {Maximum Database Page Size} {
262<p>
263An SQLite database file is organized as pages. The size of each
264page is a power of 2 between 512 and SQLITE_MAX_PAGE_SIZE.
265The default value for SQLITE_MAX_PAGE_SIZE is 32768. The current
266implementation will not support a larger value.
267</p>
268
269<p>
270It used to be the case that SQLite would allocate some stack
271structures whose size was proportional to the maximum page size.
272For this reason, SQLite would sometimes be compiled with a smaller
273maximum page size on embedded devices with limited stack memory. But
274more recent versions of SQLite put these large structures on the
275heap, not on the stack, so reducing the maximum page size is no
276longer necessary on embedded devices.
277</p>
278}
279
280limititem {Maximum Number Of Pages In A Database File} {
281<p>
282SQLite is able to limit the size of a database file to prevent
283the database file from growing too large and consuming too much
284disk or flash space.
285The SQLITE_MAX_PAGE_COUNT parameter, which is normally set to
2861073741823, is the maximum number of pages allowed in a single
287database file. An attempt to insert new data that would cause
288the database file to grow larger than this will return
289SQLITE_FULL.
290</p>
291
292<p>
293The <a href="pragma.html#pragma_max_page_count">
294max_page_count PRAGMA</a> can be used to raise or lower this
295limit at run-time.
296</p>
297
298<p>
299Note that the transaction processing in SQLite requires two bits
300of heap memory for every page in the database file. For databases
301of a few megabytes in size, this amounts to only a few hundred
302bytes of heap memory. But for gigabyte-sized databases the amount
303of heap memory required is getting into the kilobyte range and
304for terabyte-sized databases, megabytes of heap memory must be
305allocated and zeroed at each transaction. SQLite will
306support very large databases in theory, but the current implementation
307is optimized for the common SQLite use cases of embedded devices
308and persistent stores for desktop applications. In other words,
309SQLite is designed for use with databases sized in kilobytes or
310megabytes not gigabytes. If you are building an application to
311work with databases that are hundreds of gigabytes or more
312in size, then you should perhaps consider using a different database
313engine that is explicitly designed for such large data sets.
314</p>
315}
316
317puts {</ol>}
318footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/lockingv3.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/lockingv3.tcl
deleted file mode 100644
index c51cf79..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/lockingv3.tcl
+++ /dev/null
@@ -1,570 +0,0 @@
1#
2# Run this script to generated a lockingv3.html output file
3#
4set rcsid {$Id: }
5source common.tcl
6header {File Locking And Concurrency In SQLite Version 3}
7
8proc HEADING {level title {label {}}} {
9 global pnum
10 incr pnum($level)
11 foreach i [array names pnum] {
12 if {$i>$level} {set pnum($i) 0}
13 }
14 set h [expr {$level+1}]
15 if {$h>6} {set h 6}
16 set n $pnum(1).$pnum(2)
17 for {set i 3} {$i<=$level} {incr i} {
18 append n .$pnum($i)
19 }
20 if {$label!=""} {
21 puts "<a name=\"$label\">"
22 }
23 puts "<h$h>$n $title</h$h>"
24}
25set pnum(1) 0
26set pnum(2) 0
27set pnum(3) 0
28set pnum(4) 0
29set pnum(5) 0
30set pnum(6) 0
31set pnum(7) 0
32set pnum(8) 0
33
34HEADING 1 {File Locking And Concurrency In SQLite Version 3}
35
36puts {
37<p>Version 3 of SQLite introduces a more complex locking and journaling
38mechanism designed to improve concurrency and reduce the writer starvation
39problem. The new mechanism also allows atomic commits of transactions
40involving multiple database files.
41This document describes the new locking mechanism.
42The intended audience is programmers who want to understand and/or modify
43the pager code and reviewers working to verify the design
44of SQLite version 3.
45</p>
46}
47
48HEADING 1 {Overview} overview
49
50puts {
51<p>
52Locking and concurrency control are handled by the the
53<a href="http://www.sqlite.org/cvstrac/getfile/sqlite/src/pager.c">
54pager module</a>.
55The pager module is responsible for making SQLite "ACID" (Atomic,
56Consistent, Isolated, and Durable). The pager module makes sure changes
57happen all at once, that either all changes occur or none of them do,
58that two or more processes do not try to access the database
59in incompatible ways at the same time, and that once changes have been
60written they persist until explicitly deleted. The pager also provides
61an memory cache of some of the contents of the disk file.</p>
62
63<p>The pager is unconcerned
64with the details of B-Trees, text encodings, indices, and so forth.
65From the point of view of the pager the database consists of
66a single file of uniform-sized blocks. Each block is called a
67"page" and is usually 1024 bytes in size. The pages are numbered
68beginning with 1. So the first 1024 bytes of the database are called
69"page 1" and the second 1024 bytes are call "page 2" and so forth. All
70other encoding details are handled by higher layers of the library.
71The pager communicates with the operating system using one of several
72modules
73(Examples:
74<a href="http://www.sqlite.org/cvstrac/getfile/sqlite/src/os_unix.c">
75os_unix.c</a>,
76<a href="http://www.sqlite.org/cvstrac/getfile/sqlite/src/os_win.c">
77os_win.c</a>)
78that provides a uniform abstraction for operating system services.
79</p>
80
81<p>The pager module effectively controls access for separate threads, or
82separate processes, or both. Throughout this document whenever the
83word "process" is written you may substitute the word "thread" without
84changing the truth of the statement.</p>
85}
86
87HEADING 1 {Locking} locking
88
89puts {
90<p>
91From the point of view of a single process, a database file
92can be in one of five locking states:
93</p>
94
95<p>
96<table cellpadding="20">
97<tr><td valign="top">UNLOCKED</td>
98<td valign="top">
99No locks are held on the database. The database may be neither read nor
100written. Any internally cached data is considered suspect and subject to
101verification against the database file before being used. Other
102processes can read or write the database as their own locking states
103permit. This is the default state.
104</td></tr>
105
106<tr><td valign="top">SHARED</td>
107<td valign="top">
108The database may be read but not written. Any number of
109processes can hold SHARED locks at the same time, hence there can be
110many simultaneous readers. But no other thread or process is allowed
111to write to the database file while one or more SHARED locks are active.
112</td></tr>
113
114<tr><td valign="top">RESERVED</td>
115<td valign="top">
116A RESERVED lock means that the process is planning on writing to the
117database file at some point in the future but that it is currently just
118reading from the file. Only a single RESERVED lock may be active at one
119time, though multiple SHARED locks can coexist with a single RESERVED lock.
120RESERVED differs from PENDING in that new SHARED locks can be acquired
121while there is a RESERVED lock.
122</td></tr>
123
124<tr><td valign="top">PENDING</td>
125<td valign="top">
126A PENDING lock means that the process holding the lock wants to write
127to the database as soon as possible and is just waiting on all current
128SHARED locks to clear so that it can get an EXCLUSIVE lock. No new
129SHARED locks are permitted against the database if
130a PENDING lock is active, though existing SHARED locks are allowed to
131continue.
132</td></tr>
133
134<tr><td valign="top">EXCLUSIVE</td>
135<td valign="top">
136An EXCLUSIVE lock is needed in order to write to the database file.
137Only one EXCLUSIVE lock is allowed on the file and no other locks of
138any kind are allowed to coexist with an EXCLUSIVE lock. In order to
139maximize concurrency, SQLite works to minimize the amount of time that
140EXCLUSIVE locks are held.
141</td></tr>
142</table>
143</p>
144
145<p>
146The operating system interface layer understands and tracks all five
147locking states described above.
148The pager module only tracks four of the five locking states.
149A PENDING lock is always just a temporary
150stepping stone on the path to an EXCLUSIVE lock and so the pager module
151does not track PENDING locks.
152</p>
153}
154
155HEADING 1 {The Rollback Journal} rollback
156
157puts {
158<p>Any time a process wants to make a changes to a database file, it
159first records enough information in the <em>rollback journal</em> to
160restore the database file back to its initial condition. Thus, before
161altering any page of the database, the original contents of that page
162must be written into the journal. The journal also records the initial
163size of the database so that if the database file grows it can be truncated
164back to its original size on a rollback.</p>
165
166<p>The rollback journal is a ordinary disk file that has the same name as
167the database file with the suffix "<tt>-journal</tt>" added.</p>
168
169<p>If SQLite is working with multiple databases at the same time
170(using the ATTACH command) then each database has its own journal.
171But there is also a separate aggregate journal
172called the <em>master journal</em>.
173The master journal does not contain page data used for rolling back
174changes. Instead the master journal contains the names of the
175individual file journals for each of the ATTACHed databases. Each of
176the individual file journals also contain the name of the master journal.
177If there are no ATTACHed databases (or if none of the ATTACHed database
178is participating in the current transaction) no master journal is
179created and the normal rollback journal contains an empty string
180in the place normally reserved for recording the name of the master
181journal.</p>
182
183<p>A individual file journal is said to be <em>hot</em>
184if it needs to be rolled back
185in order to restore the integrity of its database.
186A hot journal is created when a process is in the middle of a database
187update and a program or operating system crash or power failure prevents
188the update from completing.
189Hot journals are an exception condition.
190Hot journals exist to recover from crashes and power failures.
191If everything is working correctly
192(that is, if there are no crashes or power failures)
193you will never get a hot journal.
194</p>
195
196<p>
197If no master journal is involved, then
198a journal is hot if it exists and its corresponding database file
199does not have a RESERVED lock.
200If a master journal is named in the file journal, then the file journal
201is hot if its master journal exists and there is no RESERVED
202lock on the corresponding database file.
203It is important to understand when a journal is hot so the
204preceding rules will be repeated in bullets:
205</p>
206
207<ul>
208<li>A journal is hot if...
209 <ul>
210 <li>It exists, and</li>
211 <li>It's master journal exists or the master journal name is an
212 empty string, and</li>
213 <li>There is no RESERVED lock on the corresponding database file.</li>
214 </ul>
215</li>
216</ul>
217}
218
219HEADING 2 {Dealing with hot journals} hot_journals
220
221puts {
222<p>
223Before reading from a a database file, SQLite always checks to see if that
224database file has a hot journal. If the file does have a hot journal, then
225the journal is rolled back before the file is read. In this way, we ensure
226that the database file is in a consistent state before it is read.
227</p>
228
229<p>When a process wants to read from a database file, it followed
230the following sequence of steps:
231</p>
232
233<ol>
234<li>Open the database file and obtain a SHARED lock. If the SHARED lock
235 cannot be obtained, fail immediately and return SQLITE_BUSY.</li>
236<li>Check to see if the database file has a hot journal. If the file
237 does not have a hot journal, we are done. Return immediately.
238 If there is a hot journal, that journal must be rolled back by
239 the subsequent steps of this algorithm.</li>
240<li>Acquire a PENDING lock then an EXCLUSIVE lock on the database file.
241 (Note: Do not acquire a RESERVED lock because that would make
242 other processes think the journal was no longer hot.) If we
243 fail to acquire these locks it means another process
244 is already trying to do the rollback. In that case,
245 drop all locks, close the database, and return SQLITE_BUSY. </li>
246<li>Read the journal file and roll back the changes.</li>
247<li>Wait for the rolled back changes to be written onto
248 the surface of the disk. This protects the integrity of the database
249 in case another power failure or crash occurs.</li>
250<li>Delete the journal file.</li>
251<li>Delete the master journal file if it is safe to do so.
252 This step is optional. It is here only to prevent stale
253 master journals from cluttering up the disk drive.
254 See the discussion below for details.</li>
255<li>Drop the EXCLUSIVE and PENDING locks but retain the SHARED lock.</li>
256</ol>
257
258<p>After the algorithm above completes successfully, it is safe to
259read from the database file. Once all reading has completed, the
260SHARED lock is dropped.</p>
261}
262
263HEADING 2 {Deleting stale master journals} stale_master_journals
264
265puts {
266<p>A stale master journal is a master journal that is no longer being
267used for anything. There is no requirement that stale master journals
268be deleted. The only reason for doing so is to free up disk space.</p>
269
270<p>A master journal is stale if no individual file journals are pointing
271to it. To figure out if a master journal is stale, we first read the
272master journal to obtain the names of all of its file journals. Then
273we check each of those file journals. If any of the file journals named
274in the master journal exists and points back to the master journal, then
275the master journal is not stale. If all file journals are either missing
276or refer to other master journals or no master journal at all, then the
277master journal we are testing is stale and can be safely deleted.</p>
278}
279
280HEADING 1 {Writing to a database file} writing
281
282puts {
283<p>To write to a database, a process must first acquire a SHARED lock
284as described above (possibly rolling back incomplete changes if there
285is a hot journal).
286After a SHARED lock is obtained, a RESERVED lock must be acquired.
287The RESERVED lock signals that the process intends to write to the
288database at some point in the future. Only one process at a time
289can hold a RESERVED lock. But other processes can continue to read
290the database while the RESERVED lock is held.
291</p>
292
293<p>If the process that wants to write is unable to obtain a RESERVED
294lock, it must mean that another process already has a RESERVED lock.
295In that case, the write attempt fails and returns SQLITE_BUSY.</p>
296
297<p>After obtaining a RESERVED lock, the process that wants to write
298creates a rollback journal. The header of the journal is initialized
299with the original size of the database file. Space in the journal header
300is also reserved for a master journal name, though the master journal
301name is initially empty.</p>
302
303<p>Before making changes to any page of the database, the process writes
304the original content of that page into the rollback journal. Changes
305to pages are held in memory at first and are not written to the disk.
306The original database file remains unaltered, which means that other
307processes can continue to read the database.</p>
308
309<p>Eventually, the writing process will want to update the database
310file, either because its memory cache has filled up or because it is
311ready to commit its changes. Before this happens, the writer must
312make sure no other process is reading the database and that the rollback
313journal data is safely on the disk surface so that it can be used to
314rollback incomplete changes in the event of a power failure.
315The steps are as follows:</p>
316
317<ol>
318<li>Make sure all rollback journal data has actually been written to
319 the surface of the disk (and is not just being held in the operating
320 system's or disk controllers cache) so that if a power failure occurs
321 the data will still be there after power is restored.</li>
322<li>Obtain a PENDING lock and then an EXCLUSIVE lock on the database file.
323 If other processes are still have SHARED locks, the writer might have
324 to wait until those SHARED locks clear before it is able to obtain
325 an EXCLUSIVE lock.</li>
326<li>Write all page modifications currently held in memory out to the
327 original database disk file.</li>
328</ol>
329
330<p>
331If the reason for writing to the database file is because the memory
332cache was full, then the writer will not commit right away. Instead,
333the writer might continue to make changes to other pages. Before
334subsequent changes are written to the database file, the rollback
335journal must be flushed to disk again. Note also that the EXCLUSIVE
336lock that the writer obtained in order to write to the database initially
337must be held until all changes are committed. That means that no other
338processes are able to access the database from the
339time the memory cache first spills to disk until the transaction
340commits.
341</p>
342
343<p>
344When a writer is ready to commit its changes, it executes the following
345steps:
346</p>
347
348<ol>
349<li value="4">
350 Obtain an EXCLUSIVE lock on the database file and
351 make sure all memory changes have been written to the database file
352 using the algorithm of steps 1-3 above.</li>
353<li>Flush all database file changes to the disk. Wait for those changes
354 to actually be written onto the disk surface.</li>
355<li>Delete the journal file. This is the instant when the changes are
356 committed. Prior to deleting the journal file, if a power failure
357 or crash occurs, the next process to open the database will see that
358 it has a hot journal and will roll the changes back.
359 After the journal is deleted, there will no longer be a hot journal
360 and the changes will persist.
361 </li>
362<li>Drop the EXCLUSIVE and PENDING locks from the database file.
363 </li>
364</ol>
365
366<p>As soon as PENDING lock is released from the database file, other
367processes can begin reading the database again. In the current implementation,
368the RESERVED lock is also released, but that is not essential. Future
369versions of SQLite might provide a "CHECKPOINT" SQL command that will
370commit all changes made so far within a transaction but retain the
371RESERVED lock so that additional changes can be made without given
372any other process an opportunity to write.</p>
373
374<p>If a transaction involves multiple databases, then a more complex
375commit sequence is used, as follows:</p>
376
377<ol>
378<li value="4">
379 Make sure all individual database files have an EXCLUSIVE lock and a
380 valid journal.
381<li>Create a master-journal. The name of the master-journal is arbitrary.
382 (The current implementation appends random suffixes to the name of the
383 main database file until it finds a name that does not previously exist.)
384 Fill the master journal with the names of all the individual journals
385 and flush its contents to disk.
386<li>Write the name of the master journal into
387 all individual journals (in space set aside for that purpose in the
388 headers of the individual journals) and flush the contents of the
389 individual journals to disk and wait for those changes to reach the
390 disk surface.
391<li>Flush all database file changes to the disk. Wait for those changes
392 to actually be written onto the disk surface.</li>
393<li>Delete the master journal file. This is the instant when the changes are
394 committed. Prior to deleting the master journal file, if a power failure
395 or crash occurs, the individual file journals will be considered hot
396 and will be rolled back by the next process that
397 attempts to read them. After the master journal has been deleted,
398 the file journals will no longer be considered hot and the changes
399 will persist.
400 </li>
401<li>Delete all individual journal files.
402<li>Drop the EXCLUSIVE and PENDING locks from all database files.
403 </li>
404</ol>
405}
406
407HEADING 2 {Writer starvation} writer_starvation
408
409puts {
410<p>In SQLite version 2, if many processes are reading from the database,
411it might be the case that there is never a time when there are
412no active readers. And if there is always at least one read lock on the
413database, no process would ever be able to make changes to the database
414because it would be impossible to acquire a write lock. This situation
415is called <em>writer starvation</em>.</p>
416
417<p>SQLite version 3 seeks to avoid writer starvation through the use of
418the PENDING lock. The PENDING lock allows existing readers to continue
419but prevents new readers from connecting to the database. So when a
420process wants to write a busy database, it can set a PENDING lock which
421will prevent new readers from coming in. Assuming existing readers do
422eventually complete, all SHARED locks will eventually clear and the
423writer will be given a chance to make its changes.</p>
424}
425
426HEADING 1 {How To Corrupt Your Database Files} how_to_corrupt
427
428puts {
429<p>The pager module is robust but it is not completely failsafe.
430It can be subverted. This section attempts to identify and explain
431the risks.</p>
432
433<p>
434Clearly, a hardware or operating system fault that introduces incorrect data
435into the middle of the database file or journal will cause problems.
436Likewise,
437if a rogue process opens a database file or journal and writes malformed
438data into the middle of it, then the database will become corrupt.
439There is not much that can be done about these kinds of problems
440so they are given no further attention.
441</p>
442
443<p>
444SQLite uses POSIX advisory locks to implement locking on Unix. On
445windows it uses the LockFile(), LockFileEx(), and UnlockFile() system
446calls. SQLite assumes that these system calls all work as advertised. If
447that is not the case, then database corruption can result. One should
448note that POSIX advisory locking is known to be buggy or even unimplemented
449on many NFS implementations (including recent versions of Mac OS X)
450and that there are reports of locking problems
451for network filesystems under windows. Your best defense is to not
452use SQLite for files on a network filesystem.
453</p>
454
455<p>
456SQLite uses the fsync() system call to flush data to the disk under Unix and
457it uses the FlushFileBuffers() to do the same under windows. Once again,
458SQLite assumes that these operating system services function as advertised.
459But it has been reported that fsync() and FlushFileBuffers() do not always
460work correctly, especially with inexpensive IDE disks. Apparently some
461manufactures of IDE disks have defective controller chips that report
462that data has reached the disk surface when in fact the data is still
463in volatile cache memory in the disk drive electronics. There are also
464reports that windows sometimes chooses to ignore FlushFileBuffers() for
465unspecified reasons. The author cannot verify any of these reports.
466But if they are true, it means that database corruption is a possibility
467following an unexpected power loss. These are hardware and/or operating
468system bugs that SQLite is unable to defend against.
469</p>
470
471<p>
472If a crash or power failure occurs and results in a hot journal but that
473journal is deleted, the next process to open the database will not
474know that it contains changes that need to be rolled back. The rollback
475will not occur and the database will be left in an inconsistent state.
476Rollback journals might be deleted for any number of reasons:
477</p>
478
479<ul>
480<li>An administrator might be cleaning up after an OS crash or power failure,
481 see the journal file, think it is junk, and delete it.</li>
482<li>Someone (or some process) might rename the database file but fail to
483 also rename its associated journal.</li>
484<li>If the database file has aliases (hard or soft links) and the file
485 is opened by a different alias than the one used to create the journal,
486 then the journal will not be found. To avoid this problem, you should
487 not create links to SQLite database files.</li>
488<li>Filesystem corruption following a power failure might cause the
489 journal to be renamed or deleted.</li>
490</ul>
491
492<p>
493The last (fourth) bullet above merits additional comment. When SQLite creates
494a journal file on Unix, it opens the directory that contains that file and
495calls fsync() on the directory, in an effort to push the directory information
496to disk. But suppose some other process is adding or removing unrelated
497files to the directory that contains the database and journal at the the
498moment of a power failure. The supposedly unrelated actions of this other
499process might result in the journal file being dropped from the directory and
500moved into "lost+found". This is an unlikely scenario, but it could happen.
501The best defenses are to use a journaling filesystem or to keep the
502database and journal in a directory by themselves.
503</p>
504
505<p>
506For a commit involving multiple databases and a master journal, if the
507various databases were on different disk volumes and a power failure occurs
508during the commit, then when the machine comes back up the disks might
509be remounted with different names. Or some disks might not be mounted
510at all. When this happens the individual file journals and the master
511journal might not be able to find each other. The worst outcome from
512this scenario is that the commit ceases to be atomic.
513Some databases might be rolled back and others might not.
514All databases will continue to be self-consistent.
515To defend against this problem, keep all databases
516on the same disk volume and/or remount disks using exactly the same names
517after a power failure.
518</p>
519}
520
521HEADING 1 {Transaction Control At The SQL Level} transaction_control
522
523puts {
524<p>
525The changes to locking and concurrency control in SQLite version 3 also
526introduce some subtle changes in the way transactions work at the SQL
527language level.
528By default, SQLite version 3 operates in <em>autocommit</em> mode.
529In autocommit mode,
530all changes to the database are committed as soon as all operations associated
531with the current database connection complete.</p>
532
533<p>The SQL command "BEGIN TRANSACTION" (the TRANSACTION keyword
534is optional) is used to take SQLite out of autocommit mode.
535Note that the BEGIN command does not acquire any locks on the database.
536After a BEGIN command, a SHARED lock will be acquired when the first
537SELECT statement is executed. A RESERVED lock will be acquired when
538the first INSERT, UPDATE, or DELETE statement is executed. No EXCLUSIVE
539lock is acquired until either the memory cache fills up and must
540be spilled to disk or until the transaction commits. In this way,
541the system delays blocking read access to the file file until the
542last possible moment.
543</p>
544
545<p>The SQL command "COMMIT" does not actually commit the changes to
546disk. It just turns autocommit back on. Then, at the conclusion of
547the command, the regular autocommit logic takes over and causes the
548actual commit to disk to occur.
549The SQL command "ROLLBACK" also operates by turning autocommit back on,
550but it also sets a flag that tells the autocommit logic to rollback rather
551than commit.</p>
552
553<p>If the SQL COMMIT command turns autocommit on and the autocommit logic
554then tries to commit change but fails because some other process is holding
555a SHARED lock, then autocommit is turned back off automatically. This
556allows the user to retry the COMMIT at a later time after the SHARED lock
557has had an opportunity to clear.</p>
558
559<p>If multiple commands are being executed against the same SQLite database
560connection at the same time, the autocommit is deferred until the very
561last command completes. For example, if a SELECT statement is being
562executed, the execution of the command will pause as each row of the
563result is returned. During this pause other INSERT, UPDATE, or DELETE
564commands can be executed against other tables in the database. But none
565of these changes will commit until the original SELECT statement finishes.
566</p>
567}
568
569
570footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/mingw.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/mingw.tcl
deleted file mode 100644
index f1a0186..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/mingw.tcl
+++ /dev/null
@@ -1,160 +0,0 @@
1#
2# Run this Tcl script to generate the mingw.html file.
3#
4set rcsid {$Id: mingw.tcl,v 1.4 2003/03/30 18:58:58 drh Exp $}
5
6puts {<html>
7<head>
8 <title>Notes On How To Build MinGW As A Cross-Compiler</title>
9</head>
10<body bgcolor=white>
11<h1 align=center>
12Notes On How To Build MinGW As A Cross-Compiler
13</h1>}
14puts "<p align=center>
15(This page was last modified on [lrange $rcsid 3 4] UTC)
16</p>"
17
18puts {
19<p><a href="http://www.mingw.org/">MinGW</a> or
20<a href="http://www.mingw.org/">Minimalist GNU For Windows</a>
21is a version of the popular GCC compiler that builds Win95/Win98/WinNT
22binaries. See the website for details.</p>
23
24<p>This page describes how you can build MinGW
25from sources as a cross-compiler
26running under Linux. Doing so will allow you to construct
27WinNT binaries from the comfort and convenience of your
28Unix desktop.</p>
29}
30
31proc Link {path {file {}}} {
32 if {$file!=""} {
33 set path $path/$file
34 } else {
35 set file $path
36 }
37 puts "<a href=\"$path\">$file</a>"
38}
39
40puts {
41<p>Here are the steps:</p>
42
43<ol>
44<li>
45<p>Get a copy of source code. You will need the binutils, the
46compiler, and the MinGW runtime. Each are available separately.
47As of this writing, Mumit Khan has collected everything you need
48together in one FTP site:
49}
50set ftpsite \
51 ftp://ftp.nanotech.wisc.edu/pub/khan/gnu-win32/mingw32/snapshots/gcc-2.95.2-1
52Link $ftpsite
53puts {
54The three files you will need are:</p>
55<ul>
56<li>}
57Link $ftpsite binutils-19990818-1-src.tar.gz
58puts </li><li>
59Link $ftpsite gcc-2.95.2-1-src.tar.gz
60puts </li><li>
61Link $ftpsite mingw-20000203.zip
62puts {</li>
63</ul>
64
65<p>Put all the downloads in a directory out of the way. The sequel
66will assume all downloads are in a directory named
67<b>~/mingw/download</b>.</p>
68</li>
69
70<li>
71<p>
72Create a directory in which to install the new compiler suite and make
73the new directory writable.
74Depending on what directory you choose, you might need to become
75root. The example shell commands that follow
76will assume the installation directory is
77<b>/opt/mingw</b> and that your user ID is <b>drh</b>.</p>
78<blockquote><pre>
79su
80mkdir /opt/mingw
81chown drh /opt/mingw
82exit
83</pre></blockquote>
84</li>
85
86<li>
87<p>Unpack the source tarballs into a separate directory.</p>
88<blockquote><pre>
89mkdir ~/mingw/src
90cd ~/mingw/src
91tar xzf ../download/binutils-*.tar.gz
92tar xzf ../download/gcc-*.tar.gz
93unzip ../download/mingw-*.zip
94</pre></blockquote>
95</li>
96
97<li>
98<p>Create a directory in which to put all the build products.</p>
99<blockquote><pre>
100mkdir ~/mingw/bld
101</pre></blockquote>
102</li>
103
104<li>
105<p>Configure and build binutils and add the results to your PATH.</p>
106<blockquote><pre>
107mkdir ~/mingw/bld/binutils
108cd ~/mingw/bld/binutils
109../../src/binutils/configure --prefix=/opt/mingw --target=i386-mingw32 -v
110make 2&gt;&amp;1 | tee make.out
111make install 2&gt;&amp;1 | tee make-install.out
112export PATH=$PATH:/opt/mingw/bin
113</pre></blockquote>
114</li>
115
116<li>
117<p>Manually copy the runtime include files into the installation directory
118before trying to build the compiler.</p>
119<blockquote><pre>
120mkdir /opt/mingw/i386-mingw32/include
121cd ~/mingw/src/mingw-runtime*/mingw/include
122cp -r * /opt/mingw/i386-mingw32/include
123</pre></blockquote>
124</li>
125
126<li>
127<p>Configure and build the compiler</p>
128<blockquote><pre>
129mkdir ~/mingw/bld/gcc
130cd ~/mingw/bld/gcc
131../../src/gcc-*/configure --prefix=/opt/mingw --target=i386-mingw32 -v
132cd gcc
133make installdirs
134cd ..
135make 2&gt;&amp;1 | tee make.out
136make install
137</pre></blockquote>
138</li>
139
140<li>
141<p>Configure and build the MinGW runtime</p>
142<blockquote><pre>
143mkdir ~/mingw/bld/runtime
144cd ~/mingw/bld/runtime
145../../src/mingw-runtime*/configure --prefix=/opt/mingw --target=i386-mingw32 -v
146make install-target-w32api
147make install
148</pre></blockquote>
149</li>
150</ol>
151
152<p>And you are done...</p>
153}
154puts {
155<p><hr /></p>
156<p><a href="index.html"><img src="/goback.jpg" border=0 />
157Back to the SQLite Home Page</a>
158</p>
159
160</body></html>}
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/mkapidoc.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/mkapidoc.tcl
deleted file mode 100644
index 723f84a..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/mkapidoc.tcl
+++ /dev/null
@@ -1,176 +0,0 @@
1#!/usr/bin/tclsh
2#
3# Run this script redirecting the sqlite3.h file as standard
4# inputs and this script will generate API documentation.
5#
6set rcsid {$Id: mkapidoc.tcl,v 1.2 2007/06/20 09:09:48 danielk1977 Exp $}
7source common.tcl
8header {C/C++ Interface For SQLite Version 3}
9puts {
10<h2 class=pdf_section>C/C++ Interface For SQLite Version 3</h2>
11}
12
13# Scan standard input to extract the information we need
14# to build the documentation.
15#
16set title {}
17set type {}
18set body {}
19set code {}
20set phase 0
21set content {}
22while {![eof stdin]} {
23 set line [gets stdin]
24 if {$phase==0} {
25 # Looking for the CAPI3REF: keyword
26 if {[regexp {^\*\* CAPI3REF: +(.*)} $line all tx]} {
27 set title $tx
28 set phase 1
29 }
30 } elseif {$phase==1} {
31 if {[string range $line 0 1]=="**"} {
32 set lx [string trim [string range $line 3 end]]
33 if {[regexp {^CATEGORY: +([a-z]*)} $lx all cx]} {
34 set type $cx
35 } elseif {[regexp {^KEYWORDS: +(.*)} $lx all kx]} {
36 foreach k $kx {
37 set keyword($k) 1
38 }
39 } else {
40 append body $lx\n
41 }
42 } elseif {[string range $line 0 1]=="*/"} {
43 set phase 2
44 }
45 } elseif {$phase==2} {
46 if {$line==""} {
47 set kwlist [lsort [array names keyword]]
48 unset -nocomplain keyword
49 set key $type:$kwlist
50 lappend content [list $key $title $type $kwlist $body $code]
51 set title {}
52 set keywords {}
53 set type {}
54 set body {}
55 set code {}
56 set phase 0
57 } else {
58 if {[regexp {^#define (SQLITE_[A-Z0-9_]+)} $line all kx]} {
59 set type constant
60 set keyword($kx) 1
61 } elseif {[regexp {^typedef .* (sqlite[0-9a-z_]+);} $line all kx]} {
62 set type datatype
63 set keyword($kx) 1
64 } elseif {[regexp {^[a-z].*[ *](sqlite3_[a-z0-9_]+)\(} $line all kx]} {
65 set type function
66 set keyword($kx) 1
67 }
68 append code $line\n
69 }
70 }
71}
72
73# Output HTML that displays the given list in N columns
74#
75proc output_list {N lx} {
76 puts {<table width="100%" cellpadding="5"><tr>}
77 set len [llength $lx]
78 set n [expr {($len + $N - 1)/$N}]
79 for {set i 0} {$i<$N} {incr i} {
80 set start [expr {$i*$n}]
81 set end [expr {($i+1)*$n}]
82 puts {<td valign="top"><ul>}
83 for {set j $start} {$j<$end} {incr j} {
84 set entry [lindex $lx $j]
85 if {$entry!=""} {
86 foreach {link label} $entry break
87 puts "<li><a href=\"#$link\">$label</a></li>"
88 }
89 }
90 puts {</ul></td>}
91 }
92 puts {</tr></table>}
93}
94
95# Do a table of contents for objects
96#
97set objlist {}
98foreach c $content {
99 foreach {key title type keywords body code} $c break
100 if {$type!="datatype"} continue
101 set keywords [lsort $keywords]
102 set k [lindex $keywords 0]
103 foreach kw $keywords {
104 lappend objlist [list $k $kw]
105 }
106}
107puts {<h2>Datatypes:</h2>}
108output_list 3 $objlist
109puts {<hr>}
110
111# Do a table of contents for constants
112#
113set clist {}
114foreach c $content {
115 foreach {key title type keywords body code} $c break
116 if {$type!="constant"} continue
117 set keywords [lsort $keywords]
118 set k [lindex $keywords 0]
119 foreach kw $keywords {
120 lappend clist [list $k $kw]
121 }
122}
123puts {<h2>Constants:</h2>}
124set clist [lsort -index 1 $clist]
125output_list 3 $clist
126puts {<hr>}
127
128
129# Do a table of contents for functions
130#
131set funclist {}
132foreach c $content {
133 foreach {key title type keywords body code} $c break
134 if {$type!="function"} continue
135 set keywords [lsort $keywords]
136 set k [lindex $keywords 0]
137 foreach kw $keywords {
138 lappend funclist [list $k $kw]
139 }
140}
141puts {<h2>Functions:</h2>}
142set funclist [lsort -index 1 $funclist]
143output_list 3 $funclist
144puts {<hr>}
145
146# Resolve links
147#
148proc resolve_links {args} {
149 set tag [lindex $args 0]
150 regsub -all {[^a-zA-Z0-9_]} $tag {} tag
151 set x "<a href=\"#$tag\">"
152 if {[llength $args]>2} {
153 append x [lrange $args 2 end]</a>
154 } else {
155 append x [lindex $args 0]</a>
156 }
157 return $x
158}
159
160# Output all the records
161#
162foreach c [lsort $content] {
163 foreach {key title type keywords body code} $c break
164 foreach k $keywords {
165 puts "<a name=\"$k\"></a>"
166 }
167 puts "<h2>$title</h2>"
168 puts "<blockquote><pre>"
169 puts "$code"
170 puts "</pre></blockquote>"
171 regsub -all "\n\n+" $body {</p>\1<p>} body
172 regsub -all {\[} <p>$body</p> {[resolve_links } body
173 set body [subst -novar -noback $body]
174 puts "$body"
175 puts "<hr>"
176}
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/nulls.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/nulls.tcl
deleted file mode 100644
index 9091389..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/nulls.tcl
+++ /dev/null
@@ -1,329 +0,0 @@
1#
2# Run this script to generated a nulls.html output file
3#
4set rcsid {$Id: nulls.tcl,v 1.8 2004/10/10 17:24:55 drh Exp $}
5source common.tcl
6header {NULL Handling in SQLite}
7puts {
8<h2>NULL Handling in SQLite Versus Other Database Engines</h2>
9
10<p>
11The goal is
12to make SQLite handle NULLs in a standards-compliant way.
13But the descriptions in the SQL standards on how to handle
14NULLs seem ambiguous.
15It is not clear from the standards documents exactly how NULLs should
16be handled in all circumstances.
17</p>
18
19<p>
20So instead of going by the standards documents, various popular
21SQL engines were tested to see how they handle NULLs. The idea
22was to make SQLite work like all the other engines.
23A SQL test script was developed and run by volunteers on various
24SQL RDBMSes and the results of those tests were used to deduce
25how each engine processed NULL values.
26The original tests were run in May of 2002.
27A copy of the test script is found at the end of this document.
28</p>
29
30<p>
31SQLite was originally coded in such a way that the answer to
32all questions in the chart below would be "Yes". But the
33experiments run on other SQL engines showed that none of them
34worked this way. So SQLite was modified to work the same as
35Oracle, PostgreSQL, and DB2. This involved making NULLs
36indistinct for the purposes of the SELECT DISTINCT statement and
37for the UNION operator in a SELECT. NULLs are still distinct
38in a UNIQUE column. This seems somewhat arbitrary, but the desire
39to be compatible with other engines outweighted that objection.
40</p>
41
42<p>
43It is possible to make SQLite treat NULLs as distinct for the
44purposes of the SELECT DISTINCT and UNION. To do so, one should
45change the value of the NULL_ALWAYS_DISTINCT #define in the
46<tt>sqliteInt.h</tt> source file and recompile.
47</p>
48
49<blockquote>
50<p>
51<i>Update 2003-07-13:</i>
52Since this document was originally written some of the database engines
53tested have been updated and users have been kind enough to send in
54corrections to the chart below. The original data showed a wide variety
55of behaviors, but over time the range of behaviors has converged toward
56the PostgreSQL/Oracle model. The only significant difference
57is that Informix and MS-SQL both threat NULLs as
58indistinct in a UNIQUE column.
59</p>
60
61<p>
62The fact that NULLs are distinct for UNIQUE columns but are indistinct for
63SELECT DISTINCT and UNION continues to be puzzling. It seems that NULLs
64should be either distinct everywhere or nowhere. And the SQL standards
65documents suggest that NULLs should be distinct everywhere. Yet as of
66this writing, no SQL engine tested treats NULLs as distinct in a SELECT
67DISTINCT statement or in a UNION.
68</p>
69</blockquote>
70
71
72<p>
73The following table shows the results of the NULL handling experiments.
74</p>
75
76<table border=1 cellpadding=3 width="100%">
77<tr><th>&nbsp&nbsp;</th>
78<th>SQLite</th>
79<th>PostgreSQL</th>
80<th>Oracle</th>
81<th>Informix</th>
82<th>DB2</th>
83<th>MS-SQL</th>
84<th>OCELOT</th>
85</tr>
86
87<tr><td>Adding anything to null gives null</td>
88<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
89<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
90<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
91<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
92<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
93<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
94<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
95</tr>
96<tr><td>Multiplying null by zero gives null</td>
97<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
98<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
99<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
100<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
101<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
102<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
103<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
104</tr>
105<tr><td>nulls are distinct in a UNIQUE column</td>
106<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
107<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
108<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
109<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
110<td valign="center" align="center" bgcolor="#aaaad2">(Note 4)</td>
111<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
112<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
113</tr>
114<tr><td>nulls are distinct in SELECT DISTINCT</td>
115<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
116<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
117<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
118<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
119<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
120<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
121<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
122</tr>
123<tr><td>nulls are distinct in a UNION</td>
124<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
125<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
126<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
127<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
128<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
129<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
130<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
131</tr>
132<tr><td>"CASE WHEN null THEN 1 ELSE 0 END" is 0?</td>
133<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
134<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
135<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
136<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
137<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
138<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
139<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
140</tr>
141<tr><td>"null OR true" is true</td>
142<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
143<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
144<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
145<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
146<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
147<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
148<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
149</tr>
150<tr><td>"not (null AND false)" is true</td>
151<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
152<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
153<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
154<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
155<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
156<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
157<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
158</tr>
159</table>
160
161<table border=1 cellpadding=3 width="100%">
162<tr><th>&nbsp&nbsp;</th>
163<th>MySQL<br>3.23.41</th>
164<th>MySQL<br>4.0.16</th>
165<th>Firebird</th>
166<th>SQL<br>Anywhere</th>
167<th>Borland<br>Interbase</th>
168</tr>
169
170<tr><td>Adding anything to null gives null</td>
171<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
172<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
173<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
174<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
175<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
176</tr>
177<tr><td>Multiplying null by zero gives null</td>
178<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
179<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
180<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
181<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
182<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
183</tr>
184<tr><td>nulls are distinct in a UNIQUE column</td>
185<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
186<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
187<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
188<td valign="center" align="center" bgcolor="#aaaad2">(Note 4)</td>
189<td valign="center" align="center" bgcolor="#aaaad2">(Note 4)</td>
190</tr>
191<tr><td>nulls are distinct in SELECT DISTINCT</td>
192<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
193<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
194<td valign="center" align="center" bgcolor="#c7a9a9">No (Note 1)</td>
195<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
196<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
197</tr>
198<tr><td>nulls are distinct in a UNION</td>
199<td valign="center" align="center" bgcolor="#aaaad2">(Note 3)</td>
200<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
201<td valign="center" align="center" bgcolor="#c7a9a9">No (Note 1)</td>
202<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
203<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
204</tr>
205<tr><td>"CASE WHEN null THEN 1 ELSE 0 END" is 0?</td>
206<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
207<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
208<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
209<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
210<td valign="center" align="center" bgcolor="#aaaad2">(Note 5)</td>
211</tr>
212<tr><td>"null OR true" is true</td>
213<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
214<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
215<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
216<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
217<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
218</tr>
219<tr><td>"not (null AND false)" is true</td>
220<td valign="center" align="center" bgcolor="#c7a9a9">No</td>
221<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
222<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
223<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
224<td valign="center" align="center" bgcolor="#a9c7a9">Yes</td>
225</tr>
226</table>
227
228<table border=0 align="right" cellpadding=0 cellspacing=0>
229<tr>
230<td valign="top" rowspan=5>Notes:&nbsp;&nbsp;</td>
231<td>1.&nbsp;</td>
232<td>Older versions of firebird omits all NULLs from SELECT DISTINCT
233and from UNION.</td>
234</tr>
235<tr><td>2.&nbsp;</td>
236<td>Test data unavailable.</td>
237</tr>
238<tr><td>3.&nbsp;</td>
239<td>MySQL version 3.23.41 does not support UNION.</td>
240</tr>
241<tr><td>4.&nbsp;</td>
242<td>DB2, SQL Anywhere, and Borland Interbase
243do not allow NULLs in a UNIQUE column.</td>
244</tr>
245<tr><td>5.&nbsp;</td>
246<td>Borland Interbase does not support CASE expressions.</td>
247</tr>
248</table>
249<br clear="both">
250
251<p>&nbsp;</p>
252<p>
253The following script was used to gather information for the table
254above.
255</p>
256
257<pre>
258-- I have about decided that SQL's treatment of NULLs is capricious and cannot be
259-- deduced by logic. It must be discovered by experiment. To that end, I have
260-- prepared the following script to test how various SQL databases deal with NULL.
261-- My aim is to use the information gather from this script to make SQLite as much
262-- like other databases as possible.
263--
264-- If you could please run this script in your database engine and mail the results
265-- to me at drh@hwaci.com, that will be a big help. Please be sure to identify the
266-- database engine you use for this test. Thanks.
267--
268-- If you have to change anything to get this script to run with your database
269-- engine, please send your revised script together with your results.
270--
271
272-- Create a test table with data
273create table t1(a int, b int, c int);
274insert into t1 values(1,0,0);
275insert into t1 values(2,0,1);
276insert into t1 values(3,1,0);
277insert into t1 values(4,1,1);
278insert into t1 values(5,null,0);
279insert into t1 values(6,null,1);
280insert into t1 values(7,null,null);
281
282-- Check to see what CASE does with NULLs in its test expressions
283select a, case when b<>0 then 1 else 0 end from t1;
284select a+10, case when not b<>0 then 1 else 0 end from t1;
285select a+20, case when b<>0 and c<>0 then 1 else 0 end from t1;
286select a+30, case when not (b<>0 and c<>0) then 1 else 0 end from t1;
287select a+40, case when b<>0 or c<>0 then 1 else 0 end from t1;
288select a+50, case when not (b<>0 or c<>0) then 1 else 0 end from t1;
289select a+60, case b when c then 1 else 0 end from t1;
290select a+70, case c when b then 1 else 0 end from t1;
291
292-- What happens when you multiple a NULL by zero?
293select a+80, b*0 from t1;
294select a+90, b*c from t1;
295
296-- What happens to NULL for other operators?
297select a+100, b+c from t1;
298
299-- Test the treatment of aggregate operators
300select count(*), count(b), sum(b), avg(b), min(b), max(b) from t1;
301
302-- Check the behavior of NULLs in WHERE clauses
303select a+110 from t1 where b<10;
304select a+120 from t1 where not b>10;
305select a+130 from t1 where b<10 OR c=1;
306select a+140 from t1 where b<10 AND c=1;
307select a+150 from t1 where not (b<10 AND c=1);
308select a+160 from t1 where not (c=1 AND b<10);
309
310-- Check the behavior of NULLs in a DISTINCT query
311select distinct b from t1;
312
313-- Check the behavior of NULLs in a UNION query
314select b from t1 union select b from t1;
315
316-- Create a new table with a unique column. Check to see if NULLs are considered
317-- to be distinct.
318create table t2(a int, b int unique);
319insert into t2 values(1,1);
320insert into t2 values(2,null);
321insert into t2 values(3,null);
322select * from t2;
323
324drop table t1;
325drop table t2;
326</pre>
327}
328
329footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/oldnews.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/oldnews.tcl
deleted file mode 100644
index 6bbb71e..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/oldnews.tcl
+++ /dev/null
@@ -1,485 +0,0 @@
1#!/usr/bin/tclsh
2source common.tcl
3header {SQLite Older News}
4
5proc newsitem {date title text} {
6 puts "<h3>$date - $title</h3>"
7 regsub -all "\n( *\n)+" $text "</p>\n\n<p>" txt
8 puts "<p>$txt</p>"
9 puts "<hr width=\"50%\">"
10}
11
12newsitem {2007-Jun-18} {Version 3.4.0} {
13 This release fixes two separate bugs either of which
14 can lead to database corruption. Upgrading
15 is strongly recommended. If you must continue using an older version
16 of SQLite, please at least read about how to avoid these bugs
17 at
18 <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">
19 CorruptionFollowingBusyError</a> and
20 <a href="http://www.sqlite.org/cvstrac/tktview?tn=2418">ticket #2418</a>
21 <p>
22 This release also adds explicit <a href="limits.html">limits</a> on the
23 sizes and quantities of things SQLite will handle. The new limits might
24 causes compatibility problems for existing applications that
25 use excessively large strings, BLOBs, tables, or SQL statements.
26 The new limits can be increased at compile-time to work around any problems
27 that arise. Nevertheless, the version number of this release is
28 3.4.0 instead of 3.3.18 in order to call attention to the possible
29 incompatibility.
30 </p>
31 There are also new features, including
32 <a href="capi3ref.html#sqlite3_blob_open">incremental BLOB I/O</a> and
33 <a href="pragma.html#pragma_incremental_vacuum">incremental vacuum</a>.
34 See the <a href="changes.html#version_3_4_0">change log</a>
35 for additional information.
36}
37
38newsitem {2007-Apr-25} {Version 3.3.17} {
39 This version fixes a bug in the forwards-compatibility logic of SQLite
40 that was causing a database to become unreadable when it should have
41 been read-only. Upgrade from 3.3.16 only if you plan to deploy into
42 a product that might need to be upgraded in the future. For day to day
43 use, it probably does not matter.
44}
45
46newsitem {2007-Apr-18} {Version 3.3.16} {
47 Performance improvements added in 3.3.14 but mistakenly turned off
48 in 3.3.15 have been reinstated. A bug has been fixed that prevented
49 VACUUM from running if a NULL value was in a UNIQUE column.
50}
51
52newsitem {2007-Apr-09} {Version 3.3.15} {
53 An annoying bug introduced in 3.3.14 has been fixed. There are
54 also many enhancements to the test suite.
55}
56
57newsitem {2007-Apr-02} {Version 3.3.14} {
58 This version focuses on performance improvements. If you recompile
59 <a href="http://www.sqlite.org/cvstrac/wiki?p=TheAmalgamation">
60 the amalgamation</a> using GCC option -O3 (the precompiled binaries
61 use -O2) you may see performance
62 improvements of 35% or more over version 3.3.13 depending on your
63 workload. This version also
64 adds support for <a href="pragma.html#pragma_locking_mode">
65 exclusive access mode</a>.
66}
67
68newsitem {2007-Feb-13} {Version 3.3.13} {
69 This version fixes a subtle bug in the ORDER BY optimizer that can
70 occur when using joins. There are also a few minor enhancements.
71 Upgrading is recommended.
72}
73
74newsitem {2007-Jan-27} {Version 3.3.12} {
75 The first published build of the previous version used the wrong
76 set of source files. Consequently, many people downloaded a build
77 that was labeled as "3.3.11" but was really 3.3.10. Version 3.3.12
78 is released to clear up the ambiguity. A couple more bugs have
79 also been fixed and <a href="pragma.html#pragma_integrity_check">
80 PRAGMA integrity_check</a> has been enhanced.
81}
82
83newsitem {2007-Jan-22} {Version 3.3.11} {
84 Version 3.3.11 fixes for a few more problems in version 3.3.9 that
85 version 3.3.10 failed to catch. Upgrading is recommended.
86}
87
88newsitem {2007-Jan-9} {Version 3.3.10} {
89 Version 3.3.10 fixes several bugs that were introduced by the previous
90 release. Upgrading is recommended.
91}
92
93newsitem {2007-Jan-4} {Version 3.3.9} {
94 Version 3.3.9 fixes bugs that can lead to database corruption under
95 obscure and difficult to reproduce circumstances. See
96 <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption">
97 DatabaseCorruption</a> in the
98 <a href="http://www.sqlite.org/cvstrac/wiki">wiki</a> for details.
99 This release also adds the new
100 <a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a>
101 API and includes important bug fixes in the command-line
102 shell and enhancements to the query optimizer. Upgrading is
103 recommended.
104}
105
106newsitem {2006-Oct-9} {Version 3.3.8} {
107 Version 3.3.8 adds support for full-text search using the
108 <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsOne">FTS1
109 module.</a> There are also minor bug fixes. Upgrade only if
110 you want to try out the new full-text search capabilities or if
111 you are having problems with 3.3.7.
112}
113
114newsitem {2006-Aug-12} {Version 3.3.7} {
115 Version 3.3.7 includes support for loadable extensions and virtual
116 tables. But both features are still considered "beta" and their
117 APIs are subject to change in a future release. This release is
118 mostly to make available the minor bug fixes that have accumulated
119 since 3.3.6. Upgrading is not necessary. Do so only if you encounter
120 one of the obscure bugs that have been fixed or if you want to try
121 out the new features.
122}
123
124newsitem {2006-Jun-19} {New Book About SQLite} {
125 <a href="http://www.apress.com/book/bookDisplay.html?bID=10130">
126 <i>The Definitive Guide to SQLite</i></a>, a new book by
127 <a href="http://www.mikesclutter.com">Mike Owens</a>.
128 is now available from <a href="http://www.apress.com">Apress</a>.
129 The books covers the latest SQLite internals as well as
130 the native C interface and bindings for PHP, Python,
131 Perl, Ruby, Tcl, and Java. Recommended.
132}
133
134
135newsitem {2006-Jun-6} {Version 3.3.6} {
136 Changes include improved tolerance for windows virus scanners
137 and faster :memory: databases. There are also fixes for several
138 obscure bugs. Upgrade if you are having problems.
139}
140
141newsitem {2006-Apr-5} {Version 3.3.5} {
142 This release fixes many minor bugs and documentation typos and
143 provides some minor new features and performance enhancements.
144 Upgrade only if you are having problems or need one of the new features.
145}
146
147newsitem {2006-Feb-11} {Version 3.3.4} {
148 This release fixes several bugs, including a
149 a blunder that might cause a deadlock on multithreaded systems.
150 Anyone using SQLite in a multithreaded environment should probably upgrade.
151}
152
153newsitem {2006-Jan-31} {Version 3.3.3 stable} {
154 There have been no major problems discovered in version 3.3.2, so
155 we hereby declare the new APIs and language features to be stable
156 and supported.
157}
158
159newsitem {2006-Jan-24} {Version 3.3.2 beta} {
160 More bug fixes and performance improvements as we move closer to
161 a production-ready version 3.3.x.
162}
163
164newsitem {2006-Jan-16} {Version 3.3.1 alpha} {
165 Many bugs found in last week's alpha release have now been fixed and
166 the library is running much faster again.
167
168 Database connections can now be moved between threads as long as the
169 connection holds no locks at the time it is moved. Thus the common
170 paradigm of maintaining a pool of database connections and handing
171 them off to transient worker threads is now supported.
172 Please help test this new feature.
173 See <a href="http://www.sqlite.org/cvstrac/wiki?p=MultiThreading">
174 the MultiThreading wiki page</a> for additional
175 information.
176}
177
178newsitem {2006-Jan-10} {Version 3.3.0 alpha} {
179 Version 3.3.0 adds support for CHECK constraints, DESC indices,
180 separate REAL and INTEGER column affinities, a new OS interface layer
181 design, and many other changes. The code passed a regression
182 test but should still be considered alpha. Please report any
183 problems.
184
185 The file format for version 3.3.0 has changed slightly to support
186 descending indices and
187 a more efficient encoding of boolean values. SQLite 3.3.0 will read and
188 write legacy databases created with any prior version of SQLite 3. But
189 databases created by version 3.3.0 will not be readable or writable
190 by earlier versions of the SQLite. The older file format can be
191 specified at compile-time for those rare cases where it is needed.
192}
193
194newsitem {2005-Dec-19} {Versions 3.2.8 and 2.8.17} {
195 These versions contain one-line changes to 3.2.7 and 2.8.16 to fix a bug
196 that has been present since March of 2002 and version 2.4.0.
197 That bug might possibly cause database corruption if a large INSERT or
198 UPDATE statement within a multi-statement transaction fails due to a
199 uniqueness constraint but the containing transaction commits.
200}
201
202
203newsitem {2005-Sep-24} {Version 3.2.7} {
204 This version fixes several minor and obscure bugs.
205 Upgrade only if you are having problems.
206}
207
208newsitem {2005-Sep-16} {Version 3.2.6 - Critical Bug Fix} {
209 This version fixes a bug that can result in database
210 corruption if a VACUUM of a 1 gibibyte or larger database fails
211 (perhaps do to running out of disk space or an unexpected power loss)
212 and is later rolled back.
213 <p>
214 Also in this release:
215 The ORDER BY and GROUP BY processing was rewritten to use less memory.
216 Support for COUNT(DISTINCT) was added. The LIKE operator can now be
217 used by the optimizer on columns with COLLATE NOCASE.
218}
219
220newsitem {2005-Aug-27} {Version 3.2.5} {
221 This release fixes a few more lingering bugs in the new code.
222 We expect that this release will be stable and ready for production use.
223}
224
225newsitem {2005-Aug-24} {Version 3.2.4} {
226 This release fixes a bug in the new optimizer that can lead to segfaults
227 when parsing very complex WHERE clauses.
228}
229
230newsitem {2005-Aug-21} {Version 3.2.3} {
231 This release adds the <a href="lang_analyze.html">ANALYZE</a> command,
232 the <a href="lang_expr.html">CAST</a> operator, and many
233 very substantial improvements to the query optimizer. See the
234 <a href="changes.html#version_3_2_3">change log</a> for additional
235 information.
236}
237
238newsitem {2005-Aug-2} {2005 Open Source Award for SQLite} {
239 SQLite and its primary author D. Richard Hipp have been honored with
240 a <a href="http://osdir.com/Article6677.phtml">2005 Open Source
241 Award</a> from Google and O'Reilly.<br clear="right">
242}
243
244
245newsitem {2005-Jun-13} {Version 3.2.2} {
246 This release includes numerous minor bug fixes, speed improvements,
247 and code size reductions. There is no reason to upgrade unless you
248 are having problems or unless you just want to.
249}
250
251newsitem {2005-Mar-29} {Version 3.2.1} {
252 This release fixes a memory allocation problem in the new
253 <a href="lang_altertable.html">ALTER TABLE ADD COLUMN</a>
254 command.
255}
256
257newsitem {2005-Mar-21} {Version 3.2.0} {
258 The primary purpose for version 3.2.0 is to add support for
259 <a href="lang_altertable.html">ALTER TABLE ADD COLUMN</a>.
260 The new ADD COLUMN capability is made
261 possible by AOL developers supporting and embracing great
262 open-source software. Thanks, AOL!
263
264 Version 3.2.0 also fixes an obscure but serious bug that was discovered
265 just prior to release. If you have a multi-statement transaction and
266 within that transaction an UPDATE or INSERT statement fails due to a
267 constraint, then you try to rollback the whole transaction, the rollback
268 might not work correctly. See
269 <a href="http://www.sqlite.org/cvstrac/tktview?tn=1171">Ticket #1171</a>
270 for details. Upgrading is recommended for all users.
271}
272
273newsitem {2005-Mar-16} {Version 3.1.6} {
274 Version 3.1.6 fixes a critical bug that can cause database corruption
275 when inserting rows into tables with around 125 columns. This bug was
276 introduced in version 3.0.0. See
277 <a href="http://www.sqlite.org/cvstrac/tktview?tn=1163">Ticket #1163</a>
278 for additional information.
279}
280
281newsitem {2005-Mar-11} {Versions 3.1.4 and 3.1.5 Released} {
282 Version 3.1.4 fixes a critical bug that could cause database corruption
283 if the autovacuum mode of version 3.1.0 is turned on (it is off by
284 default) and a CREATE UNIQUE INDEX is executed within a transaction but
285 fails because the indexed columns are not unique. Anyone using the
286 autovacuum feature and unique indices should upgrade.
287
288 Version 3.1.5 adds the ability to disable
289 the F_FULLFSYNC ioctl() in OS-X by setting "PRAGMA synchronous=on" instead
290 of the default "PRAGMA synchronous=full". There was an attempt to add
291 this capability in 3.1.4 but it did not work due to a spelling error.
292}
293
294newsitem {2005-Feb-19} {Version 3.1.3 Released} {
295 Version 3.1.3 cleans up some minor issues discovered in version 3.1.2.
296}
297
298newsitem {2005-Feb-15} {Versions 2.8.16 and 3.1.2 Released} {
299 A critical bug in the VACUUM command that can lead to database
300 corruption has been fixed in both the 2.x branch and the main
301 3.x line. This bug has existed in all prior versions of SQLite.
302 Even though it is unlikely you will ever encounter this bug,
303 it is suggested that all users upgrade. See
304 <a href="http://www.sqlite.org/cvstrac/tktview?tn=1116">
305 ticket #1116</a>. for additional information.
306
307 Version 3.1.2 is also the first stable release of the 3.1
308 series. SQLite 3.1 features added support for correlated
309 subqueries, autovacuum, autoincrement, ALTER TABLE, and
310 other enhancements. See the
311 <a href="http://www.sqlite.org/releasenotes310.html">release notes
312 for version 3.1.0</a> for a detailed description of the
313 changes available in the 3.1 series.
314}
315
316newsitem {2005-Feb-01} {Version 3.1.1 (beta) Released} {
317 Version 3.1.1 (beta) is now available on the
318 website. Verison 3.1.1 is fully backwards compatible with the 3.0 series
319 and features many new features including Autovacuum and correlated
320 subqueries. The
321 <a href="http://www.sqlite.org/releasenotes310.html">release notes</a>
322 From version 3.1.0 apply equally to this release beta. A stable release
323 is expected within a couple of weeks.
324}
325
326newsitem {2005-Jan-21} {Version 3.1.0 (alpha) Released} {
327 Version 3.1.0 (alpha) is now available on the
328 website. Verison 3.1.0 is fully backwards compatible with the 3.0 series
329 and features many new features including Autovacuum and correlated
330 subqueries. See the
331 <a href="http://www.sqlite.org/releasenotes310.html">release notes</a>
332 for details.
333
334 This is an alpha release. A beta release is expected in about a week
335 with the first stable release to follow after two more weeks.
336}
337
338newsitem {2004-Nov-09} {SQLite at the 2004 International PHP Conference} {
339 There was a talk on the architecture of SQLite and how to optimize
340 SQLite queries at the 2004 International PHP Conference in Frankfurt,
341 Germany.
342 <a href="http://www.sqlite.org/php2004/page-001.html">
343 Slides</a> from that talk are available.
344}
345
346newsitem {2004-Oct-11} {Version 3.0.8} {
347 Version 3.0.8 of SQLite contains several code optimizations and minor
348 bug fixes and adds support for DEFERRED, IMMEDIATE, and EXCLUSIVE
349 transactions. This is an incremental release. There is no reason
350 to upgrade from version 3.0.7 if that version is working for you.
351}
352
353
354newsitem {2004-Oct-10} {SQLite at the 11<sup><small>th</small></sup>
355Annual Tcl/Tk Conference} {
356 There will be a talk on the use of SQLite in Tcl/Tk at the
357 11<sup><small>th</small></sup> Tcl/Tk Conference this week in
358 New Orleans. Visit <a href="http://www.tcl.tk/community/tcl2004/">
359 http://www.tcl.tk/</a> for details.
360 <a href="http://www.sqlite.org/tclconf2004/page-001.html">
361 Slides</a> from the talk are available.
362}
363
364newsitem {2004-Sep-18} {Version 3.0.7} {
365 Version 3.0 has now been in use by multiple projects for several
366 months with no major difficulties. We consider it stable and
367 ready for production use.
368}
369
370newsitem {2004-Sep-02} {Version 3.0.6 (beta)} {
371 Because of some important changes to sqlite3_step(),
372 we have decided to
373 do an additional beta release prior to the first "stable" release.
374 If no serious problems are discovered in this version, we will
375 release version 3.0 "stable" in about a week.
376}
377
378
379newsitem {2004-Aug-29} {Version 3.0.5 (beta)} {
380 The fourth beta release of SQLite version 3.0 is now available.
381 The next release is expected to be called "stable".
382}
383
384
385newsitem {2004-Aug-08} {Version 3.0.4 (beta)} {
386 The third beta release of SQLite version 3.0 is now available.
387 This new beta fixes several bugs including a database corruption
388 problem that can occur when doing a DELETE while a SELECT is pending.
389 Expect at least one more beta before version 3.0 goes final.
390}
391
392newsitem {2004-July-22} {Version 3.0.3 (beta)} {
393 The second beta release of SQLite version 3.0 is now available.
394 This new beta fixes many bugs and adds support for databases with
395 varying page sizes. The next 3.0 release will probably be called
396 a final or stable release.
397
398 Version 3.0 adds support for internationalization and a new
399 more compact file format.
400 <a href="version3.html">Details.</a>
401 The API and file format have been fixed since 3.0.2. All
402 regression tests pass (over 100000 tests) and the test suite
403 exercises over 95% of the code.
404
405 SQLite version 3.0 is made possible in part by AOL
406 developers supporting and embracing great Open-Source Software.
407}
408
409newsitem {2004-Jly-22} {Version 2.8.15} {
410 SQLite version 2.8.15 is a maintenance release for the version 2.8
411 series. Version 2.8 continues to be maintained with bug fixes, but
412 no new features will be added to version 2.8. All the changes in
413 this release are minor. If you are not having problems, there is
414 there is no reason to upgrade.
415}
416
417newsitem {2004-Jun-30} {Version 3.0.2 (beta) Released} {
418 The first beta release of SQLite version 3.0 is now available.
419 Version 3.0 adds support for internationalization and a new
420 more compact file format.
421 <a href="version3.html">Details.</a>
422 As of this release, the API and file format are frozen. All
423 regression tests pass (over 100000 tests) and the test suite
424 exercises over 95% of the code.
425
426 SQLite version 3.0 is made possible in part by AOL
427 developers supporting and embracing great Open-Source Software.
428}
429
430
431newsitem {2004-Jun-25} {Website hacked} {
432 The www.sqlite.org website was hacked sometime around 2004-Jun-22
433 because the lead SQLite developer failed to properly patch CVS.
434 Evidence suggests that the attacker was unable to elevate privileges
435 above user "cvs". Nevertheless, as a precaution the entire website
436 has been reconstructed from scratch on a fresh machine. All services
437 should be back to normal as of 2004-Jun-28.
438}
439
440
441newsitem {2004-Jun-18} {Version 3.0.0 (alpha) Released} {
442 The first alpha release of SQLite version 3.0 is available for
443 public review and comment. Version 3.0 enhances internationalization support
444 through the use of UTF-16 and user-defined text collating sequences.
445 BLOBs can now be stored directly, without encoding.
446 A new file format results in databases that are 25% smaller (depending
447 on content). The code is also a little faster. In spite of the many
448 new features, the library footprint is still less than 240KB
449 (x86, gcc -O1).
450 <a href="version3.html">Additional information</a>.
451
452 Our intent is to freeze the file format and API on 2004-Jul-01.
453 Users are encouraged to review and evaluate this alpha release carefully
454 and submit any feedback prior to that date.
455
456 The 2.8 series of SQLite will continue to be supported with bug
457 fixes for the foreseeable future.
458}
459
460newsitem {2004-Jun-09} {Version 2.8.14 Released} {
461 SQLite version 2.8.14 is a patch release to the stable 2.8 series.
462 There is no reason to upgrade if 2.8.13 is working ok for you.
463 This is only a bug-fix release. Most development effort is
464 going into version 3.0.0 which is due out soon.
465}
466
467newsitem {2004-May-31} {CVS Access Temporarily Disabled} {
468 Anonymous access to the CVS repository will be suspended
469 for 2 weeks beginning on 2004-June-04. Everyone will still
470 be able to download
471 prepackaged source bundles, create or modify trouble tickets, or view
472 change logs during the CVS service interruption. Full open access to the
473 CVS repository will be restored on 2004-June-18.
474}
475
476newsitem {2004-Apr-23} {Work Begins On SQLite Version 3} {
477 Work has begun on version 3 of SQLite. Version 3 is a major
478 changes to both the C-language API and the underlying file format
479 that will enable SQLite to better support internationalization.
480 The first beta is schedule for release on 2004-July-01.
481
482 Plans are to continue to support SQLite version 2.8 with
483 bug fixes. But all new development will occur in version 3.0.
484}
485footer {$Id: oldnews.tcl,v 1.23 2007/09/04 01:58:27 drh Exp $}
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/omitted.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/omitted.tcl
deleted file mode 100644
index 23241e7..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/omitted.tcl
+++ /dev/null
@@ -1,85 +0,0 @@
1#
2# Run this script to generated a omitted.html output file
3#
4set rcsid {$Id: omitted.tcl,v 1.10 2005/11/03 00:41:18 drh Exp $}
5source common.tcl
6header {SQL Features That SQLite Does Not Implement}
7puts {
8<h2>SQL Features That SQLite Does Not Implement</h2>
9
10<p>
11Rather than try to list all the features of SQL92 that SQLite does
12support, it is much easier to list those that it does not.
13Unsupported features of SQL92 are shown below.</p>
14
15<p>
16The order of this list gives some hint as to when a feature might
17be added to SQLite. Those features near the top of the list are
18likely to be added in the near future. There are no immediate
19plans to add features near the bottom of the list.
20</p>
21
22<table cellpadding="10">
23}
24
25proc feature {name desc} {
26 puts "<tr><td valign=\"top\"><b><nobr>$name</nobr></b></td>"
27 puts "<td width=\"10\">&nbsp;</th>"
28 puts "<td valign=\"top\">$desc</td></tr>"
29}
30
31feature {FOREIGN KEY constraints} {
32 FOREIGN KEY constraints are parsed but are not enforced.
33}
34
35feature {Complete trigger support} {
36 There is some support for triggers but it is not complete. Missing
37 subfeatures include FOR EACH STATEMENT triggers (currently all triggers
38 must be FOR EACH ROW), INSTEAD OF triggers on tables (currently
39 INSTEAD OF triggers are only allowed on views), and recursive
40 triggers - triggers that trigger themselves.
41}
42
43feature {Complete ALTER TABLE support} {
44 Only the RENAME TABLE and ADD COLUMN variants of the
45 ALTER TABLE command are supported. Other kinds of ALTER TABLE operations
46 such as
47 DROP COLUMN, ALTER COLUMN, ADD CONSTRAINT, and so forth are omitted.
48}
49
50feature {Nested transactions} {
51 The current implementation only allows a single active transaction.
52}
53
54feature {RIGHT and FULL OUTER JOIN} {
55 LEFT OUTER JOIN is implemented, but not RIGHT OUTER JOIN or
56 FULL OUTER JOIN.
57}
58
59feature {Writing to VIEWs} {
60 VIEWs in SQLite are read-only. You may not execute a DELETE, INSERT, or
61 UPDATE statement on a view. But you can create a trigger
62 that fires on an attempt to DELETE, INSERT, or UPDATE a view and do
63 what you need in the body of the trigger.
64}
65
66feature {GRANT and REVOKE} {
67 Since SQLite reads and writes an ordinary disk file, the
68 only access permissions that can be applied are the normal
69 file access permissions of the underlying operating system.
70 The GRANT and REVOKE commands commonly found on client/server
71 RDBMSes are not implemented because they would be meaningless
72 for an embedded database engine.
73}
74
75puts {
76</table>
77
78<p>
79If you find other SQL92 features that SQLite does not support, please
80add them to the Wiki page at
81<a href="http://www.sqlite.org/cvstrac/wiki?p=UnsupportedSql">
82http://www.sqlite.org/cvstrac/wiki?p=Unsupported</a>
83</p>
84}
85footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/opcode.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/opcode.tcl
deleted file mode 100644
index f28534f..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/opcode.tcl
+++ /dev/null
@@ -1,243 +0,0 @@
1#
2# Run this Tcl script to generate the sqlite.html file.
3#
4set rcsid {$Id: opcode.tcl,v 1.15 2005/03/09 12:26:51 danielk1977 Exp $}
5source common.tcl
6header {SQLite Virtual Machine Opcodes}
7puts {
8<h2>SQLite Virtual Machine Opcodes</h2>
9}
10
11set fd [open [lindex $argv 0] r]
12set file [read $fd [file size [lindex $argv 0]]]
13close $fd
14set current_op {}
15foreach line [split $file \n] {
16 set line [string trim $line]
17 if {[string index $line 1]!="*"} {
18 set current_op {}
19 continue
20 }
21 if {[regexp {^/\* Opcode: } $line]} {
22 set current_op [lindex $line 2]
23 set txt [lrange $line 3 end]
24 regsub -all {>} $txt {\&gt;} txt
25 regsub -all {<} $txt {\&lt;} txt
26 set Opcode($current_op:args) $txt
27 lappend OpcodeList $current_op
28 continue
29 }
30 if {$current_op==""} continue
31 if {[regexp {^\*/} $line]} {
32 set current_op {}
33 continue
34 }
35 set line [string trim [string range $line 3 end]]
36 if {$line==""} {
37 append Opcode($current_op:text) \n<p>
38 } else {
39 regsub -all {>} $line {\&gt;} line
40 regsub -all {<} $line {\&lt;} line
41 append Opcode($current_op:text) \n$line
42 }
43}
44unset file
45
46puts {
47<h3>Introduction</h3>
48
49<p>In order to execute an SQL statement, the SQLite library first parses
50the SQL, analyzes the statement, then generates a short program to execute
51the statement. The program is generated for a "virtual machine" implemented
52by the SQLite library. This document describes the operation of that
53virtual machine.</p>
54
55<p>This document is intended as a reference, not a tutorial.
56A separate <a href="vdbe.html">Virtual Machine Tutorial</a> is
57available. If you are looking for a narrative description
58of how the virtual machine works, you should read the tutorial
59and not this document. Once you have a basic idea of what the
60virtual machine does, you can refer back to this document for
61the details on a particular opcode.
62Unfortunately, the virtual machine tutorial was written for
63SQLite version 1.0. There are substantial changes in the virtual
64machine for version 2.0 and the document has not been updated.
65</p>
66
67<p>The source code to the virtual machine is in the <b>vdbe.c</b> source
68file. All of the opcode definitions further down in this document are
69contained in comments in the source file. In fact, the opcode table
70in this document
71was generated by scanning the <b>vdbe.c</b> source file
72and extracting the necessary information from comments. So the
73source code comments are really the canonical source of information
74about the virtual machine. When in doubt, refer to the source code.</p>
75
76<p>Each instruction in the virtual machine consists of an opcode and
77up to three operands named P1, P2 and P3. P1 may be an arbitrary
78integer. P2 must be a non-negative integer. P2 is always the
79jump destination in any operation that might cause a jump.
80P3 is a null-terminated
81string or NULL. Some operators use all three operands. Some use
82one or two. Some operators use none of the operands.<p>
83
84<p>The virtual machine begins execution on instruction number 0.
85Execution continues until (1) a Halt instruction is seen, or
86(2) the program counter becomes one greater than the address of
87last instruction, or (3) there is an execution error.
88When the virtual machine halts, all memory
89that it allocated is released and all database cursors it may
90have had open are closed. If the execution stopped due to an
91error, any pending transactions are terminated and changes made
92to the database are rolled back.</p>
93
94<p>The virtual machine also contains an operand stack of unlimited
95depth. Many of the opcodes use operands from the stack. See the
96individual opcode descriptions for details.</p>
97
98<p>The virtual machine can have zero or more cursors. Each cursor
99is a pointer into a single table or index within the database.
100There can be multiple cursors pointing at the same index or table.
101All cursors operate independently, even cursors pointing to the same
102indices or tables.
103The only way for the virtual machine to interact with a database
104file is through a cursor.
105Instructions in the virtual
106machine can create a new cursor (Open), read data from a cursor
107(Column), advance the cursor to the next entry in the table
108(Next) or index (NextIdx), and many other operations.
109All cursors are automatically
110closed when the virtual machine terminates.</p>
111
112<p>The virtual machine contains an arbitrary number of fixed memory
113locations with addresses beginning at zero and growing upward.
114Each memory location can hold an arbitrary string. The memory
115cells are typically used to hold the result of a scalar SELECT
116that is part of a larger expression.</p>
117
118<p>The virtual machine contains a single sorter.
119The sorter is able to accumulate records, sort those records,
120then play the records back in sorted order. The sorter is used
121to implement the ORDER BY clause of a SELECT statement.</p>
122
123<p>The virtual machine contains a single "List".
124The list stores a list of integers. The list is used to hold the
125rowids for records of a database table that needs to be modified.
126The WHERE clause of an UPDATE or DELETE statement scans through
127the table and writes the rowid of every record to be modified
128into the list. Then the list is played back and the table is modified
129in a separate step.</p>
130
131<p>The virtual machine can contain an arbitrary number of "Sets".
132Each set holds an arbitrary number of strings. Sets are used to
133implement the IN operator with a constant right-hand side.</p>
134
135<p>The virtual machine can open a single external file for reading.
136This external read file is used to implement the COPY command.</p>
137
138<p>Finally, the virtual machine can have a single set of aggregators.
139An aggregator is a device used to implement the GROUP BY clause
140of a SELECT. An aggregator has one or more slots that can hold
141values being extracted by the select. The number of slots is the
142same for all aggregators and is defined by the AggReset operation.
143At any point in time a single aggregator is current or "has focus".
144There are operations to read or write to memory slots of the aggregator
145in focus. There are also operations to change the focus aggregator
146and to scan through all aggregators.</p>
147
148<h3>Viewing Programs Generated By SQLite</h3>
149
150<p>Every SQL statement that SQLite interprets results in a program
151for the virtual machine. But if you precede the SQL statement with
152the keyword "EXPLAIN" the virtual machine will not execute the
153program. Instead, the instructions of the program will be returned
154like a query result. This feature is useful for debugging and
155for learning how the virtual machine operates.</p>
156
157<p>You can use the <b>sqlite</b> command-line tool to see the
158instructions generated by an SQL statement. The following is
159an example:</p>}
160
161proc Code {body} {
162 puts {<blockquote><tt>}
163 regsub -all {&} [string trim $body] {\&amp;} body
164 regsub -all {>} $body {\&gt;} body
165 regsub -all {<} $body {\&lt;} body
166 regsub -all {\(\(\(} $body {<b>} body
167 regsub -all {\)\)\)} $body {</b>} body
168 regsub -all { } $body {\&nbsp;} body
169 regsub -all \n $body <br>\n body
170 puts $body
171 puts {</tt></blockquote>}
172}
173
174Code {
175$ (((sqlite ex1)))
176sqlite> (((.explain)))
177sqlite> (((explain delete from tbl1 where two<20;)))
178addr opcode p1 p2 p3
179---- ------------ ----- ----- ----------------------------------------
1800 Transaction 0 0
1811 VerifyCookie 219 0
1822 ListOpen 0 0
1833 Open 0 3 tbl1
1844 Rewind 0 0
1855 Next 0 12
1866 Column 0 1
1877 Integer 20 0
1888 Ge 0 5
1899 Recno 0 0
19010 ListWrite 0 0
19111 Goto 0 5
19212 Close 0 0
19313 ListRewind 0 0
19414 OpenWrite 0 3
19515 ListRead 0 19
19616 MoveTo 0 0
19717 Delete 0 0
19818 Goto 0 15
19919 ListClose 0 0
20020 Commit 0 0
201}
202
203puts {
204<p>All you have to do is add the "EXPLAIN" keyword to the front of the
205SQL statement. But if you use the ".explain" command to <b>sqlite</b>
206first, it will set up the output mode to make the program more easily
207viewable.</p>
208
209<p>If <b>sqlite</b> has been compiled without the "-DNDEBUG=1" option
210(that is, with the NDEBUG preprocessor macro not defined) then you
211can put the SQLite virtual machine in a mode where it will trace its
212execution by writing messages to standard output. The non-standard
213SQL "PRAGMA" comments can be used to turn tracing on and off. To
214turn tracing on, enter:
215</p>
216
217<blockquote><pre>
218PRAGMA vdbe_trace=on;
219</pre></blockquote>
220
221<p>
222You can turn tracing back off by entering a similar statement but
223changing the value "on" to "off".</p>
224
225<h3>The Opcodes</h3>
226}
227
228puts "<p>There are currently [llength $OpcodeList] opcodes defined by
229the virtual machine."
230puts {All currently defined opcodes are described in the table below.
231This table was generated automatically by scanning the source code
232from the file <b>vdbe.c</b>.</p>}
233
234puts {
235<p><table cellspacing="1" border="1" cellpadding="10">
236<tr><th>Opcode&nbsp;Name</th><th>Description</th></tr>}
237foreach op [lsort -dictionary $OpcodeList] {
238 puts {<tr><td valign="top" align="center">}
239 puts "<a name=\"$op\">$op</a>"
240 puts "<td>[string trim $Opcode($op:text)]</td></tr>"
241}
242puts {</table></p>}
243footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/optimizer.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/optimizer.tcl
deleted file mode 100644
index 5b2897e..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/optimizer.tcl
+++ /dev/null
@@ -1,265 +0,0 @@
1#
2# Run this TCL script to generate HTML for the goals.html file.
3#
4set rcsid {$Id: optimizer.tcl,v 1.1 2005/08/30 22:44:06 drh Exp $}
5source common.tcl
6header {The SQLite Query Optimizer}
7
8proc CODE {text} {
9 puts "<blockquote><pre>"
10 puts $text
11 puts "</pre></blockquote>"
12}
13proc IMAGE {name {caption {}}} {
14 puts "<center><img src=\"$name\">"
15 if {$caption!=""} {
16 puts "<br>$caption"
17 }
18 puts "</center>"
19}
20proc PARAGRAPH {text} {
21 puts "<p>$text</p>\n"
22}
23proc HEADING {level name} {
24 puts "<h$level>$name</h$level>"
25}
26
27HEADING 1 {The SQLite Query Optimizer}
28
29PARAGRAPH {
30 This article describes how the SQLite query optimizer works.
31 This is not something you have to know in order to use SQLite - many
32 programmers use SQLite successfully without the slightest hint of what
33 goes on in the inside.
34 But a basic understanding of what SQLite is doing
35 behind the scenes will help you to write more efficient SQL. And the
36 knowledge gained by studying the SQLite query optimizer has broad
37 application since most other relational database engines operate
38 similarly.
39 A solid understanding of how the query optimizer works is also
40 required before making meaningful changes or additions to the SQLite, so
41 this article should be read closely by anyone aspiring
42 to hack the source code.
43}
44
45HEADING 2 Background
46
47PARAGRAPH {
48 It is important to understand that SQL is a programming language.
49 SQL is a perculiar programming language in that it
50 describes <u>what</u> the programmer wants to compute not <u>how</u>
51 to compute it as most other programming languages do.
52 But perculiar or not, SQL is still just a programming language.
53}
54
55PARAGRAPH {
56 It is very helpful to think of each SQL statement as a separate
57 program.
58 An important job of the SQL database engine is to translate each
59 SQL statement from its descriptive form that specifies what the
60 information is desired (the <u>what</u>)
61 into a procedural form that specifies how to go
62 about acquiring the desired information (the <u>how</u>).
63 The task of translating the <u>what</u> into a
64 <u>how</u> is assigned to the query optimizer.
65}
66
67PARAGRAPH {
68 The beauty of SQL comes from the fact that the optimizer frees the programmer
69 from having to worry over the details of <u>how</u>. The programmer
70 only has to specify the <u>what</u> and then leave the optimizer
71 to deal with all of the minutae of implementing the
72 <u>how</u>. Thus the programmer is able to think and work at a
73 much higher level and leave the optimizer to stress over the low-level
74 work.
75}
76
77HEADING 2 {Database Layout}
78
79PARAGRAPH {
80 An SQLite database consists of one or more "b-trees".
81 Each b-tree contains zero or more "rows".
82 A single row contains a "key" and some "data".
83 In general, both the key and the data are arbitrary binary
84 data of any length.
85 The keys must all be unique within a single b-tree.
86 Rows are stored in order of increasing key values - each
87 b-tree has a comparision functions for keys that determines
88 this order.
89}
90
91PARAGRAPH {
92 In SQLite, each SQL table is stored as a b-tree where the
93 key is a 64-bit integer and the data is the content of the
94 table row. The 64-bit integer key is the ROWID. And, of course,
95 if the table has an INTEGER PRIMARY KEY, then that integer is just
96 an alias for the ROWID.
97}
98
99PARAGRAPH {
100 Consider the following block of SQL code:
101}
102
103CODE {
104 CREATE TABLE ex1(
105 id INTEGER PRIMARY KEY,
106 x VARCHAR(30),
107 y INTEGER
108 );
109 INSERT INTO ex1 VALUES(NULL,'abc',12345);
110 INSERT INTO ex1 VALUES(NULL,456,'def');
111 INSERT INTO ex1 VALUES(100,'hello','world');
112 INSERT INTO ex1 VALUES(-5,'abc','xyz');
113 INSERT INTO ex1 VALUES(54321,NULL,987);
114}
115
116PARAGRAPH {
117 This code generates a new b-tree (named "ex1") containing 5 rows.
118 This table can be visualized as follows:
119}
120IMAGE table-ex1b2.gif
121
122PARAGRAPH {
123 Note that the key for each row if the b-tree is the INTEGER PRIMARY KEY
124 for that row. (Remember that the INTEGER PRIMARY KEY is just an alias
125 for the ROWID.) The other fields of the table form the data for each
126 entry in the b-tree. Note also that the b-tree entries are in ROWID order
127 which is different from the order that they were originally inserted.
128}
129
130PARAGRAPH {
131 Now consider the following SQL query:
132}
133CODE {
134 SELECT y FROM ex1 WHERE x=456;
135}
136
137PARAGRAPH {
138 When the SQLite parser and query optimizer are handed this query, they
139 have to translate it into a procedure that will find the desired result.
140 In this case, they do what is call a "full table scan". They start
141 at the beginning of the b-tree that contains the table and visit each
142 row. Within each row, the value of the "x" column is tested and when it
143 is found to match 456, the value of the "y" column is output.
144 We can represent this procedure graphically as follows:
145}
146IMAGE fullscanb.gif
147
148PARAGRAPH {
149 A full table scan is the access method of last resort. It will always
150 work. But if the table contains millions of rows and you are only looking
151 a single one, it might take a very long time to find the particular row
152 you are interested in.
153 In particular, the time needed to access a single row of the table is
154 proportional to the total number of rows in the table.
155 So a big part of the job of the optimizer is to try to find ways to
156 satisfy the query without doing a full table scan.
157}
158PARAGRAPH {
159 The usual way to avoid doing a full table scan is use a binary search
160 to find the particular row or rows of interest in the table.
161 Consider the next query which searches on rowid instead of x:
162}
163CODE {
164 SELECT y FROM ex1 WHERE rowid=2;
165}
166
167PARAGRAPH {
168 In the previous query, we could not use a binary search for x because
169 the values of x were not ordered. But the rowid values are ordered.
170 So instead of having to visit every row of the b-tree looking for one
171 that has a rowid value of 2, we can do a binary search for that particular
172 row and output its corresponding y value. We show this graphically
173 as follows:
174}
175IMAGE direct1b.gif
176
177PARAGRAPH {
178 When doing a binary search, we only have to look at a number of
179 rows with is proportional to the logorithm of the number of entries
180 in the table. For a table with just 5 entires as in the example above,
181 the difference between a full table scan and a binary search is
182 negligible. In fact, the full table scan might be faster. But in
183 a database that has 5 million rows, a binary search will be able to
184 find the desired row in only about 23 tries, whereas the full table
185 scan will need to look at all 5 million rows. So the binary search
186 is about 200,000 times faster in that case.
187}
188PARAGRAPH {
189 A 200,000-fold speed improvement is huge. So we always want to do
190 a binary search rather than a full table scan when we can.
191}
192PARAGRAPH {
193 The problem with a binary search is that the it only works if the
194 fields you are search for are in sorted order. So we can do a binary
195 search when looking up the rowid because the rows of the table are
196 sorted by rowid. But we cannot use a binary search when looking up
197 x because the values in the x column are in no particular order.
198}
199PARAGRAPH {
200 The way to work around this problem and to permit binary searching on
201 fields like x is to provide an index.
202 An index is another b-tree.
203 But in the index b-tree the key is not the rowid but rather the field
204 or fields being indexed followed by the rowid.
205 The data in an index b-tree is empty - it is not needed or used.
206 The following diagram shows an index on the x field of our example table:
207}
208IMAGE index-ex1-x-b.gif
209
210PARAGRAPH {
211 An important point to note in the index are that they keys of the
212 b-tree are in sorted order. (Recall that NULL values in SQLite sort
213 first, followed by numeric values in numerical order, then strings, and
214 finally BLOBs.) This is the property that will allow use to do a
215 binary search for the field x. The rowid is also included in every
216 key for two reasons. First, by including the rowid we guarantee that
217 every key will be unique. And second, the rowid will be used to look
218 up the actual table entry after doing the binary search. Finally, note
219 that the data portion of the index b-tree serves no purpose and is thus
220 kept empty to save space in the disk file.
221}
222PARAGRAPH {
223 Remember what the original query example looked like:
224}
225CODE {
226 SELECT y FROM ex1 WHERE x=456;
227}
228
229PARAGRAPH {
230 The first time this query was encountered we had to do a full table
231 scan. But now that we have an index on x, we can do a binary search
232 on that index for the entry where x==456. Then from that entry we
233 can find the rowid value and use the rowid to look up the corresponding
234 entry in the original table. From the entry in the original table,
235 we can find the value y and return it as our result. The following
236 diagram shows this process graphically:
237}
238IMAGE indirect1b1.gif
239
240PARAGRAPH {
241 With the index, we are able to look up an entry based on the value of
242 x after visiting only a logorithmic number of b-tree entries. Unlike
243 the case where we were searching using rowid, we have to do two binary
244 searches for each output row. But for a 5-million row table, that is
245 still only 46 searches instead of 5 million for a 100,000-fold speedup.
246}
247
248HEADING 3 {Parsing The WHERE Clause}
249
250
251
252# parsing the where clause
253# rowid lookup
254# index lookup
255# index lookup without the table
256# how an index is chosen
257# joins
258# join reordering
259# order by using an index
260# group by using an index
261# OR -> IN optimization
262# Bitmap indices
263# LIKE and GLOB optimization
264# subquery flattening
265# MIN and MAX optimizations
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/optimizing.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/optimizing.tcl
deleted file mode 100644
index 44d2825..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/optimizing.tcl
+++ /dev/null
@@ -1,15 +0,0 @@
1set rcsid {$Id: optimizing.tcl,v 1.1 2005/01/17 03:42:52 drh Exp $}
2source common.tcl
3header {Hints For Optimizing Queries In SQLite}
4proc section {level tag name} {
5 incr level
6 if {$level>6} {set level 6}
7 puts "\n"<a name=\"tag\" />"
8 puts "<h$level>$name</h$level>\n"
9}
10section 1 recompile {Recompile the library for optimal performance}
11section 2 avoidtrans {Minimize the number of transactions}
12section 3 usebind {Use sqlite3_bind to insert large chunks of data}
13section 4 useindices {Use appropriate indices}
14section 5 recordjoin {Reorder the tables in a join}
15footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/optoverview.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/optoverview.tcl
deleted file mode 100644
index 15646e3..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/optoverview.tcl
+++ /dev/null
@@ -1,516 +0,0 @@
1#
2# Run this TCL script to generate HTML for the goals.html file.
3#
4set rcsid {$Id: optoverview.tcl,v 1.5 2005/11/24 13:15:34 drh Exp $}
5source common.tcl
6header {The SQLite Query Optimizer Overview}
7
8proc CODE {text} {
9 puts "<blockquote><pre>"
10 puts $text
11 puts "</pre></blockquote>"
12}
13proc SYNTAX {text} {
14 puts "<blockquote><pre>"
15 set t2 [string map {& &amp; < &lt; > &gt;} $text]
16 regsub -all "/(\[^\n/\]+)/" $t2 {</b><i>\1</i><b>} t3
17 puts "<b>$t3</b>"
18 puts "</pre></blockquote>"
19}
20proc IMAGE {name {caption {}}} {
21 puts "<center><img src=\"$name\">"
22 if {$caption!=""} {
23 puts "<br>$caption"
24 }
25 puts "</center>"
26}
27proc PARAGRAPH {text} {
28 # regsub -all "/(\[a-zA-Z0-9\]+)/" $text {<i>\1</i>} t2
29 regsub -all "\\*(\[^\n*\]+)\\*" $text {<tt><b><big>\1</big></b></tt>} t3
30 puts "<p>$t3</p>\n"
31}
32set level(0) 0
33set level(1) 0
34proc HEADING {n name {tag {}}} {
35 if {$tag!=""} {
36 puts "<a name=\"$tag\">"
37 }
38 global level
39 incr level($n)
40 for {set i [expr {$n+1}]} {$i<10} {incr i} {
41 set level($i) 0
42 }
43 if {$n==0} {
44 set num {}
45 } elseif {$n==1} {
46 set num $level(1).0
47 } else {
48 set num $level(1)
49 for {set i 2} {$i<=$n} {incr i} {
50 append num .$level($i)
51 }
52 }
53 incr n 1
54 puts "<h$n>$num $name</h$n>"
55}
56
57HEADING 0 {The SQLite Query Optimizer Overview}
58
59PARAGRAPH {
60 This document provides a terse overview of how the query optimizer
61 for SQLite works. This is not a tutorial. The reader is likely to
62 need some prior knowledge of how database engines operate
63 in order to fully understand this text.
64}
65
66HEADING 1 {WHERE clause analysis} where_clause
67
68PARAGRAPH {
69 The WHERE clause on a query is broken up into "terms" where each term
70 is separated from the others by an AND operator.
71}
72PARAGRAPH {
73 All terms of the WHERE clause are analyzed to see if they can be
74 satisfied using indices.
75 Terms that cannot be satisfied through the use of indices become
76 tests that are evaluated against each row of the relevant input
77 tables. No tests are done for terms that are completely satisfied by
78 indices. Sometimes
79 one or more terms will provide hints to indices but still must be
80 evaluated against each row of the input tables.
81}
82
83PARAGRAPH {
84 The analysis of a term might cause new "virtual" terms to
85 be added to the WHERE clause. Virtual terms can be used with
86 indices to restrict a search. But virtual terms never generate code
87 that is tested against input rows.
88}
89
90PARAGRAPH {
91 To be usable by an index a term must be of one of the following
92 forms:
93}
94SYNTAX {
95 /column/ = /expression/
96 /column/ > /expression/
97 /column/ >= /expression/
98 /column/ < /expression/
99 /column/ <= /expression/
100 /expression/ = /column/
101 /expression/ > /column/
102 /expression/ >= /column/
103 /expression/ < /column/
104 /expression/ <= /column/
105 /column/ IN (/expression-list/)
106 /column/ IN (/subquery/)
107}
108PARAGRAPH {
109 If an index is created using a statement like this:
110}
111CODE {
112 CREATE INDEX idx_ex1 ON ex1(a,b,c,d,e,...,y,z);
113}
114PARAGRAPH {
115 Then the index might be used if the initial columns of the index
116 (columns a, b, and so forth) appear in WHERE clause terms.
117 All index columns must be used with
118 the *=* or *IN* operators except for
119 the right-most column which can use inequalities. For the right-most
120 column of an index that is used, there can be up to two inequalities
121 that must sandwich the allowed values of the column between two extremes.
122}
123PARAGRAPH {
124 It is not necessary for every column of an index to appear in a
125 WHERE clause term in order for that index to be used.
126 But there can not be gaps in the columns of the index that are used.
127 Thus for the example index above, if there is no WHERE clause term
128 that constraints column c, then terms that constraint columns a and b can
129 be used with the index but not terms that constraint columns d through z.
130 Similarly, no index column will be used (for indexing purposes)
131 that is to the right of a
132 column that is constrained only by inequalities.
133 For the index above and WHERE clause like this:
134}
135CODE {
136 ... WHERE a=5 AND b IN (1,2,3) AND c>12 AND d='hello'
137}
138PARAGRAPH {
139 Only columns a, b, and c of the index would be usable. The d column
140 would not be usable because it occurs to the right of c and c is
141 constrained only by inequalities.
142}
143
144HEADING 1 {The BETWEEN optimization} between_opt
145
146PARAGRAPH {
147 If a term of the WHERE clause is of the following form:
148}
149SYNTAX {
150 /expr1/ BETWEEN /expr2/ AND /expr3/
151}
152PARAGRAPH {
153 Then two virtual terms are added as follows:
154}
155SYNTAX {
156 /expr1/ >= /expr2/ AND /expr1/ <= /expr3/
157}
158PARAGRAPH {
159 If both virtual terms end up being used as constraints on an index,
160 then the original BETWEEN term is omitted and the corresponding test
161 is not performed on input rows.
162 Thus if the BETWEEN term ends up being used as an index constraint
163 no tests are ever performed on that term.
164 On the other hand, the
165 virtual terms themselves never causes tests to be performed on
166 input rows.
167 Thus if the BETWEEN term is not used as an index constraint and
168 instead must be used to test input rows, the <i>expr1</i> expression is
169 only evaluated once.
170}
171
172HEADING 1 {The OR optimization} or_opt
173
174PARAGRAPH {
175 If a term consists of multiple subterms containing a common column
176 name and separated by OR, like this:
177}
178SYNTAX {
179 /column/ = /expr1/ OR /column/ = /expr2/ OR /column/ = /expr3/ OR ...
180}
181PARAGRAPH {
182 Then the term is rewritten as follows:
183}
184SYNTAX {
185 /column/ IN (/expr1/,/expr2/,/expr3/,/expr4/,...)
186}
187PARAGRAPH {
188 The rewritten term then might go on to constraint an index using the
189 normal rules for *IN* operators.
190 Note that <i>column</i> must be the same column in every OR-connected subterm,
191 although the column can occur on either the left or the right side of
192 the *=* operator.
193}
194
195HEADING 1 {The LIKE optimization} like_opt
196
197PARAGRAPH {
198 Terms that are composed of the LIKE or GLOB operator
199 can sometimes be used to constrain indices.
200 There are many conditions on this use:
201}
202PARAGRAPH {
203 <ol>
204 <li>The left-hand side of the LIKE or GLOB operator must be the name
205 of an indexed column.</li>
206 <li>The right-hand side of the LIKE or GLOB must be a string literal
207 that does not begin with a wildcard character.</li>
208 <li>The ESCAPE clause cannot appear on the LIKE operator.</li>
209 <li>The build-in functions used to implement LIKE and GLOB must not
210 have been overloaded using the sqlite3_create_function() API.</li>
211 <li>For the GLOB operator, the column must use the default BINARY
212 collating sequence.</li>
213 <li>For the LIKE operator, if case_sensitive_like mode is enabled then
214 the column must use the default BINARY collating sequence, or if
215 case_sensitive_like mode is disabled then the column must use the
216 built-in NOCASE collating sequence.</li>
217 </ol>
218}
219PARAGRAPH {
220 The LIKE operator has two modes that can be set by a pragma. The
221 default mode is for LIKE comparisons to be insensitive to differences
222 of case for latin1 characters. Thus, by default, the following
223 expression is true:
224}
225CODE {
226 'a' LIKE 'A'
227}
228PARAGRAPH {
229 By turned on the case_sensitive_like pragma as follows:
230}
231CODE {
232 PRAGMA case_sensitive_like=ON;
233}
234PARAGRAPH {
235 Then the LIKE operator pays attention to case and the example above would
236 evaluate to false. Note that case insensitivity only applies to
237 latin1 characters - basically the upper and lower case letters of English
238 in the lower 127 byte codes of ASCII. International character sets
239 are case sensitive in SQLite unless a user-supplied collating
240 sequence is used. But if you employ a user-supplied collating sequence,
241 the LIKE optimization describe here will never be taken.
242}
243PARAGRAPH {
244 The LIKE operator is case insensitive by default because this is what
245 the SQL standard requires. You can change the default behavior at
246 compile time by using the -DSQLITE_CASE_SENSITIVE_LIKE command-line option
247 to the compiler.
248}
249PARAGRAPH {
250 The LIKE optimization might occur if the column named on the left of the
251 operator uses the BINARY collating sequence (which is the default) and
252 case_sensitive_like is turned on. Or the optimization might occur if
253 the column uses the built-in NOCASE collating sequence and the
254 case_sensitive_like mode is off. These are the only two combinations
255 under which LIKE operators will be optimized. If the column on the
256 right-hand side of the LIKE operator uses any collating sequence other
257 than the built-in BINARY and NOCASE collating sequences, then no optimizations
258 will ever be attempted on the LIKE operator.
259}
260PARAGRAPH {
261 The GLOB operator is always case sensitive. The column on the left side
262 of the GLOB operator must always use the built-in BINARY collating sequence
263 or no attempt will be made to optimize that operator with indices.
264}
265PARAGRAPH {
266 The right-hand side of the GLOB or LIKE operator must be a literal string
267 value that does not begin with a wildcard. If the right-hand side is a
268 parameter that is bound to a string, then no optimization is attempted.
269 If the right-hand side begins with a wildcard character then no
270 optimization is attempted.
271}
272PARAGRAPH {
273 Suppose the initial sequence of non-wildcard characters on the right-hand
274 side of the LIKE or GLOB operator is <i>x</i>. We are using a single
275 character to denote this non-wildcard prefix but the reader should
276 understand that the prefix can consist of more than 1 character.
277 Let <i>y</i> the smallest string that is the same length as /x/ but which
278 compares greater than <i>x</i>. For example, if <i>x</i> is *hello* then
279 <i>y</i> would be *hellp*.
280 The LIKE and GLOB optimizations consist of adding two virtual terms
281 like this:
282}
283SYNTAX {
284 /column/ >= /x/ AND /column/ < /y/
285}
286PARAGRAPH {
287 Under most circumstances, the original LIKE or GLOB operator is still
288 tested against each input row even if the virtual terms are used to
289 constrain an index. This is because we do not know what additional
290 constraints may be imposed by characters to the right
291 of the <i>x</i> prefix. However, if there is only a single global wildcard
292 to the right of <i>x</i>, then the original LIKE or GLOB test is disabled.
293 In other words, if the pattern is like this:
294}
295SYNTAX {
296 /column/ LIKE /x/%
297 /column/ GLOB /x/*
298}
299PARAGRAPH {
300 Then the original LIKE or GLOB tests are disabled when the virtual
301 terms constrain an index because in that case we know that all of the
302 rows selected by the index will pass the LIKE or GLOB test.
303}
304
305HEADING 1 {Joins} joins
306
307PARAGRAPH {
308 The current implementation of
309 SQLite uses only loop joins. That is to say, joins are implemented as
310 nested loops.
311}
312PARAGRAPH {
313 The default order of the nested loops in a join is for the left-most
314 table in the FROM clause to form the outer loop and the right-most
315 table to form the inner loop.
316 However, SQLite will nest the loops in a different order if doing so
317 will help it to select better indices.
318}
319PARAGRAPH {
320 Inner joins can be freely reordered. However a left outer join is
321 neither commutative nor associative and hence will not be reordered.
322 Inner joins to the left and right of the outer join might be reordered
323 if the optimizer thinks that is advantageous but the outer joins are
324 always evaluated in the order in which they occur.
325}
326PARAGRAPH {
327 When selecting the order of tables in a join, SQLite uses a greedy
328 algorithm that runs in polynomial time.
329}
330PARAGRAPH {
331 The ON and USING clauses of a join are converted into additional
332 terms of the WHERE clause prior to WHERE clause analysis described
333 above in paragraph 1.0. Thus
334 with SQLite, there is no advantage to use the newer SQL92 join syntax
335 over the older SQL89 comma-join syntax. They both end up accomplishing
336 exactly the same thing.
337}
338PARAGRAPH {
339 Join reordering is automatic and usually works well enough that
340 programmer do not have to think about it. But occasionally some
341 hints from the programmer are needed. For a description of when
342 hints might be necessary and how to provide those hints, see the
343 <a href="http://www.sqlite.org/cvstrac/wiki?p=QueryPlans">QueryPlans</a>
344 page in the Wiki.
345}
346
347HEADING 1 {Choosing between multiple indices} multi_index
348
349PARAGRAPH {
350 Each table in the FROM clause of a query can use at most one index,
351 and SQLite strives to use at least one index on each table. Sometimes,
352 two or more indices might be candidates for use on a single table.
353 For example:
354}
355CODE {
356 CREATE TABLE ex2(x,y,z);
357 CREATE INDEX ex2i1 ON ex2(x);
358 CREATE INDEX ex2i2 ON ex2(y);
359 SELECT z FROM ex2 WHERE x=5 AND y=6;
360}
361PARAGRAPH {
362 For the SELECT statement above, the optimizer can use the ex2i1 index
363 to lookup rows of ex2 that contain x=5 and then test each row against
364 the y=6 term. Or it can use the ex2i2 index to lookup rows
365 of ex2 that contain y=6 then test each of those rows against the
366 x=5 term.
367}
368PARAGRAPH {
369 When faced with a choice of two or more indices, SQLite tries to estimate
370 the total amount of work needed to perform the query using each option.
371 It then selects the option that gives the least estimated work.
372}
373PARAGRAPH {
374 To help the optimizer get a more accurate estimate of the work involved
375 in using various indices, the user may optional run the ANALYZE command.
376 The ANALYZE command scans all indices of database where there might
377 be a choice between two or more indices and gathers statistics on the
378 selectiveness of those indices. The results of this scan are stored
379 in the sqlite_stat1 table.
380 The contents of the sqlite_stat1 table are not updated as the database
381 changes so after making significant changes it might be prudent to
382 rerun ANALYZE.
383 The results of an ANALYZE command are only available to database connections
384 that are opened after the ANALYZE command completes.
385}
386PARAGRAPH {
387 Once created, the sqlite_stat1 table cannot be dropped. But its
388 content can be viewed, modified, or erased. Erasing the entire content
389 of the sqlite_stat1 table has the effect of undoing the ANALYZE command.
390 Changing the content of the sqlite_stat1 table can get the optimizer
391 deeply confused and cause it to make silly index choices. Making
392 updates to the sqlite_stat1 table (except by running ANALYZE) is
393 not recommended.
394}
395PARAGRAPH {
396 Terms of the WHERE clause can be manually disqualified for use with
397 indices by prepending a unary *+* operator to the column name. The
398 unary *+* is a no-op and will not slow down the evaluation of the test
399 specified by the term.
400 But it will prevent the term from constraining an index.
401 So, in the example above, if the query were rewritten as:
402}
403CODE {
404 SELECT z FROM ex2 WHERE +x=5 AND y=6;
405}
406PARAGRAPH {
407 The *+* operator on the *x* column would prevent that term from
408 constraining an index. This would force the use of the ex2i2 index.
409}
410
411HEADING 1 {Avoidance of table lookups} index_only
412
413PARAGRAPH {
414 When doing an indexed lookup of a row, the usual procedure is to
415 do a binary search on the index to find the index entry, then extract
416 the rowid from the index and use that rowid to do a binary search on
417 the original table. Thus a typical indexed lookup involves two
418 binary searches.
419 If, however, all columns that were to be fetched from the table are
420 already available in the index itself, SQLite will use the values
421 contained in the index and will never look up the original table
422 row. This saves one binary search for each row and can make many
423 queries run twice as fast.
424}
425
426HEADING 1 {ORDER BY optimizations} order_by
427
428PARAGRAPH {
429 SQLite attempts to use an index to satisfy the ORDER BY clause of a
430 query when possible.
431 When faced with the choice of using an index to satisfy WHERE clause
432 constraints or satisfying an ORDER BY clause, SQLite does the same
433 work analysis described in section 6.0
434 and chooses the index that it believes will result in the fastest answer.
435
436}
437
438HEADING 1 {Subquery flattening} flattening
439
440PARAGRAPH {
441 When a subquery occurs in the FROM clause of a SELECT, the default
442 behavior is to evaluate the subquery into a transient table, then run
443 the outer SELECT against the transient table.
444 This is problematic since the transient table will not have any indices
445 and the outer query (which is likely a join) will be forced to do a
446 full table scan on the transient table.
447}
448PARAGRAPH {
449 To overcome this problem, SQLite attempts to flatten subqueries in
450 the FROM clause of a SELECT.
451 This involves inserting the FROM clause of the subquery into the
452 FROM clause of the outer query and rewriting expressions in
453 the outer query that refer to the result set of the subquery.
454 For example:
455}
456CODE {
457 SELECT a FROM (SELECT x+y AS a FROM t1 WHERE z<100) WHERE a>5
458}
459PARAGRAPH {
460 Would be rewritten using query flattening as:
461}
462CODE {
463 SELECT x+y AS a FROM t1 WHERE z<100 AND a>5
464}
465PARAGRAPH {
466 There is a long list of conditions that must all be met in order for
467 query flattening to occur.
468}
469PARAGRAPH {
470 <ol>
471 <li> The subquery and the outer query do not both use aggregates.</li>
472 <li> The subquery is not an aggregate or the outer query is not a join. </li>
473 <li> The subquery is not the right operand of a left outer join, or
474 the subquery is not itself a join. </li>
475 <li> The subquery is not DISTINCT or the outer query is not a join. </li>
476 <li> The subquery is not DISTINCT or the outer query does not use
477 aggregates. </li>
478 <li> The subquery does not use aggregates or the outer query is not
479 DISTINCT. </li>
480 <li> The subquery has a FROM clause. </li>
481 <li> The subquery does not use LIMIT or the outer query is not a join. </li>
482 <li> The subquery does not use LIMIT or the outer query does not use
483 aggregates. </li>
484 <li> The subquery does not use aggregates or the outer query does not
485 use LIMIT. </li>
486 <li> The subquery and the outer query do not both have ORDER BY clauses.</li>
487 <li> The subquery is not the right term of a LEFT OUTER JOIN or the
488 subquery has no WHERE clause. </li>
489 </ol>
490}
491PARAGRAPH {
492 The proof that query flattening may safely occur if all of the the
493 above conditions are met is left as an exercise to the reader.
494}
495PARAGRAPH {
496 Query flattening is an important optimization when views are used as
497 each use of a view is translated into a subquery.
498}
499
500HEADING 1 {The MIN/MAX optimization} minmax
501
502PARAGRAPH {
503 Queries of the following forms will be optimized to run in logarithmic
504 time assuming appropriate indices exist:
505}
506CODE {
507 SELECT MIN(x) FROM table;
508 SELECT MAX(x) FROM table;
509}
510PARAGRAPH {
511 In order for these optimizations to occur, they must appear in exactly
512 the form shown above - changing only the name of the table and column.
513 It is not permissible to add a WHERE clause or do any arithmetic on the
514 result. The result set must contain a single column.
515 The column in the MIN or MAX function must be an indexed column.
516}
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/pragma.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/pragma.tcl
deleted file mode 100644
index d1fcb21..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/pragma.tcl
+++ /dev/null
@@ -1,635 +0,0 @@
1#
2# Run this Tcl script to generate the pragma.html file.
3#
4set rcsid {$Id: pragma.tcl,v 1.28 2007/08/28 08:19:49 danielk1977 Exp $}
5source common.tcl
6header {Pragma statements supported by SQLite}
7
8proc Section {name {label {}}} {
9 puts "\n<hr />"
10 if {$label!=""} {
11 puts "<a name=\"$label\"></a>"
12 }
13 puts "<h1>$name</h1>\n"
14}
15
16puts {
17<p>The <a href="#syntax">PRAGMA command</a> is a special command used to
18modify the operation of the SQLite library or to query the library for
19internal (non-table) data. The PRAGMA command is issued using the same
20interface as other SQLite commands (e.g. SELECT, INSERT) but is
21different in the following important respects:
22</p>
23<ul>
24<li>Specific pragma statements may be removed and others added in future
25 releases of SQLite. Use with caution!
26<li>No error messages are generated if an unknown pragma is issued.
27 Unknown pragmas are simply ignored. This means if there is a typo in
28 a pragma statement the library does not inform the user of the fact.
29<li>Some pragmas take effect during the SQL compilation stage, not the
30 execution stage. This means if using the C-language sqlite3_prepare(),
31 sqlite3_step(), sqlite3_finalize() API (or similar in a wrapper
32 interface), the pragma may be applied to the library during the
33 sqlite3_prepare() call.
34<li>The pragma command is unlikely to be compatible with any other SQL
35 engine.
36</ul>
37
38<p>The available pragmas fall into four basic categories:</p>
39<ul>
40<li>Pragmas used to <a href="#modify">modify the operation</a> of the
41 SQLite library in some manner, or to query for the current mode of
42 operation.
43<li>Pragmas used to <a href="#schema">query the schema</a> of the current
44 database.
45<li>Pragmas used to <a href="#version">query or modify the databases two
46 version values</a>, the schema-version and the user-version.
47<li>Pragmas used to <a href="#debug">debug the library</a> and verify that
48 database files are not corrupted.
49</ul>
50}
51
52Section {PRAGMA command syntax} syntax
53
54Syntax {sql-statement} {
55PRAGMA <name> [= <value>] |
56PRAGMA <function>(<arg>)
57}
58
59puts {
60<p>The pragmas that take an integer <b><i>value</i></b> also accept
61symbolic names. The strings "<b>on</b>", "<b>true</b>", and "<b>yes</b>"
62are equivalent to <b>1</b>. The strings "<b>off</b>", "<b>false</b>",
63and "<b>no</b>" are equivalent to <b>0</b>. These strings are case-
64insensitive, and do not require quotes. An unrecognized string will be
65treated as <b>1</b>, and will not generate an error. When the <i>value</i>
66is returned it is as an integer.</p>
67}
68
69Section {Pragmas to modify library operation} modify
70
71puts {
72<ul>
73<a name="pragma_auto_vacuum"></a>
74<li><p><b>PRAGMA auto_vacuum;<br>
75 PRAGMA auto_vacuum = </b>
76 <i>0 | none | 1 | full | 2 | incremental</i><b>;</b></p>
77 <p>Query or set the auto-vacuum flag in the database.</p>
78
79 <p>Normally, (that is to say when auto_vacuum is 0 or "none")
80 when a transaction that deletes data from a database is
81 committed, the database file remains the same size. Unused database file
82 pages are added to a "freelist" are reused for subsequent inserts. The
83 database file does not shrink.
84 In this mode the <a href="lang_vacuum.html">VACUUM</a>
85 command can be used to reclaim unused space.</p>
86
87 <p>When the auto-vacuum flag is 1 (full), the freelist pages are
88 moved to the end of the file and the file is truncated to remove
89 the freelist pages at every commit.
90 Note, however, that auto-vacuum only truncates the freelist pages
91 from the file. Auto-vacuum does not defragment the database nor
92 repack individual database pages the way that the
93 <a href="lang_vacuum.html">VACUUM</a> command does. In fact, because
94 it moves pages around within the file, auto-vacuum can actually
95 make fragmentation worse.</p>
96
97 <p>Auto-vacuuming is only possible if the database stores some
98 additional information that allows each database page to be
99 traced backwards to its referer. Therefore, auto-vacuuming must
100 be turned on before any tables are created. It is not possible
101 to enable or disable auto-vacuum after a table has been created.</p>
102
103 <p>When the value of auto-vacuum is 2 (incremental) then the additional
104 information needed to do autovacuuming is stored in the database file
105 but autovacuuming does not occur automatically at each commit as it
106 does with auto_vacuum==full. In incremental mode, the separate
107 <a href="#pragma_incremental_vacuum">incremental_vacuum</a> pragma must
108 be invoked to cause the vacuum to occur.</p>
109
110 <p>The database connection can be changed between full and incremental
111 autovacuum mode at will. However, the connection cannot be changed
112 in and out of the "none" mode after any table has been created in the
113 database.
114 </p></li>
115
116<a name="pragma_cache_size"></a>
117<li><p><b>PRAGMA cache_size;
118 <br>PRAGMA cache_size = </b><i>Number-of-pages</i><b>;</b></p>
119 <p>Query or change the maximum number of database disk pages that SQLite
120 will hold in memory at once. Each page uses about 1.5K of memory.
121 The default cache size is 2000. If you are doing UPDATEs or DELETEs
122 that change many rows of a database and you do not mind if SQLite
123 uses more memory, you can increase the cache size for a possible speed
124 improvement.</p>
125 <p>When you change the cache size using the cache_size pragma, the
126 change only endures for the current session. The cache size reverts
127 to the default value when the database is closed and reopened. Use
128 the <a href="#pragma_default_cache_size"><b>default_cache_size</b></a>
129 pragma to check the cache size permanently.</p></li>
130
131<a name="pragma_case_sensitive_like"></a>
132<li><p><b>PRAGMA case_sensitive_like;
133 <br>PRAGMA case_sensitive_like = </b><i>0 | 1</i><b>;</b></p>
134 <p>The default behavior of the LIKE operator is to ignore case
135 for latin1 characters. Hence, by default <b>'a' LIKE 'A'</b> is
136 true. The case_sensitive_like pragma can be turned on to change
137 this behavior. When case_sensitive_like is enabled,
138 <b>'a' LIKE 'A'</b> is false but <b>'a' LIKE 'a'</b> is still true.</p>
139 </li>
140
141<a name="pragma_count_changes"></a>
142<li><p><b>PRAGMA count_changes;
143 <br>PRAGMA count_changes = </b><i>0 | 1</i><b>;</b></p>
144 <p>Query or change the count-changes flag. Normally, when the
145 count-changes flag is not set, INSERT, UPDATE and DELETE statements
146 return no data. When count-changes is set, each of these commands
147 returns a single row of data consisting of one integer value - the
148 number of rows inserted, modified or deleted by the command. The
149 returned change count does not include any insertions, modifications
150 or deletions performed by triggers.</p>
151
152<a name="pragma_default_cache_size"></a>
153<li><p><b>PRAGMA default_cache_size;
154 <br>PRAGMA default_cache_size = </b><i>Number-of-pages</i><b>;</b></p>
155 <p>Query or change the maximum number of database disk pages that SQLite
156 will hold in memory at once. Each page uses 1K on disk and about
157 1.5K in memory.
158 This pragma works like the
159 <a href="#pragma_cache_size"><b>cache_size</b></a>
160 pragma with the additional
161 feature that it changes the cache size persistently. With this pragma,
162 you can set the cache size once and that setting is retained and reused
163 every time you reopen the database.</p></li>
164
165<a name="pragma_default_synchronous"></a>
166<li><p><b>PRAGMA default_synchronous;</b></p>
167 <p>This pragma was available in version 2.8 but was removed in version
168 3.0. It is a dangerous pragma whose use is discouraged. To help
169 dissuide users of version 2.8 from employing this pragma, the documentation
170 will not tell you what it does.</p></li>
171
172
173<a name="pragma_empty_result_callbacks"></a>
174<li><p><b>PRAGMA empty_result_callbacks;
175 <br>PRAGMA empty_result_callbacks = </b><i>0 | 1</i><b>;</b></p>
176 <p>Query or change the empty-result-callbacks flag.</p>
177 <p>The empty-result-callbacks flag affects the sqlite3_exec API only.
178 Normally, when the empty-result-callbacks flag is cleared, the
179 callback function supplied to the sqlite3_exec() call is not invoked
180 for commands that return zero rows of data. When empty-result-callbacks
181 is set in this situation, the callback function is invoked exactly once,
182 with the third parameter set to 0 (NULL). This is to enable programs
183 that use the sqlite3_exec() API to retrieve column-names even when
184 a query returns no data.
185 </p>
186
187<a name="pragma_encoding"></a>
188<li><p><b>PRAGMA encoding;
189 <br>PRAGMA encoding = "UTF-8";
190 <br>PRAGMA encoding = "UTF-16";
191 <br>PRAGMA encoding = "UTF-16le";
192 <br>PRAGMA encoding = "UTF-16be";</b></p>
193 <p>In first form, if the main database has already been
194 created, then this pragma returns the text encoding used by the
195 main database, one of "UTF-8", "UTF-16le" (little-endian UTF-16
196 encoding) or "UTF-16be" (big-endian UTF-16 encoding). If the main
197 database has not already been created, then the value returned is the
198 text encoding that will be used to create the main database, if
199 it is created by this session.</p>
200 <p>The second and subsequent forms of this pragma are only useful if
201 the main database has not already been created. In this case the
202 pragma sets the encoding that the main database will be created with if
203 it is created by this session. The string "UTF-16" is interpreted
204 as "UTF-16 encoding using native machine byte-ordering". If the second
205 and subsequent forms are used after the database file has already
206 been created, they have no effect and are silently ignored.</p>
207
208 <p>Once an encoding has been set for a database, it cannot be changed.</p>
209
210 <p>Databases created by the ATTACH command always use the same encoding
211 as the main database.</p>
212</li>
213
214<a name="pragma_full_column_names"></a>
215<li><p><b>PRAGMA full_column_names;
216 <br>PRAGMA full_column_names = </b><i>0 | 1</i><b>;</b></p>
217 <p>Query or change the full-column-names flag. This flag affects
218 the way SQLite names columns of data returned by SELECT statements
219 when the expression for the column is a table-column name or the
220 wildcard "*". Normally, such result columns are named
221 &lt;table-name/alias&gt;&lt;column-name&gt; if the SELECT statement joins
222 two or
223 more tables together, or simply &lt;column-name&gt; if the SELECT
224 statement queries a single table. When the full-column-names flag
225 is set, such columns are always named &lt;table-name/alias&gt;
226 &lt;column-name&gt; regardless of whether or not a join is performed.
227 </p>
228 <p>If both the short-column-names and full-column-names are set,
229 then the behaviour associated with the full-column-names flag is
230 exhibited.
231 </p>
232</li>
233
234<a name="pragma_fullfsync"></a>
235<li><p><b>PRAGMA fullfsync
236 <br>PRAGMA fullfsync = </b><i>0 | 1</i><b>;</b></p>
237 <p>Query or change the fullfsync flag. This flag affects
238 determines whether or not the F_FULLFSYNC syncing method is used
239 on systems that support it. The default value is off. As of this
240 writing (2006-02-10) only Mac OS X supports F_FULLFSYNC.
241 </p>
242</li>
243
244<a name="pragma_incremental_vacuum"></a>
245<li><p><b>PRAGMA incremental_vacuum</b><i>(N)</i><b>;</b></p>
246 <p>The incremental_vacuum pragma causes up to <i>N</i> pages to
247 be removed from the freelist. The database file is truncated by
248 the same amount. The incremental_vacuum pragma has no effect if
249 the database is not in
250 <a href="#pragma_auto_vacuum">auto_vacuum==incremental</a> mode
251 or if there are no pages on the freelist. If there are fewer than
252 <i>N</i> pages on the freelist, then the entire freelist is cleared.</p>
253
254 <p>As of version 3.4.0 (the first version that supports
255 incremental_vacuum) this feature is still experimental. Possible
256 future changes include enhancing incremental vacuum to do
257 defragmentation and node repacking just as the full-blown
258 <a href="lang_vacuum.html">VACUUM</a> command does. And
259 incremental vacuum may be promoted from a pragma to a separate
260 SQL command, or perhaps some variation on the VACUUM command.
261 Programmers are cautioned to not become enamored with the
262 current syntax or functionality as it is likely to change.</p>
263</li>
264
265
266<a name="pragma_legacy_file_format"></a>
267<li><p><b>PRAGMA legacy_file_format;
268 <br>PRAGMA legacy_file_format = <i>ON | OFF</i></b></p>
269 <p>This pragma sets or queries the value of the legacy_file_format
270 flag. When this flag is on, new SQLite databases are created in
271 a file format that is readable and writable by all versions of
272 SQLite going back to 3.0.0. When the flag is off, new databases
273 are created using the latest file format which might not be
274 readable or writable by older versions of SQLite.</p>
275
276 <p>This flag only affects newly created databases. It has no
277 effect on databases that already exist.</p>
278</li>
279
280<a name="pragma_locking_mode"></a>
281<li><p><b>PRAGMA locking_mode;
282 <br>PRAGMA locking_mode = <i>NORMAL | EXCLUSIVE</i></b></p>
283 <p>This pragma sets or queries the database connection locking-mode.
284 The locking-mode is either NORMAL or EXCLUSIVE.
285
286 <p>In NORMAL locking-mode (the default), a database connection
287 unlocks the database file at the conclusion of each read or
288 write transaction. When the locking-mode is set to EXCLUSIVE, the
289 database connection never releases file-locks. The first time the
290 database is read in EXCLUSIVE mode, a shared lock is obtained and
291 held. The first time the database is written, an exclusive lock is
292 obtained and held.</p>
293
294 <p>Database locks obtained by a connection in EXCLUSIVE mode may be
295 released either by closing the database connection, or by setting the
296 locking-mode back to NORMAL using this pragma and then accessing the
297 database file (for read or write). Simply setting the locking-mode to
298 NORMAL is not enough - locks are not be released until the next time
299 the database file is accessed.</p>
300
301 <p>There are two reasons to set the locking-mode to EXCLUSIVE. One
302 is if the application actually wants to prevent other processes from
303 accessing the database file. The other is that a small number of
304 filesystem operations are saved by optimizations enabled in this
305 mode. This may be significant in embedded environments.</p>
306
307 <p>When the locking_mode pragma specifies a particular database,
308 for example:</p>
309
310 <blockquote>
311PRAGMA <b>main.</b>locking_mode=EXCLUSIVE;
312 </blockquote>
313
314 <p>Then the locking mode applies only to the named database. If no
315 database name qualifier preceeds the "locking_mode" keyword then
316 the locking mode is applied to all databases, including any new
317 databases added by subsequent <a href="lang_attach.html">ATTACH</a>
318 commands.</p>
319
320 <p>The "temp" database (in which TEMP tables and indices are stored)
321 always uses exclusive locking mode. The locking mode of temp cannot
322 be changed. All other databases use the normal locking mode by default
323 and are affected by this pragma.</p>
324</li>
325
326<a name="pragma_page_size"></a>
327<li><p><b>PRAGMA page_size;
328 <br>PRAGMA page_size = </b><i>bytes</i><b>;</b></p>
329 <p>Query or set the page-size of the database. The page-size
330 may only be set if the database has not yet been created. The page
331 size must be a power of two greater than or equal to 512 and less
332 than or equal to 8192. The upper limit may be modified by setting
333 the value of macro SQLITE_MAX_PAGE_SIZE during compilation. The
334 maximum upper bound is 32768.
335 </p>
336</li>
337
338<a name="pragma_max_page_count"></a>
339<li><p><b>PRAGMA max_page_count;
340 <br>PRAGMA max_page_count = </b><i>N</i><b>;</b></p>
341 <p>Query or set the maximum number of pages in the database file.
342 Both forms of the pragma return the maximum page count. The second
343 form attempts to modify the maximum page count. The maximum page
344 count cannot be reduced below the current database size.
345 </p>
346</li>
347
348<a name="pragma_read_uncommitted"></a>
349<li><p><b>PRAGMA read_uncommitted;
350 <br>PRAGMA read_uncommitted = </b><i>0 | 1</i><b>;</b></p>
351 <p>Query, set, or clear READ UNCOMMITTED isolation. The default isolation
352 level for SQLite is SERIALIZABLE. Any process or thread can select
353 READ UNCOMMITTED isolation, but SERIALIZABLE will still be used except
354 between connections that share a common page and schema cache.
355 Cache sharing is enabled using the
356 <a href="capi3ref.html#sqlite3_enable_shared_cache">
357 sqlite3_enable_shared_cache()</a> API and is only available between
358 connections running the same thread. Cache sharing is off by default.
359 </p>
360</li>
361
362<a name="pragma_short_column_names"></a>
363<li><p><b>PRAGMA short_column_names;
364 <br>PRAGMA short_column_names = </b><i>0 | 1</i><b>;</b></p>
365 <p>Query or change the short-column-names flag. This flag affects
366 the way SQLite names columns of data returned by SELECT statements
367 when the expression for the column is a table-column name or the
368 wildcard "*". Normally, such result columns are named
369 &lt;table-name/alias&gt;lt;column-name&gt; if the SELECT statement
370 joins two or more tables together, or simply &lt;column-name&gt; if
371 the SELECT statement queries a single table. When the short-column-names
372 flag is set, such columns are always named &lt;column-name&gt;
373 regardless of whether or not a join is performed.
374 </p>
375 <p>If both the short-column-names and full-column-names are set,
376 then the behaviour associated with the full-column-names flag is
377 exhibited.
378 </p>
379</li>
380
381<a name="pragma_synchronous"></a>
382<li><p><b>PRAGMA synchronous;
383 <br>PRAGMA synchronous = FULL; </b>(2)<b>
384 <br>PRAGMA synchronous = NORMAL; </b>(1)<b>
385 <br>PRAGMA synchronous = OFF; </b>(0)</p>
386 <p>Query or change the setting of the "synchronous" flag.
387 The first (query) form will return the setting as an
388 integer. When synchronous is FULL (2), the SQLite database engine will
389 pause at critical moments to make sure that data has actually been
390 written to the disk surface before continuing. This ensures that if
391 the operating system crashes or if there is a power failure, the database
392 will be uncorrupted after rebooting. FULL synchronous is very
393 safe, but it is also slow.
394 When synchronous is NORMAL, the SQLite database
395 engine will still pause at the most critical moments, but less often
396 than in FULL mode. There is a very small (though non-zero) chance that
397 a power failure at just the wrong time could corrupt the database in
398 NORMAL mode. But in practice, you are more likely to suffer
399 a catastrophic disk failure or some other unrecoverable hardware
400 fault.
401 With synchronous OFF (0), SQLite continues without pausing
402 as soon as it has handed data off to the operating system.
403 If the application running SQLite crashes, the data will be safe, but
404 the database might become corrupted if the operating system
405 crashes or the computer loses power before that data has been written
406 to the disk surface. On the other hand, some
407 operations are as much as 50 or more times faster with synchronous OFF.
408 </p>
409 <p>In SQLite version 2, the default value is NORMAL. For version 3, the
410 default was changed to FULL.
411 </p>
412</li>
413
414
415<a name="pragma_temp_store"></a>
416<li><p><b>PRAGMA temp_store;
417 <br>PRAGMA temp_store = DEFAULT;</b> (0)<b>
418 <br>PRAGMA temp_store = FILE;</b> (1)<b>
419 <br>PRAGMA temp_store = MEMORY;</b> (2)</p>
420 <p>Query or change the setting of the "<b>temp_store</b>" parameter.
421 When temp_store is DEFAULT (0), the compile-time C preprocessor macro
422 TEMP_STORE is used to determine where temporary tables and indices
423 are stored. When
424 temp_store is MEMORY (2) temporary tables and indices are kept in memory.
425 When temp_store is FILE (1) temporary tables and indices are stored
426 in a file. The <a href="#pragma_temp_store_directory">
427 temp_store_directory</a> pragma can be used to specify the directory
428 containing this file.
429 <b>FILE</b> is specified. When the temp_store setting is changed,
430 all existing temporary tables, indices, triggers, and views are
431 immediately deleted.</p>
432
433 <p>It is possible for the library compile-time C preprocessor symbol
434 TEMP_STORE to override this pragma setting. The following table summarizes
435 the interaction of the TEMP_STORE preprocessor macro and the
436 temp_store pragma:</p>
437
438 <blockquote>
439 <table cellpadding="2" border="1">
440 <tr><th valign="bottom">TEMP_STORE</th>
441 <th valign="bottom">PRAGMA<br>temp_store</th>
442 <th>Storage used for<br>TEMP tables and indices</th></tr>
443 <tr><td align="center">0</td>
444 <td align="center"><em>any</em></td>
445 <td align="center">file</td></tr>
446 <tr><td align="center">1</td>
447 <td align="center">0</td>
448 <td align="center">file</td></tr>
449 <tr><td align="center">1</td>
450 <td align="center">1</td>
451 <td align="center">file</td></tr>
452 <tr><td align="center">1</td>
453 <td align="center">2</td>
454 <td align="center">memory</td></tr>
455 <tr><td align="center">2</td>
456 <td align="center">0</td>
457 <td align="center">memory</td></tr>
458 <tr><td align="center">2</td>
459 <td align="center">1</td>
460 <td align="center">file</td></tr>
461 <tr><td align="center">2</td>
462 <td align="center">2</td>
463 <td align="center">memory</td></tr>
464 <tr><td align="center">3</td>
465 <td align="center"><em>any</em></td>
466 <td align="center">memory</td></tr>
467 </table>
468 </blockquote>
469 </li>
470 <br>
471
472<a name="pragma_temp_store_directory"></a>
473<li><p><b>PRAGMA temp_store_directory;
474 <br>PRAGMA temp_store_directory = 'directory-name';</b></p>
475 <p>Query or change the setting of the "temp_store_directory" - the
476 directory where files used for storing temporary tables and indices
477 are kept. This setting lasts for the duration of the current connection
478 only and resets to its default value for each new connection opened.
479
480 <p>When the temp_store_directory setting is changed, all existing temporary
481 tables, indices, triggers, and viewers are immediately deleted. In
482 practice, temp_store_directory should be set immediately after the
483 database is opened. </p>
484
485 <p>The value <i>directory-name</i> should be enclosed in single quotes.
486 To revert the directory to the default, set the <i>directory-name</i> to
487 an empty string, e.g., <i>PRAGMA temp_store_directory = ''</i>. An
488 error is raised if <i>directory-name</i> is not found or is not
489 writable. </p>
490
491 <p>The default directory for temporary files depends on the OS. For
492 Unix/Linux/OSX, the default is the is the first writable directory found
493 in the list of: <b>/var/tmp, /usr/tmp, /tmp,</b> and <b>
494 <i>current-directory</i></b>. For Windows NT, the default
495 directory is determined by Windows, generally
496 <b>C:\Documents and Settings\<i>user-name</i>\Local Settings\Temp\</b>.
497 Temporary files created by SQLite are unlinked immediately after
498 opening, so that the operating system can automatically delete the
499 files when the SQLite process exits. Thus, temporary files are not
500 normally visible through <i>ls</i> or <i>dir</i> commands.</p>
501
502 </li>
503</ul>
504}
505
506Section {Pragmas to query the database schema} schema
507
508puts {
509<ul>
510<a name="pragma_database_list"></a>
511<li><p><b>PRAGMA database_list;</b></p>
512 <p>For each open database, invoke the callback function once with
513 information about that database. Arguments include the index and
514 the name the database was attached with. The first row will be for
515 the main database. The second row will be for the database used to
516 store temporary tables.</p></li>
517
518<a name="pragma_foreign_key_list"></a>
519<li><p><b>PRAGMA foreign_key_list(</b><i>table-name</i><b>);</b></p>
520 <p>For each foreign key that references a column in the argument
521 table, invoke the callback function with information about that
522 foreign key. The callback function will be invoked once for each
523 column in each foreign key.</p></li>
524
525<a name="pragma_freelist_count"></a>
526<li><p><b>PRAGMA [database].freelist_count;</b></p>
527 <p>Return the number of unused pages in the database file. Running
528 a <a href="#pragma_incremental_vacuum">"PRAGMA incremental_vaccum(N);"</a>
529 command with a large value of N will shrink the database file by this
530 number of pages. </p></li>
531
532<a name="pragma_index_info"></a>
533<li><p><b>PRAGMA index_info(</b><i>index-name</i><b>);</b></p>
534 <p>For each column that the named index references, invoke the
535 callback function
536 once with information about that column, including the column name,
537 and the column number.</p></li>
538
539<a name="pragma_index_list"></a>
540<li><p><b>PRAGMA index_list(</b><i>table-name</i><b>);</b></p>
541 <p>For each index on the named table, invoke the callback function
542 once with information about that index. Arguments include the
543 index name and a flag to indicate whether or not the index must be
544 unique.</p></li>
545
546<a name="pragma_table_info"></a>
547<li><p><b>PRAGMA table_info(</b><i>table-name</i><b>);</b></p>
548 <p>For each column in the named table, invoke the callback function
549 once with information about that column, including the column name,
550 data type, whether or not the column can be NULL, and the default
551 value for the column.</p></li>
552</ul>
553}
554
555Section {Pragmas to query/modify version values} version
556
557puts {
558
559<ul>
560<a name="pragma_schema_version"></a>
561<a name="pragma_user_version"></a>
562<li><p><b>PRAGMA [database.]schema_version;
563 <br>PRAGMA [database.]schema_version = </b><i>integer </i><b>;
564 <br>PRAGMA [database.]user_version;
565 <br>PRAGMA [database.]user_version = </b><i>integer </i><b>;</b>
566
567
568<p> The pragmas schema_version and user_version are used to set or get
569 the value of the schema-version and user-version, respectively. Both
570 the schema-version and the user-version are 32-bit signed integers
571 stored in the database header.</p>
572
573<p> The schema-version is usually only manipulated internally by SQLite.
574 It is incremented by SQLite whenever the database schema is modified
575 (by creating or dropping a table or index). The schema version is
576 used by SQLite each time a query is executed to ensure that the
577 internal cache of the schema used when compiling the SQL query matches
578 the schema of the database against which the compiled query is actually
579 executed. Subverting this mechanism by using "PRAGMA schema_version"
580 to modify the schema-version is potentially dangerous and may lead
581 to program crashes or database corruption. Use with caution!</p>
582
583<p> The user-version is not used internally by SQLite. It may be used by
584 applications for any purpose.</p>
585</li>
586</ul>
587}
588
589Section {Pragmas to debug the library} debug
590
591puts {
592<ul>
593<a name="pragma_integrity_check"></a>
594<li><p><b>PRAGMA integrity_check;
595 <br>PRAGMA integrity_check(</b><i>integer</i><b>)</b></p>
596 <p>The command does an integrity check of the entire database. It
597 looks for out-of-order records, missing pages, malformed records, and
598 corrupt indices.
599 If any problems are found, then strings are returned (as multiple
600 rows with a single column per row) which describe
601 the problems. At most <i>integer</i> errors will be reported
602 before the analysis quits. The default value for <i>integer</i>
603 is 100. If no errors are found, a single row with the value "ok" is
604 returned.</p></li>
605
606<a name="pragma_parser_trace"></a>
607<li><p><b>PRAGMA parser_trace = ON; </b>(1)<b>
608 <br>PRAGMA parser_trace = OFF;</b> (0)</p>
609 <p>Turn tracing of the SQL parser inside of the
610 SQLite library on and off. This is used for debugging.
611 This only works if the library is compiled without the NDEBUG macro.
612 </p></li>
613
614<a name="pragma_vdbe_trace"></a>
615<li><p><b>PRAGMA vdbe_trace = ON; </b>(1)<b>
616 <br>PRAGMA vdbe_trace = OFF;</b> (0)</p>
617 <p>Turn tracing of the virtual database engine inside of the
618 SQLite library on and off. This is used for debugging. See the
619 <a href="vdbe.html#trace">VDBE documentation</a> for more
620 information.</p></li>
621
622<a name="pragma_vdbe_listing"></a>
623<li><p><b>PRAGMA vdbe_listing = ON; </b>(1)<b>
624 <br>PRAGMA vdbe_listing = OFF;</b> (0)</p>
625 <p>Turn listings of virtual machine programs on and off.
626 With listing is on, the entire content of a program is printed
627 just prior to beginning execution. This is like automatically
628 executing an EXPLAIN prior to each statement. The statement
629 executes normally after the listing is printed.
630 This is used for debugging. See the
631 <a href="vdbe.html#trace">VDBE documentation</a> for more
632 information.</p></li>
633</ul>
634
635}
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/quickstart.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/quickstart.tcl
deleted file mode 100644
index 8ae3d72..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/quickstart.tcl
+++ /dev/null
@@ -1,110 +0,0 @@
1#
2# Run this TCL script to generate HTML for the quickstart.html file.
3#
4set rcsid {$Id: quickstart.tcl,v 1.8 2006/06/13 11:27:22 drh Exp $}
5source common.tcl
6header {SQLite In 5 Minutes Or Less}
7puts {
8<p>Here is what you do to start experimenting with SQLite without having
9to do a lot of tedious reading and configuration:</p>
10
11<h2>Download The Code</h2>
12
13<ul>
14<li><p>Get a copy of the prebuilt binaries for your machine, or get a copy
15of the sources and compile them yourself. Visit
16the <a href="download.html">download</a> page for more information.</p></li>
17</ul>
18
19<h2>Create A New Database</h2>
20
21<ul>
22<li><p>At a shell or DOS prompt, enter: "<b>sqlite3 test.db</b>". This will
23create a new database named "test.db". (You can use a different name if
24you like.)</p></li>
25<li><p>Enter SQL commands at the prompt to create and populate the
26new database.</p></li>
27<li><p>Additional documentation is available <a href="sqlite.html">here</a></li>
28</ul>
29
30<h2>Write Programs That Use SQLite</h2>
31
32<ul>
33<li><p>Below is a simple TCL program that demonstrates how to use
34the TCL interface to SQLite. The program executes the SQL statements
35given as the second argument on the database defined by the first
36argument. The commands to watch for are the <b>sqlite3</b> command
37on line 7 which opens an SQLite database and creates
38a new TCL command named "<b>db</b>" to access that database, the
39invocation of the <b>db</b> command on line 8 to execute
40SQL commands against the database, and the closing of the database connection
41on the last line of the script.</p>
42
43<blockquote><pre>
44#!/usr/bin/tclsh
45if {$argc!=2} {
46 puts stderr "Usage: %s DATABASE SQL-STATEMENT"
47 exit 1
48}
49load /usr/lib/tclsqlite3.so Sqlite3
50<b>sqlite3</b> db [lindex $argv 0]
51<b>db</b> eval [lindex $argv 1] x {
52 foreach v $x(*) {
53 puts "$v = $x($v)"
54 }
55 puts ""
56}
57<b>db</b> close
58</pre></blockquote>
59</li>
60
61<li><p>Below is a simple C program that demonstrates how to use
62the C/C++ interface to SQLite. The name of a database is given by
63the first argument and the second argument is one or more SQL statements
64to execute against the database. The function calls to pay attention
65to here are the call to <b>sqlite3_open()</b> on line 22 which opens
66the database, <b>sqlite3_exec()</b> on line 27 that executes SQL
67commands against the database, and <b>sqlite3_close()</b> on line 31
68that closes the database connection.</p>
69
70<blockquote><pre>
71#include &lt;stdio.h&gt;
72#include &lt;sqlite3.h&gt;
73
74static int callback(void *NotUsed, int argc, char **argv, char **azColName){
75 int i;
76 for(i=0; i&lt;argc; i++){
77 printf("%s = %s\n", azColName[i], argv[i] ? argv[i] : "NULL");
78 }
79 printf("\n");
80 return 0;
81}
82
83int main(int argc, char **argv){
84 sqlite3 *db;
85 char *zErrMsg = 0;
86 int rc;
87
88 if( argc!=3 ){
89 fprintf(stderr, "Usage: %s DATABASE SQL-STATEMENT\n", argv[0]);
90 exit(1);
91 }
92 rc = <b>sqlite3_open</b>(argv[1], &db);
93 if( rc ){
94 fprintf(stderr, "Can't open database: %s\n", sqlite3_errmsg(db));
95 sqlite3_close(db);
96 exit(1);
97 }
98 rc = <b>sqlite3_exec</b>(db, argv[2], callback, 0, &zErrMsg);
99 if( rc!=SQLITE_OK ){
100 fprintf(stderr, "SQL error: %s\n", zErrMsg);
101 sqlite3_free(zErrMsg);
102 }
103 <b>sqlite3_close</b>(db);
104 return 0;
105}
106</pre></blockquote>
107</li>
108</ul>
109}
110footer {$Id: quickstart.tcl,v 1.8 2006/06/13 11:27:22 drh Exp $}
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/shared.gif b/libraries/sqlite/unix/sqlite-3.5.1/www/shared.gif
deleted file mode 100644
index 9b7be7c..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/shared.gif
+++ /dev/null
Binary files differ
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/sharedcache.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/sharedcache.tcl
deleted file mode 100644
index c06c888..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/sharedcache.tcl
+++ /dev/null
@@ -1,221 +0,0 @@
1#
2# Run this script to generated a sharedcache.html output file
3#
4set rcsid {$Id: }
5source common.tcl
6header {SQLite Shared-Cache Mode}
7
8proc HEADING {level title} {
9 global pnum
10 incr pnum($level)
11 foreach i [array names pnum] {
12 if {$i>$level} {set pnum($i) 0}
13 }
14 set h [expr {$level+1}]
15 if {$h>6} {set h 6}
16 set n $pnum(1).$pnum(2)
17 for {set i 3} {$i<=$level} {incr i} {
18 append n .$pnum($i)
19 }
20 puts "<h$h>$n $title</h$h>"
21}
22set pnum(1) 0
23set pnum(2) 0
24set pnum(3) 0
25set pnum(4) 0
26set pnum(5) 0
27set pnum(6) 0
28set pnum(7) 0
29set pnum(8) 0
30
31HEADING 1 {SQLite Shared-Cache Mode}
32
33puts {
34<p>Starting with version 3.3.0, SQLite includes a special "shared-cache"
35mode (disabled by default) intended for use in embedded servers. If
36shared-cache mode is enabled and a thread establishes multiple connections
37to the same database, the connections share a single data and schema cache.
38This can significantly reduce the quantity of memory and IO required by
39the system.</p>
40
41<p>Using shared-cache mode imposes some extra restrictions on
42passing database handles between threads and changes the semantics
43of the locking model in some cases. These details are described in full by
44this document. A basic understanding of the normal SQLite locking model (see
45<a href="lockingv3.html">File Locking And Concurrency In SQLite Version 3</a>
46for details) is assumed.</p>
47}
48
49HEADING 1 {Shared-Cache Locking Model}
50
51puts {
52<p>Externally, from the point of view of another process or thread, two
53or more database connections using a shared-cache appear as a single
54connection. The locking protocol used to arbitrate between multiple
55shared-caches or regular database users is described elsewhere.
56</p>
57
58<table style="margin:auto">
59<tr><td>
60<img src="shared.gif">
61<!-- <pre>
62 +--------------+ +--------------+
63 | Connection 2 | | Connection 3 |
64 +--------------+ +--------------+
65 | |
66 V V
67+--------------+ +--------------+
68| Connection 1 | | Shared cache |
69+--------------+ +--------------+
70 | |
71 V V
72 +----------------+
73 | Database |
74 +----------------+
75</pre> -->
76</table>
77<p style="font-style:italic;text-align:center">Figure 1</p>
78
79<p>Figure 1 depicts an example runtime configuration where three
80database connections have been established. Connection 1 is a normal
81SQLite database connection. Connections 2 and 3 share a cache (and so must
82have been established by the same process thread). The normal locking
83protocol is used to serialize database access between connection 1 and
84the shared cache. The internal protocol used to serialize (or not, see
85"Read-Uncommitted Isolation Mode" below) access to the shared-cache by
86connections 2 and 3 is described in the remainder of this section.
87</p>
88
89<p>There are three levels to the shared-cache locking model,
90transaction level locking, table level locking and schema level locking.
91They are described in the following three sub-sections.</p>
92
93}
94
95HEADING 2 {Transaction Level Locking}
96
97puts {
98<p>SQLite connections can open two kinds of transactions, read and write
99transactions. This is not done explicitly, a transaction is implicitly a
100read-transaction until it first writes to a database table, at which point
101it becomes a write-transaction.
102</p>
103<p>At most one connection to a single shared cache may open a
104write transaction at any one time. This may co-exist with any number of read
105transactions.
106</p>
107}
108
109HEADING 2 {Table Level Locking}
110
111puts {
112<p>When two or more connections use a shared-cache, locks are used to
113serialize concurrent access attempts on a per-table basis. Tables support
114two types of locks, "read-locks" and "write-locks". Locks are granted to
115connections - at any one time, each database connection has either a
116read-lock, write-lock or no lock on each database table.
117</p>
118
119<p>At any one time, a single table may have any number of active read-locks
120or a single active write lock. To read data a table, a connection must
121first obtain a read-lock. To write to a table, a connection must obtain a
122write-lock on that table. If a required table lock cannot be obtained,
123the query fails and SQLITE_LOCKED is returned to the caller.
124</p>
125
126<p>Once a connection obtains a table lock, it is not released until the
127current transaction (read or write) is concluded.
128</p>
129}
130
131HEADING 3 {Read-Uncommitted Isolation Mode}
132
133puts {
134<p>The behaviour described above may be modified slightly by using the
135<i>read_uncommitted</i> pragma to change the isolation level from serialized
136(the default), to read-uncommitted.</p>
137
138<p> A database connection in read-uncommitted mode does not attempt
139to obtain read-locks before reading from database tables as described
140above. This can lead to inconsistent query results if another database
141connection modifies a table while it is being read, but it also means that
142a read-transaction opened by a connection in read-uncommitted mode can
143neither block nor be blocked by any other connection.</p>
144
145<p>Read-uncommitted mode has no effect on the locks required to write to
146database tables (i.e. read-uncommitted connections must still obtain
147write-locks and hence database writes may still block or be blocked).
148Also, read-uncommitted mode has no effect on the <i>sqlite_master</i>
149locks required by the rules enumerated below (see section
150"Schema (sqlite_master) Level Locking").
151</p>
152
153<pre>
154 /* Set the value of the read-uncommitted flag:
155 **
156 ** True -> Set the connection to read-uncommitted mode.
157 ** False -> Set the connectino to serialized (the default) mode.
158 */
159 PRAGMA read_uncommitted = &lt;boolean&gt;;
160
161 /* Retrieve the current value of the read-uncommitted flag */
162 PRAGMA read_uncommitted;
163</pre>
164}
165
166HEADING 2 {Schema (sqlite_master) Level Locking}
167
168puts {
169<p>The <i>sqlite_master</i> table supports shared-cache read and write
170locks in the same way as all other database tables (see description
171above). The following special rules also apply:
172</p>
173
174<ul>
175<li>A connection must obtain a read-lock on <i>sqlite_master</i> before
176accessing any database tables or obtaining any other read or write locks.</li>
177<li>Before executing a statement that modifies the database schema (i.e.
178a CREATE or DROP TABLE statement), a connection must obtain a write-lock on
179<i>sqlite_master</i>.
180</li>
181<li>A connection may not compile an SQL statement if any other connection
182is holding a write-lock on the <i>sqlite_master</i> table of any attached
183database (including the default database, "main").
184</li>
185</ul>
186}
187
188HEADING 1 {Thread Related Issues}
189
190puts {
191<p>When shared-cache mode is enabled, a database connection may only be
192used by the thread that called sqlite3_open() to create it. If another
193thread attempts to use the database connection, in most cases an
194SQLITE_MISUSE error is returned. However this is not guaranteed and
195programs should not depend on this behaviour, in some cases a segfault
196may result.
197</p>
198}
199
200HEADING 1 {Enabling Shared-Cache Mode}
201
202puts {
203<p>Shared-cache mode is enabled on a thread-wide basis. Using the C
204interface, the following API can be used to enable or disable shared-cache
205mode for the calling thread:
206</p>
207
208<pre>
209int sqlite3_enable_shared_cache(int);
210</pre>
211
212<p>It is illegal to call sqlite3_enable_shared_cache() if one or more
213open database connections were opened by the calling thread. If the argument
214is non-zero, shared-cache mode is enabled. If the argument is zero,
215shared-cache mode is disabled. The return value is either SQLITE_OK (if the
216operation was successful), SQLITE_NOMEM (if a malloc() failed), or
217SQLITE_MISUSE (if the thread has open database connections).
218</p>
219}
220
221footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/speed.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/speed.tcl
deleted file mode 100644
index b60cfe1..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/speed.tcl
+++ /dev/null
@@ -1,495 +0,0 @@
1#
2# Run this Tcl script to generate the speed.html file.
3#
4set rcsid {$Id: speed.tcl,v 1.17 2005/03/12 15:55:11 drh Exp $ }
5source common.tcl
6header {SQLite Database Speed Comparison}
7
8puts {
9<h2>Database Speed Comparison</h2>
10
11<font color="red"><b>
12Note: This document is old. It describes a speed comparison between
13an older version of SQLite against archaic versions of MySQL and PostgreSQL.
14Readers are invited to contribute more up-to-date speed comparisons
15on the <a href="http://www.sqlite.org/cvstrac/wiki">SQLite Wiki</a>.
16<p>
17The numbers here are old enough to be nearly meaningless. Until it is
18updated, use this document only as proof that SQLite is not a
19sluggard.
20</b></font>
21
22<h3>Executive Summary</h3>
23
24<p>A series of tests were run to measure the relative performance of
25SQLite 2.7.6, PostgreSQL 7.1.3, and MySQL 3.23.41.
26The following are general
27conclusions drawn from these experiments:
28</p>
29
30<ul>
31<li><p>
32 SQLite 2.7.6 is significantly faster (sometimes as much as 10 or
33 20 times faster) than the default PostgreSQL 7.1.3 installation
34 on RedHat 7.2 for most common operations.
35</p></li>
36<li><p>
37 SQLite 2.7.6 is often faster (sometimes
38 more than twice as fast) than MySQL 3.23.41
39 for most common operations.
40</p></li>
41<li><p>
42 SQLite does not execute CREATE INDEX or DROP TABLE as fast as
43 the other databases. But this is not seen as a problem because
44 those are infrequent operations.
45</p></li>
46<li><p>
47 SQLite works best if you group multiple operations together into
48 a single transaction.
49</p></li>
50</ul>
51
52<p>
53The results presented here come with the following caveats:
54</p>
55
56<ul>
57<li><p>
58 These tests did not attempt to measure multi-user performance or
59 optimization of complex queries involving multiple joins and subqueries.
60</p></li>
61<li><p>
62 These tests are on a relatively small (approximately 14 megabyte) database.
63 They do not measure how well the database engines scale to larger problems.
64</p></li>
65</ul>
66
67<h3>Test Environment</h3>
68
69<p>
70The platform used for these tests is a 1.6GHz Athlon with 1GB or memory
71and an IDE disk drive. The operating system is RedHat Linux 7.2 with
72a stock kernel.
73</p>
74
75<p>
76The PostgreSQL and MySQL servers used were as delivered by default on
77RedHat 7.2. (PostgreSQL version 7.1.3 and MySQL version 3.23.41.)
78No effort was made to tune these engines. Note in particular
79the the default MySQL configuration on RedHat 7.2 does not support
80transactions. Not having to support transactions gives MySQL a
81big speed advantage, but SQLite is still able to hold its own on most
82tests.
83</p>
84
85<p>
86I am told that the default PostgreSQL configuration in RedHat 7.3
87is unnecessarily conservative (it is designed to
88work on a machine with 8MB of RAM) and that PostgreSQL could
89be made to run a lot faster with some knowledgeable configuration
90tuning.
91Matt Sergeant reports that he has tuned his PostgreSQL installation
92and rerun the tests shown below. His results show that
93PostgreSQL and MySQL run at about the same speed. For Matt's
94results, visit
95</p>
96
97<blockquote>
98<a href="http://www.sergeant.org/sqlite_vs_pgsync.html">
99http://www.sergeant.org/sqlite_vs_pgsync.html</a>
100</blockquote>
101
102<p>
103SQLite was tested in the same configuration that it appears
104on the website. It was compiled with -O6 optimization and with
105the -DNDEBUG=1 switch which disables the many "assert()" statements
106in the SQLite code. The -DNDEBUG=1 compiler option roughly doubles
107the speed of SQLite.
108</p>
109
110<p>
111All tests are conducted on an otherwise quiescent machine.
112A simple Tcl script was used to generate and run all the tests.
113A copy of this Tcl script can be found in the SQLite source tree
114in the file <b>tools/speedtest.tcl</b>.
115</p>
116
117<p>
118The times reported on all tests represent wall-clock time
119in seconds. Two separate time values are reported for SQLite.
120The first value is for SQLite in its default configuration with
121full disk synchronization turned on. With synchronization turned
122on, SQLite executes
123an <b>fsync()</b> system call (or the equivalent) at key points
124to make certain that critical data has
125actually been written to the disk drive surface. Synchronization
126is necessary to guarantee the integrity of the database if the
127operating system crashes or the computer powers down unexpectedly
128in the middle of a database update. The second time reported for SQLite is
129when synchronization is turned off. With synchronization off,
130SQLite is sometimes much faster, but there is a risk that an
131operating system crash or an unexpected power failure could
132damage the database. Generally speaking, the synchronous SQLite
133times are for comparison against PostgreSQL (which is also
134synchronous) and the asynchronous SQLite times are for
135comparison against the asynchronous MySQL engine.
136</p>
137
138<h3>Test 1: 1000 INSERTs</h3>
139<blockquote>
140CREATE TABLE t1(a INTEGER, b INTEGER, c VARCHAR(100));<br>
141INSERT INTO t1 VALUES(1,13153,'thirteen thousand one hundred fifty three');<br>
142INSERT INTO t1 VALUES(2,75560,'seventy five thousand five hundred sixty');<br>
143<i>... 995 lines omitted</i><br>
144INSERT INTO t1 VALUES(998,66289,'sixty six thousand two hundred eighty nine');<br>
145INSERT INTO t1 VALUES(999,24322,'twenty four thousand three hundred twenty two');<br>
146INSERT INTO t1 VALUES(1000,94142,'ninety four thousand one hundred forty two');<br>
147
148</blockquote><table border=0 cellpadding=0 cellspacing=0>
149<tr><td>PostgreSQL:</td><td align="right">&nbsp;&nbsp;&nbsp;4.373</td></tr>
150<tr><td>MySQL:</td><td align="right">&nbsp;&nbsp;&nbsp;0.114</td></tr>
151<tr><td>SQLite 2.7.6:</td><td align="right">&nbsp;&nbsp;&nbsp;13.061</td></tr>
152<tr><td>SQLite 2.7.6 (nosync):</td><td align="right">&nbsp;&nbsp;&nbsp;0.223</td></tr>
153</table>
154
155<p>
156Because it does not have a central server to coordinate access,
157SQLite must close and reopen the database file, and thus invalidate
158its cache, for each transaction. In this test, each SQL statement
159is a separate transaction so the database file must be opened and closed
160and the cache must be flushed 1000 times. In spite of this, the asynchronous
161version of SQLite is still nearly as fast as MySQL. Notice how much slower
162the synchronous version is, however. SQLite calls <b>fsync()</b> after
163each synchronous transaction to make sure that all data is safely on
164the disk surface before continuing. For most of the 13 seconds in the
165synchronous test, SQLite was sitting idle waiting on disk I/O to complete.</p>
166
167
168<h3>Test 2: 25000 INSERTs in a transaction</h3>
169<blockquote>
170BEGIN;<br>
171CREATE TABLE t2(a INTEGER, b INTEGER, c VARCHAR(100));<br>
172INSERT INTO t2 VALUES(1,59672,'fifty nine thousand six hundred seventy two');<br>
173<i>... 24997 lines omitted</i><br>
174INSERT INTO t2 VALUES(24999,89569,'eighty nine thousand five hundred sixty nine');<br>
175INSERT INTO t2 VALUES(25000,94666,'ninety four thousand six hundred sixty six');<br>
176COMMIT;<br>
177
178</blockquote><table border=0 cellpadding=0 cellspacing=0>
179<tr><td>PostgreSQL:</td><td align="right">&nbsp;&nbsp;&nbsp;4.900</td></tr>
180<tr><td>MySQL:</td><td align="right">&nbsp;&nbsp;&nbsp;2.184</td></tr>
181<tr><td>SQLite 2.7.6:</td><td align="right">&nbsp;&nbsp;&nbsp;0.914</td></tr>
182<tr><td>SQLite 2.7.6 (nosync):</td><td align="right">&nbsp;&nbsp;&nbsp;0.757</td></tr>
183</table>
184
185<p>
186When all the INSERTs are put in a transaction, SQLite no longer has to
187close and reopen the database or invalidate its cache between each statement.
188It also does not
189have to do any fsync()s until the very end. When unshackled in
190this way, SQLite is much faster than either PostgreSQL and MySQL.
191</p>
192
193<h3>Test 3: 25000 INSERTs into an indexed table</h3>
194<blockquote>
195BEGIN;<br>
196CREATE TABLE t3(a INTEGER, b INTEGER, c VARCHAR(100));<br>
197CREATE INDEX i3 ON t3(c);<br>
198<i>... 24998 lines omitted</i><br>
199INSERT INTO t3 VALUES(24999,88509,'eighty eight thousand five hundred nine');<br>
200INSERT INTO t3 VALUES(25000,84791,'eighty four thousand seven hundred ninety one');<br>
201COMMIT;<br>
202
203</blockquote><table border=0 cellpadding=0 cellspacing=0>
204<tr><td>PostgreSQL:</td><td align="right">&nbsp;&nbsp;&nbsp;8.175</td></tr>
205<tr><td>MySQL:</td><td align="right">&nbsp;&nbsp;&nbsp;3.197</td></tr>
206<tr><td>SQLite 2.7.6:</td><td align="right">&nbsp;&nbsp;&nbsp;1.555</td></tr>
207<tr><td>SQLite 2.7.6 (nosync):</td><td align="right">&nbsp;&nbsp;&nbsp;1.402</td></tr>
208</table>
209
210<p>
211There were reports that SQLite did not perform as well on an indexed table.
212This test was recently added to disprove those rumors. It is true that
213SQLite is not as fast at creating new index entries as the other engines
214(see Test 6 below) but its overall speed is still better.
215</p>
216
217<h3>Test 4: 100 SELECTs without an index</h3>
218<blockquote>
219BEGIN;<br>
220SELECT count(*), avg(b) FROM t2 WHERE b>=0 AND b<1000;<br>
221SELECT count(*), avg(b) FROM t2 WHERE b>=100 AND b<1100;<br>
222<i>... 96 lines omitted</i><br>
223SELECT count(*), avg(b) FROM t2 WHERE b>=9800 AND b<10800;<br>
224SELECT count(*), avg(b) FROM t2 WHERE b>=9900 AND b<10900;<br>
225COMMIT;<br>
226
227</blockquote><table border=0 cellpadding=0 cellspacing=0>
228<tr><td>PostgreSQL:</td><td align="right">&nbsp;&nbsp;&nbsp;3.629</td></tr>
229<tr><td>MySQL:</td><td align="right">&nbsp;&nbsp;&nbsp;2.760</td></tr>
230<tr><td>SQLite 2.7.6:</td><td align="right">&nbsp;&nbsp;&nbsp;2.494</td></tr>
231<tr><td>SQLite 2.7.6 (nosync):</td><td align="right">&nbsp;&nbsp;&nbsp;2.526</td></tr>
232</table>
233
234
235<p>
236This test does 100 queries on a 25000 entry table without an index,
237thus requiring a full table scan. Prior versions of SQLite used to
238be slower than PostgreSQL and MySQL on this test, but recent performance
239enhancements have increased its speed so that it is now the fastest
240of the group.
241</p>
242
243<h3>Test 5: 100 SELECTs on a string comparison</h3>
244<blockquote>
245BEGIN;<br>
246SELECT count(*), avg(b) FROM t2 WHERE c LIKE '%one%';<br>
247SELECT count(*), avg(b) FROM t2 WHERE c LIKE '%two%';<br>
248<i>... 96 lines omitted</i><br>
249SELECT count(*), avg(b) FROM t2 WHERE c LIKE '%ninety nine%';<br>
250SELECT count(*), avg(b) FROM t2 WHERE c LIKE '%one hundred%';<br>
251COMMIT;<br>
252
253</blockquote><table border=0 cellpadding=0 cellspacing=0>
254<tr><td>PostgreSQL:</td><td align="right">&nbsp;&nbsp;&nbsp;13.409</td></tr>
255<tr><td>MySQL:</td><td align="right">&nbsp;&nbsp;&nbsp;4.640</td></tr>
256<tr><td>SQLite 2.7.6:</td><td align="right">&nbsp;&nbsp;&nbsp;3.362</td></tr>
257<tr><td>SQLite 2.7.6 (nosync):</td><td align="right">&nbsp;&nbsp;&nbsp;3.372</td></tr>
258</table>
259
260<p>
261This test still does 100 full table scans but it uses
262uses string comparisons instead of numerical comparisons.
263SQLite is over three times faster than PostgreSQL here and about 30%
264faster than MySQL.
265</p>
266
267<h3>Test 6: Creating an index</h3>
268<blockquote>
269CREATE INDEX i2a ON t2(a);<br>CREATE INDEX i2b ON t2(b);
270</blockquote><table border=0 cellpadding=0 cellspacing=0>
271<tr><td>PostgreSQL:</td><td align="right">&nbsp;&nbsp;&nbsp;0.381</td></tr>
272<tr><td>MySQL:</td><td align="right">&nbsp;&nbsp;&nbsp;0.318</td></tr>
273<tr><td>SQLite 2.7.6:</td><td align="right">&nbsp;&nbsp;&nbsp;0.777</td></tr>
274<tr><td>SQLite 2.7.6 (nosync):</td><td align="right">&nbsp;&nbsp;&nbsp;0.659</td></tr>
275</table>
276
277<p>
278SQLite is slower at creating new indices. This is not a huge problem
279(since new indices are not created very often) but it is something that
280is being worked on. Hopefully, future versions of SQLite will do better
281here.
282</p>
283
284<h3>Test 7: 5000 SELECTs with an index</h3>
285<blockquote>
286SELECT count(*), avg(b) FROM t2 WHERE b>=0 AND b<100;<br>
287SELECT count(*), avg(b) FROM t2 WHERE b>=100 AND b<200;<br>
288SELECT count(*), avg(b) FROM t2 WHERE b>=200 AND b<300;<br>
289<i>... 4994 lines omitted</i><br>
290SELECT count(*), avg(b) FROM t2 WHERE b>=499700 AND b<499800;<br>
291SELECT count(*), avg(b) FROM t2 WHERE b>=499800 AND b<499900;<br>
292SELECT count(*), avg(b) FROM t2 WHERE b>=499900 AND b<500000;<br>
293
294</blockquote><table border=0 cellpadding=0 cellspacing=0>
295<tr><td>PostgreSQL:</td><td align="right">&nbsp;&nbsp;&nbsp;4.614</td></tr>
296<tr><td>MySQL:</td><td align="right">&nbsp;&nbsp;&nbsp;1.270</td></tr>
297<tr><td>SQLite 2.7.6:</td><td align="right">&nbsp;&nbsp;&nbsp;1.121</td></tr>
298<tr><td>SQLite 2.7.6 (nosync):</td><td align="right">&nbsp;&nbsp;&nbsp;1.162</td></tr>
299</table>
300
301<p>
302All three database engines run faster when they have indices to work with.
303But SQLite is still the fastest.
304</p>
305
306<h3>Test 8: 1000 UPDATEs without an index</h3>
307<blockquote>
308BEGIN;<br>
309UPDATE t1 SET b=b*2 WHERE a>=0 AND a<10;<br>
310UPDATE t1 SET b=b*2 WHERE a>=10 AND a<20;<br>
311<i>... 996 lines omitted</i><br>
312UPDATE t1 SET b=b*2 WHERE a>=9980 AND a<9990;<br>
313UPDATE t1 SET b=b*2 WHERE a>=9990 AND a<10000;<br>
314COMMIT;<br>
315
316</blockquote><table border=0 cellpadding=0 cellspacing=0>
317<tr><td>PostgreSQL:</td><td align="right">&nbsp;&nbsp;&nbsp;1.739</td></tr>
318<tr><td>MySQL:</td><td align="right">&nbsp;&nbsp;&nbsp;8.410</td></tr>
319<tr><td>SQLite 2.7.6:</td><td align="right">&nbsp;&nbsp;&nbsp;0.637</td></tr>
320<tr><td>SQLite 2.7.6 (nosync):</td><td align="right">&nbsp;&nbsp;&nbsp;0.638</td></tr>
321</table>
322
323<p>
324For this particular UPDATE test, MySQL is consistently
325five or ten times
326slower than PostgreSQL and SQLite. I do not know why. MySQL is
327normally a very fast engine. Perhaps this problem has been addressed
328in later versions of MySQL.
329</p>
330
331<h3>Test 9: 25000 UPDATEs with an index</h3>
332<blockquote>
333BEGIN;<br>
334UPDATE t2 SET b=468026 WHERE a=1;<br>
335UPDATE t2 SET b=121928 WHERE a=2;<br>
336<i>... 24996 lines omitted</i><br>
337UPDATE t2 SET b=35065 WHERE a=24999;<br>
338UPDATE t2 SET b=347393 WHERE a=25000;<br>
339COMMIT;<br>
340
341</blockquote><table border=0 cellpadding=0 cellspacing=0>
342<tr><td>PostgreSQL:</td><td align="right">&nbsp;&nbsp;&nbsp;18.797</td></tr>
343<tr><td>MySQL:</td><td align="right">&nbsp;&nbsp;&nbsp;8.134</td></tr>
344<tr><td>SQLite 2.7.6:</td><td align="right">&nbsp;&nbsp;&nbsp;3.520</td></tr>
345<tr><td>SQLite 2.7.6 (nosync):</td><td align="right">&nbsp;&nbsp;&nbsp;3.104</td></tr>
346</table>
347
348<p>
349As recently as version 2.7.0, SQLite ran at about the same speed as
350MySQL on this test. But recent optimizations to SQLite have more
351than doubled speed of UPDATEs.
352</p>
353
354<h3>Test 10: 25000 text UPDATEs with an index</h3>
355<blockquote>
356BEGIN;<br>
357UPDATE t2 SET c='one hundred forty eight thousand three hundred eighty two' WHERE a=1;<br>
358UPDATE t2 SET c='three hundred sixty six thousand five hundred two' WHERE a=2;<br>
359<i>... 24996 lines omitted</i><br>
360UPDATE t2 SET c='three hundred eighty three thousand ninety nine' WHERE a=24999;<br>
361UPDATE t2 SET c='two hundred fifty six thousand eight hundred thirty' WHERE a=25000;<br>
362COMMIT;<br>
363
364</blockquote><table border=0 cellpadding=0 cellspacing=0>
365<tr><td>PostgreSQL:</td><td align="right">&nbsp;&nbsp;&nbsp;48.133</td></tr>
366<tr><td>MySQL:</td><td align="right">&nbsp;&nbsp;&nbsp;6.982</td></tr>
367<tr><td>SQLite 2.7.6:</td><td align="right">&nbsp;&nbsp;&nbsp;2.408</td></tr>
368<tr><td>SQLite 2.7.6 (nosync):</td><td align="right">&nbsp;&nbsp;&nbsp;1.725</td></tr>
369</table>
370
371<p>
372Here again, version 2.7.0 of SQLite used to run at about the same speed
373as MySQL. But now version 2.7.6 is over two times faster than MySQL and
374over twenty times faster than PostgreSQL.
375</p>
376
377<p>
378In fairness to PostgreSQL, it started thrashing on this test. A
379knowledgeable administrator might be able to get PostgreSQL to run a lot
380faster here by tweaking and tuning the server a little.
381</p>
382
383<h3>Test 11: INSERTs from a SELECT</h3>
384<blockquote>
385BEGIN;<br>INSERT INTO t1 SELECT b,a,c FROM t2;<br>INSERT INTO t2 SELECT b,a,c FROM t1;<br>COMMIT;
386</blockquote><table border=0 cellpadding=0 cellspacing=0>
387<tr><td>PostgreSQL:</td><td align="right">&nbsp;&nbsp;&nbsp;61.364</td></tr>
388<tr><td>MySQL:</td><td align="right">&nbsp;&nbsp;&nbsp;1.537</td></tr>
389<tr><td>SQLite 2.7.6:</td><td align="right">&nbsp;&nbsp;&nbsp;2.787</td></tr>
390<tr><td>SQLite 2.7.6 (nosync):</td><td align="right">&nbsp;&nbsp;&nbsp;1.599</td></tr>
391</table>
392
393<p>
394The asynchronous SQLite is just a shade slower than MySQL on this test.
395(MySQL seems to be especially adept at INSERT...SELECT statements.)
396The PostgreSQL engine is still thrashing - most of the 61 seconds it used
397were spent waiting on disk I/O.
398</p>
399
400<h3>Test 12: DELETE without an index</h3>
401<blockquote>
402DELETE FROM t2 WHERE c LIKE '%fifty%';
403</blockquote><table border=0 cellpadding=0 cellspacing=0>
404<tr><td>PostgreSQL:</td><td align="right">&nbsp;&nbsp;&nbsp;1.509</td></tr>
405<tr><td>MySQL:</td><td align="right">&nbsp;&nbsp;&nbsp;0.975</td></tr>
406<tr><td>SQLite 2.7.6:</td><td align="right">&nbsp;&nbsp;&nbsp;4.004</td></tr>
407<tr><td>SQLite 2.7.6 (nosync):</td><td align="right">&nbsp;&nbsp;&nbsp;0.560</td></tr>
408</table>
409
410<p>
411The synchronous version of SQLite is the slowest of the group in this test,
412but the asynchronous version is the fastest.
413The difference is the extra time needed to execute fsync().
414</p>
415
416<h3>Test 13: DELETE with an index</h3>
417<blockquote>
418DELETE FROM t2 WHERE a>10 AND a<20000;
419</blockquote><table border=0 cellpadding=0 cellspacing=0>
420<tr><td>PostgreSQL:</td><td align="right">&nbsp;&nbsp;&nbsp;1.316</td></tr>
421<tr><td>MySQL:</td><td align="right">&nbsp;&nbsp;&nbsp;2.262</td></tr>
422<tr><td>SQLite 2.7.6:</td><td align="right">&nbsp;&nbsp;&nbsp;2.068</td></tr>
423<tr><td>SQLite 2.7.6 (nosync):</td><td align="right">&nbsp;&nbsp;&nbsp;0.752</td></tr>
424</table>
425
426<p>
427This test is significant because it is one of the few where
428PostgreSQL is faster than MySQL. The asynchronous SQLite is,
429however, faster then both the other two.
430</p>
431
432<h3>Test 14: A big INSERT after a big DELETE</h3>
433<blockquote>
434INSERT INTO t2 SELECT * FROM t1;
435</blockquote><table border=0 cellpadding=0 cellspacing=0>
436<tr><td>PostgreSQL:</td><td align="right">&nbsp;&nbsp;&nbsp;13.168</td></tr>
437<tr><td>MySQL:</td><td align="right">&nbsp;&nbsp;&nbsp;1.815</td></tr>
438<tr><td>SQLite 2.7.6:</td><td align="right">&nbsp;&nbsp;&nbsp;3.210</td></tr>
439<tr><td>SQLite 2.7.6 (nosync):</td><td align="right">&nbsp;&nbsp;&nbsp;1.485</td></tr>
440</table>
441
442<p>
443Some older versions of SQLite (prior to version 2.4.0)
444would show decreasing performance after a
445sequence of DELETEs followed by new INSERTs. As this test shows, the
446problem has now been resolved.
447</p>
448
449<h3>Test 15: A big DELETE followed by many small INSERTs</h3>
450<blockquote>
451BEGIN;<br>
452DELETE FROM t1;<br>
453INSERT INTO t1 VALUES(1,10719,'ten thousand seven hundred nineteen');<br>
454<i>... 11997 lines omitted</i><br>
455INSERT INTO t1 VALUES(11999,72836,'seventy two thousand eight hundred thirty six');<br>
456INSERT INTO t1 VALUES(12000,64231,'sixty four thousand two hundred thirty one');<br>
457COMMIT;<br>
458
459</blockquote><table border=0 cellpadding=0 cellspacing=0>
460<tr><td>PostgreSQL:</td><td align="right">&nbsp;&nbsp;&nbsp;4.556</td></tr>
461<tr><td>MySQL:</td><td align="right">&nbsp;&nbsp;&nbsp;1.704</td></tr>
462<tr><td>SQLite 2.7.6:</td><td align="right">&nbsp;&nbsp;&nbsp;0.618</td></tr>
463<tr><td>SQLite 2.7.6 (nosync):</td><td align="right">&nbsp;&nbsp;&nbsp;0.406</td></tr>
464</table>
465
466<p>
467SQLite is very good at doing INSERTs within a transaction, which probably
468explains why it is so much faster than the other databases at this test.
469</p>
470
471<h3>Test 16: DROP TABLE</h3>
472<blockquote>
473DROP TABLE t1;<br>DROP TABLE t2;<br>DROP TABLE t3;
474</blockquote><table border=0 cellpadding=0 cellspacing=0>
475<tr><td>PostgreSQL:</td><td align="right">&nbsp;&nbsp;&nbsp;0.135</td></tr>
476<tr><td>MySQL:</td><td align="right">&nbsp;&nbsp;&nbsp;0.015</td></tr>
477<tr><td>SQLite 2.7.6:</td><td align="right">&nbsp;&nbsp;&nbsp;0.939</td></tr>
478<tr><td>SQLite 2.7.6 (nosync):</td><td align="right">&nbsp;&nbsp;&nbsp;0.254</td></tr>
479</table>
480
481<p>
482SQLite is slower than the other databases when it comes to dropping tables.
483This probably is because when SQLite drops a table, it has to go through and
484erase the records in the database file that deal with that table. MySQL and
485PostgreSQL, on the other hand, use separate files to represent each table
486so they can drop a table simply by deleting a file, which is much faster.
487</p>
488
489<p>
490On the other hand, dropping tables is not a very common operation
491so if SQLite takes a little longer, that is not seen as a big problem.
492</p>
493
494}
495footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/sqlite.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/sqlite.tcl
deleted file mode 100644
index eed1cd7..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/sqlite.tcl
+++ /dev/null
@@ -1,582 +0,0 @@
1#
2# Run this Tcl script to generate the sqlite.html file.
3#
4set rcsid {$Id: sqlite.tcl,v 1.25 2007/01/08 14:31:36 drh Exp $}
5source common.tcl
6header {sqlite3: A command-line access program for SQLite databases}
7puts {
8<h2>sqlite3: A command-line access program for SQLite databases</h2>
9
10<p>The SQLite library includes a simple command-line utility named
11<b>sqlite3</b> that allows the user to manually enter and execute SQL
12commands against an SQLite database. This document provides a brief
13introduction on how to use <b>sqlite3</b>.
14
15<h3>Getting Started</h3>
16
17<p>To start the <b>sqlite3</b> program, just type "sqlite3" followed by
18the name the file that holds the SQLite database. If the file does
19not exist, a new one is created automatically.
20The <b>sqlite3</b> program will
21then prompt you to enter SQL. Type in SQL statements (terminated by a
22semicolon), press "Enter" and the SQL will be executed.</p>
23
24<p>For example, to create a new SQLite database named "ex1"
25with a single table named "tbl1", you might do this:</p>
26}
27
28proc Code {body} {
29 puts {<blockquote><tt>}
30 regsub -all {&} [string trim $body] {\&amp;} body
31 regsub -all {>} $body {\&gt;} body
32 regsub -all {<} $body {\&lt;} body
33 regsub -all {\(\(\(} $body {<b>} body
34 regsub -all {\)\)\)} $body {</b>} body
35 regsub -all { } $body {\&nbsp;} body
36 regsub -all \n $body <br>\n body
37 puts $body
38 puts {</tt></blockquote>}
39}
40
41Code {
42$ (((sqlite3 ex1)))
43SQLite version 3.3.10
44Enter ".help" for instructions
45sqlite> (((create table tbl1(one varchar(10), two smallint);)))
46sqlite> (((insert into tbl1 values('hello!',10);)))
47sqlite> (((insert into tbl1 values('goodbye', 20);)))
48sqlite> (((select * from tbl1;)))
49hello!|10
50goodbye|20
51sqlite>
52}
53
54puts {
55<p>You can terminate the sqlite3 program by typing your systems
56End-Of-File character (usually a Control-D) or the interrupt
57character (usually a Control-C).</p>
58
59<p>Make sure you type a semicolon at the end of each SQL command!
60The sqlite3 program looks for a semicolon to know when your SQL command is
61complete. If you omit the semicolon, sqlite3 will give you a
62continuation prompt and wait for you to enter more text to be
63added to the current SQL command. This feature allows you to
64enter SQL commands that span multiple lines. For example:</p>
65}
66
67Code {
68sqlite> (((CREATE TABLE tbl2 ()))
69 ...> ((( f1 varchar(30) primary key,)))
70 ...> ((( f2 text,)))
71 ...> ((( f3 real)))
72 ...> ((();)))
73sqlite>
74}
75
76puts {
77
78<h3>Aside: Querying the SQLITE_MASTER table</h3>
79
80<p>The database schema in an SQLite database is stored in
81a special table named "sqlite_master".
82You can execute "SELECT" statements against the
83special sqlite_master table just like any other table
84in an SQLite database. For example:</p>
85}
86
87Code {
88$ (((sqlite3 ex1)))
89SQlite vresion 3.3.10
90Enter ".help" for instructions
91sqlite> (((select * from sqlite_master;)))
92 type = table
93 name = tbl1
94tbl_name = tbl1
95rootpage = 3
96 sql = create table tbl1(one varchar(10), two smallint)
97sqlite>
98}
99
100puts {
101<p>
102But you cannot execute DROP TABLE, UPDATE, INSERT or DELETE against
103the sqlite_master table. The sqlite_master
104table is updated automatically as you create or drop tables and
105indices from the database. You can not make manual changes
106to the sqlite_master table.
107</p>
108
109<p>
110The schema for TEMPORARY tables is not stored in the "sqlite_master" table
111since TEMPORARY tables are not visible to applications other than the
112application that created the table. The schema for TEMPORARY tables
113is stored in another special table named "sqlite_temp_master". The
114"sqlite_temp_master" table is temporary itself.
115</p>
116
117<h3>Special commands to sqlite3</h3>
118
119<p>
120Most of the time, sqlite3 just reads lines of input and passes them
121on to the SQLite library for execution.
122But if an input line begins with a dot ("."), then
123that line is intercepted and interpreted by the sqlite3 program itself.
124These "dot commands" are typically used to change the output format
125of queries, or to execute certain prepackaged query statements.
126</p>
127
128<p>
129For a listing of the available dot commands, you can enter ".help"
130at any time. For example:
131</p>}
132
133Code {
134sqlite> (((.help)))
135.bail ON|OFF Stop after hitting an error. Default OFF
136.databases List names and files of attached databases
137.dump ?TABLE? ... Dump the database in an SQL text format
138.echo ON|OFF Turn command echo on or off
139.exit Exit this program
140.explain ON|OFF Turn output mode suitable for EXPLAIN on or off.
141.header(s) ON|OFF Turn display of headers on or off
142.help Show this message
143.import FILE TABLE Import data from FILE into TABLE
144.indices TABLE Show names of all indices on TABLE
145.load FILE ?ENTRY? Load an extension library
146.mode MODE ?TABLE? Set output mode where MODE is one of:
147 csv Comma-separated values
148 column Left-aligned columns. (See .width)
149 html HTML <table> code
150 insert SQL insert statements for TABLE
151 line One value per line
152 list Values delimited by .separator string
153 tabs Tab-separated values
154 tcl TCL list elements
155.nullvalue STRING Print STRING in place of NULL values
156.output FILENAME Send output to FILENAME
157.output stdout Send output to the screen
158.prompt MAIN CONTINUE Replace the standard prompts
159.quit Exit this program
160.read FILENAME Execute SQL in FILENAME
161.schema ?TABLE? Show the CREATE statements
162.separator STRING Change separator used by output mode and .import
163.show Show the current values for various settings
164.tables ?PATTERN? List names of tables matching a LIKE pattern
165.timeout MS Try opening locked tables for MS milliseconds
166.width NUM NUM ... Set column widths for "column" mode
167sqlite>
168}
169
170puts {
171<h3>Changing Output Formats</h3>
172
173<p>The sqlite3 program is able to show the results of a query
174in eight different formats: "csv", "column", "html", "insert",
175"line", "tabs", and "tcl".
176You can use the ".mode" dot command to switch between these output
177formats.</p>
178
179<p>The default output mode is "list". In
180list mode, each record of a query result is written on one line of
181output and each column within that record is separated by a specific
182separator string. The default separator is a pipe symbol ("|").
183List mode is especially useful when you are going to send the output
184of a query to another program (such as AWK) for additional processing.</p>}
185
186Code {
187sqlite> (((.mode list)))
188sqlite> (((select * from tbl1;)))
189hello|10
190goodbye|20
191sqlite>
192}
193
194puts {
195<p>You can use the ".separator" dot command to change the separator
196for list mode. For example, to change the separator to a comma and
197a space, you could do this:</p>}
198
199Code {
200sqlite> (((.separator ", ")))
201sqlite> (((select * from tbl1;)))
202hello, 10
203goodbye, 20
204sqlite>
205}
206
207puts {
208<p>In "line" mode, each column in a row of the database
209is shown on a line by itself. Each line consists of the column
210name, an equal sign and the column data. Successive records are
211separated by a blank line. Here is an example of line mode
212output:</p>}
213
214Code {
215sqlite> (((.mode line)))
216sqlite> (((select * from tbl1;)))
217one = hello
218two = 10
219
220one = goodbye
221two = 20
222sqlite>
223}
224
225puts {
226<p>In column mode, each record is shown on a separate line with the
227data aligned in columns. For example:</p>}
228
229Code {
230sqlite> (((.mode column)))
231sqlite> (((select * from tbl1;)))
232one two
233---------- ----------
234hello 10
235goodbye 20
236sqlite>
237}
238
239puts {
240<p>By default, each column is at least 10 characters wide.
241Data that is too wide to fit in a column is truncated. You can
242adjust the column widths using the ".width" command. Like this:</p>}
243
244Code {
245sqlite> (((.width 12 6)))
246sqlite> (((select * from tbl1;)))
247one two
248------------ ------
249hello 10
250goodbye 20
251sqlite>
252}
253
254puts {
255<p>The ".width" command in the example above sets the width of the first
256column to 12 and the width of the second column to 6. All other column
257widths were unaltered. You can gives as many arguments to ".width" as
258necessary to specify the widths of as many columns as are in your
259query results.</p>
260
261<p>If you specify a column a width of 0, then the column
262width is automatically adjusted to be the maximum of three
263numbers: 10, the width of the header, and the width of the
264first row of data. This makes the column width self-adjusting.
265The default width setting for every column is this
266auto-adjusting 0 value.</p>
267
268<p>The column labels that appear on the first two lines of output
269can be turned on and off using the ".header" dot command. In the
270examples above, the column labels are on. To turn them off you
271could do this:</p>}
272
273Code {
274sqlite> (((.header off)))
275sqlite> (((select * from tbl1;)))
276hello 10
277goodbye 20
278sqlite>
279}
280
281puts {
282<p>Another useful output mode is "insert". In insert mode, the output
283is formatted to look like SQL INSERT statements. You can use insert
284mode to generate text that can later be used to input data into a
285different database.</p>
286
287<p>When specifying insert mode, you have to give an extra argument
288which is the name of the table to be inserted into. For example:</p>
289}
290
291Code {
292sqlite> (((.mode insert new_table)))
293sqlite> (((select * from tbl1;)))
294INSERT INTO 'new_table' VALUES('hello',10);
295INSERT INTO 'new_table' VALUES('goodbye',20);
296sqlite>
297}
298
299puts {
300<p>The last output mode is "html". In this mode, sqlite3 writes
301the results of the query as an XHTML table. The beginning
302&lt;TABLE&gt; and the ending &lt;/TABLE&gt; are not written, but
303all of the intervening &lt;TR&gt;s, &lt;TH&gt;s, and &lt;TD&gt;s
304are. The html output mode is envisioned as being useful for
305CGI.</p>
306}
307
308puts {
309<h3>Writing results to a file</h3>
310
311<p>By default, sqlite3 sends query results to standard output. You
312can change this using the ".output" command. Just put the name of
313an output file as an argument to the .output command and all subsequent
314query results will be written to that file. Use ".output stdout" to
315begin writing to standard output again. For example:</p>}
316
317Code {
318sqlite> (((.mode list)))
319sqlite> (((.separator |)))
320sqlite> (((.output test_file_1.txt)))
321sqlite> (((select * from tbl1;)))
322sqlite> (((.exit)))
323$ (((cat test_file_1.txt)))
324hello|10
325goodbye|20
326$
327}
328
329puts {
330<h3>Querying the database schema</h3>
331
332<p>The sqlite3 program provides several convenience commands that
333are useful for looking at the schema of the database. There is
334nothing that these commands do that cannot be done by some other
335means. These commands are provided purely as a shortcut.</p>
336
337<p>For example, to see a list of the tables in the database, you
338can enter ".tables".</p>
339}
340
341Code {
342sqlite> (((.tables)))
343tbl1
344tbl2
345sqlite>
346}
347
348puts {
349<p>The ".tables" command is similar to setting list mode then
350executing the following query:</p>
351
352<blockquote><pre>
353SELECT name FROM sqlite_master
354WHERE type IN ('table','view') AND name NOT LIKE 'sqlite_%'
355UNION ALL
356SELECT name FROM sqlite_temp_master
357WHERE type IN ('table','view')
358ORDER BY 1
359</pre></blockquote>
360
361<p>In fact, if you look at the source code to the sqlite3 program
362(found in the source tree in the file src/shell.c) you'll find
363exactly the above query.</p>
364
365<p>The ".indices" command works in a similar way to list all of
366the indices for a particular table. The ".indices" command takes
367a single argument which is the name of the table for which the
368indices are desired. Last, but not least, is the ".schema" command.
369With no arguments, the ".schema" command shows the original CREATE TABLE
370and CREATE INDEX statements that were used to build the current database.
371If you give the name of a table to ".schema", it shows the original
372CREATE statement used to make that table and all if its indices.
373We have:</p>}
374
375Code {
376sqlite> (((.schema)))
377create table tbl1(one varchar(10), two smallint)
378CREATE TABLE tbl2 (
379 f1 varchar(30) primary key,
380 f2 text,
381 f3 real
382)
383sqlite> (((.schema tbl2)))
384CREATE TABLE tbl2 (
385 f1 varchar(30) primary key,
386 f2 text,
387 f3 real
388)
389sqlite>
390}
391
392puts {
393<p>The ".schema" command accomplishes the same thing as setting
394list mode, then entering the following query:</p>
395
396<blockquote><pre>
397SELECT sql FROM
398 (SELECT * FROM sqlite_master UNION ALL
399 SELECT * FROM sqlite_temp_master)
400WHERE type!='meta'
401ORDER BY tbl_name, type DESC, name
402</pre></blockquote>
403
404<p>Or, if you give an argument to ".schema" because you only
405want the schema for a single table, the query looks like this:</p>
406
407<blockquote><pre>
408SELECT sql FROM
409 (SELECT * FROM sqlite_master UNION ALL
410 SELECT * FROM sqlite_temp_master)
411WHERE type!='meta' AND sql NOT NULL AND name NOT LIKE 'sqlite_%'
412ORDER BY substr(type,2,1), name
413</pre></blockquote>
414
415<p>
416You can supply an argument to the .schema command. If you do, the
417query looks like this:
418</p>
419
420<blockquote><pre>
421SELECT sql FROM
422 (SELECT * FROM sqlite_master UNION ALL
423 SELECT * FROM sqlite_temp_master)
424WHERE tbl_name LIKE '%s'
425 AND type!='meta' AND sql NOT NULL AND name NOT LIKE 'sqlite_%'
426ORDER BY substr(type,2,1), name
427</pre></blockquote>
428
429<p>The "%s" in the query is replace by your argument. This allows you
430to view the schema for some subset of the database.</p>
431}
432
433Code {
434sqlite> (((.schema %abc%)))
435}
436
437puts {
438<p>
439Along these same lines,
440the ".table" command also accepts a pattern as its first argument.
441If you give an argument to the .table command, a "%" is both
442appended and prepended and a LIKE clause is added to the query.
443This allows you to list only those tables that match a particular
444pattern.</p>
445
446<p>The ".databases" command shows a list of all databases open in
447the current connection. There will always be at least 2. The first
448one is "main", the original database opened. The second is "temp",
449the database used for temporary tables. There may be additional
450databases listed for databases attached using the ATTACH statement.
451The first output column is the name the database is attached with,
452and the second column is the filename of the external file.</p>}
453
454Code {
455sqlite> (((.databases)))
456}
457
458puts {
459<h3>Converting An Entire Database To An ASCII Text File</h3>
460
461<p>Use the ".dump" command to convert the entire contents of a
462database into a single ASCII text file. This file can be converted
463back into a database by piping it back into <b>sqlite3</b>.</p>
464
465<p>A good way to make an archival copy of a database is this:</p>
466}
467
468Code {
469$ (((echo '.dump' | sqlite3 ex1 | gzip -c >ex1.dump.gz)))
470}
471
472puts {
473<p>This generates a file named <b>ex1.dump.gz</b> that contains everything
474you need to reconstruct the database at a later time, or on another
475machine. To reconstruct the database, just type:</p>
476}
477
478Code {
479$ (((zcat ex1.dump.gz | sqlite3 ex2)))
480}
481
482puts {
483<p>The text format is pure SQL so you
484can also use the .dump command to export an SQLite database
485into other popular SQL database engines. Like this:</p>
486}
487
488Code {
489$ (((createdb ex2)))
490$ (((sqlite3 ex1 .dump | psql ex2)))
491}
492
493puts {
494<h3>Other Dot Commands</h3>
495
496<p>The ".explain" dot command can be used to set the output mode
497to "column" and to set the column widths to values that are reasonable
498for looking at the output of an EXPLAIN command. The EXPLAIN command
499is an SQLite-specific SQL extension that is useful for debugging. If any
500regular SQL is prefaced by EXPLAIN, then the SQL command is parsed and
501analyzed but is not executed. Instead, the sequence of virtual machine
502instructions that would have been used to execute the SQL command are
503returned like a query result. For example:</p>}
504
505Code {
506sqlite> (((.explain)))
507sqlite> (((explain delete from tbl1 where two<20;)))
508addr opcode p1 p2 p3
509---- ------------ ----- ----- -------------------------------------
5100 ListOpen 0 0
5111 Open 0 1 tbl1
5122 Next 0 9
5133 Field 0 1
5144 Integer 20 0
5155 Ge 0 2
5166 Key 0 0
5177 ListWrite 0 0
5188 Goto 0 2
5199 Noop 0 0
52010 ListRewind 0 0
52111 ListRead 0 14
52212 Delete 0 0
52313 Goto 0 11
52414 ListClose 0 0
525}
526
527puts {
528
529<p>The ".timeout" command sets the amount of time that the <b>sqlite3</b>
530program will wait for locks to clear on files it is trying to access
531before returning an error. The default value of the timeout is zero so
532that an error is returned immediately if any needed database table or
533index is locked.</p>
534
535<p>And finally, we mention the ".exit" command which causes the
536sqlite3 program to exit.</p>
537
538<h3>Using sqlite3 in a shell script</h3>
539
540<p>
541One way to use sqlite3 in a shell script is to use "echo" or
542"cat" to generate a sequence of commands in a file, then invoke sqlite3
543while redirecting input from the generated command file. This
544works fine and is appropriate in many circumstances. But as
545an added convenience, sqlite3 allows a single SQL command to be
546entered on the command line as a second argument after the
547database name. When the sqlite3 program is launched with two
548arguments, the second argument is passed to the SQLite library
549for processing, the query results are printed on standard output
550in list mode, and the program exits. This mechanism is designed
551to make sqlite3 easy to use in conjunction with programs like
552"awk". For example:</p>}
553
554Code {
555$ (((sqlite3 ex1 'select * from tbl1' |)))
556> ((( awk '{printf "<tr><td>%s<td>%s\n",$1,$2 }')))
557<tr><td>hello<td>10
558<tr><td>goodbye<td>20
559$
560}
561
562puts {
563<h3>Ending shell commands</h3>
564
565<p>
566SQLite commands are normally terminated by a semicolon. In the shell
567you can also use the word "GO" (case-insensitive) or a slash character
568"/" on a line by itself to end a command. These are used by SQL Server
569and Oracle, respectively. These won't work in <b>sqlite3_exec()</b>,
570because the shell translates these into a semicolon before passing them
571to that function.</p>
572}
573
574puts {
575<h3>Compiling the sqlite3 program from sources</h3>
576
577<p>
578The sqlite3 program is built automatically when you compile the
579SQLite library. Just get a copy of the source tree, run
580"configure" and then "make".</p>
581}
582footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/support.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/support.tcl
deleted file mode 100644
index 6dc4693..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/support.tcl
+++ /dev/null
@@ -1,79 +0,0 @@
1set rcsid {$Id: support.tcl,v 1.7 2007/06/21 13:30:40 drh Exp $}
2source common.tcl
3header {SQLite Support Options}
4puts {
5<h2>SQLite Support Options</h2>
6
7
8<h3>Mailing List</h3>
9<p>
10A mailing list has been set up for asking questions and
11for open discussion of problems
12and issues by the SQLite user community.
13To subscribe to the mailing list, send an email to
14<a href="mailto:sqlite-users-subscribe@sqlite.org">
15sqlite-users-subscribe@sqlite.org</a>.
16If you would prefer to get digests rather than individual
17emails, send a message to to
18<a href="mailto:sqlite-users-digest-subscribe@sqlite.org">
19sqlite-users-digest-subscribe@sqlite.org</a>.
20For additional information about operating and using this
21mailing list, send a message to
22<a href="mailto:sqlite-users-help@sqlite.org">
23sqlite-users-help@sqlite.org</a> and instructions will be
24sent by to you by return email.
25</p>
26
27<p>
28There are multiple archives of the mailing list:
29</p>
30
31<blockquote>
32<a href="http://www.mail-archive.com/sqlite-users%40sqlite.org/">
33http://www.mail-archive.com/sqlite-users%40sqlite.org</a><br>
34<a href="http://marc.info/?l=sqlite-users&r=1&w=2">
35http://marc.info/?l=sqlite-users&r=1&w=2</a><br>
36<a href="http://news.gmane.org/gmane.comp.db.sqlite.general">
37http://news.gmane.org/gmane.comp.db.sqlite.general</a>
38</blockquote>
39
40</p>
41
42<a name="directemail">
43<h3>Direct E-Mail To The Author</h3>
44
45<p>
46Use the mailing list.
47Please do <b>not</b> send email directly to the author of SQLite
48unless:
49<ul>
50<li>You have or intend to acquire a professional support contract
51as described below, or</li>
52<li>You are working on an open source project.</li>
53</ul>
54You are welcomed to use SQLite in closed source, proprietary, and/or
55commerical projects and to ask questions about such use on the public
56mailing list. But please do not ask to receive free direct technical
57support. The software is free; direct technical support is not.
58</p>
59
60
61<h3>Professional Support</h3>
62
63<p>
64If you would like professional support for SQLite
65or if you want custom modifications to SQLite performed by the
66original author, these services are available for a modest fee.
67For additional information visit
68<a href="http://www.hwaci.com/sw/sqlite/prosupport.html">
69http://www.hwaci.com/sw/sqlite/prosupport.html</a> or contact:</p>
70
71<blockquote>
72D. Richard Hipp <br />
73Hwaci - Applied Software Research <br />
74704.948.4565 <br />
75<a href="mailto:drh@hwaci.com">drh@hwaci.com</a>
76</blockquote>
77
78}
79footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/table-ex1b2.gif b/libraries/sqlite/unix/sqlite-3.5.1/www/table-ex1b2.gif
deleted file mode 100644
index 5f68e0a..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/table-ex1b2.gif
+++ /dev/null
Binary files differ
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/tclsqlite.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/tclsqlite.tcl
deleted file mode 100644
index 141cb5e..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/tclsqlite.tcl
+++ /dev/null
@@ -1,666 +0,0 @@
1#
2# Run this Tcl script to generate the tclsqlite.html file.
3#
4set rcsid {$Id: tclsqlite.tcl,v 1.17 2007/06/19 17:48:57 drh Exp $}
5source common.tcl
6header {The Tcl interface to the SQLite library}
7proc METHOD {name text} {
8 puts "<a name=\"$name\">\n<h3>The \"$name\" method</h3>\n"
9 puts $text
10}
11puts {
12<h2>The Tcl interface to the SQLite library</h2>
13
14<p>The SQLite library is designed to be very easy to use from
15a Tcl or Tcl/Tk script. This document gives an overview of the Tcl
16programming interface.</p>
17
18<h3>The API</h3>
19
20<p>The interface to the SQLite library consists of single
21tcl command named <b>sqlite3</b>
22Because there is only this
23one command, the interface is not placed in a separate
24namespace.</p>
25
26<p>The <b>sqlite3</b> command is used as follows:</p>
27
28<blockquote>
29<b>sqlite3</b>&nbsp;&nbsp;<i>dbcmd&nbsp;&nbsp;database-name</i>
30</blockquote>
31
32<p>
33The <b>sqlite3</b> command opens the database named in the second
34argument. If the database does not already exist, it is
35automatically created.
36The <b>sqlite3</b> command also creates a new Tcl
37command to control the database. The name of the new Tcl command
38is given by the first argument. This approach is similar to the
39way widgets are created in Tk.
40</p>
41
42<p>
43The name of the database is just the name of a disk file in which
44the database is stored. If the name of the database is an empty
45string or the special name ":memory:" then a new database is created
46in memory.
47</p>
48
49<p>
50Once an SQLite database is open, it can be controlled using
51methods of the <i>dbcmd</i>. There are currently 22 methods
52defined.</p>
53
54<p>
55<ul>
56}
57foreach m [lsort {
58 authorizer
59 busy
60 cache
61 changes
62 close
63 collate
64 collation_needed
65 commit_hook
66 complete
67 copy
68 enable_load_extension
69 errorcode
70 eval
71 exists
72 function
73 last_insert_rowid
74 nullvalue
75 onecolumn
76 profile
77 progress
78 rollback_hook
79 timeout
80 total_changes
81 trace
82 transaction
83 update_hook
84 version
85}] {
86 puts "<li><a href=\"#$m\">$m</a></li>"
87}
88puts {
89</ul>
90</p>
91
92<p>The use of each of these methods will be explained in the sequel, though
93not in the order shown above.</p>
94
95}
96
97##############################################################################
98METHOD eval {
99<p>
100The most useful <i>dbcmd</i> method is "eval". The eval method is used
101to execute SQL on the database. The syntax of the eval method looks
102like this:</p>
103
104<blockquote>
105<i>dbcmd</i>&nbsp;&nbsp;<b>eval</b>&nbsp;&nbsp;<i>sql</i>
106&nbsp;&nbsp;&nbsp;&nbsp;?<i>array-name&nbsp;</i>?&nbsp;?<i>script</i>?
107</blockquote>
108
109<p>
110The job of the eval method is to execute the SQL statement or statements
111given in the second argument. For example, to create a new table in
112a database, you can do this:</p>
113
114<blockquote>
115<b>sqlite3 db1 ./testdb<br>
116db1 eval {CREATE TABLE t1(a int, b text)}</b>
117</blockquote>
118
119<p>The above code creates a new table named <b>t1</b> with columns
120<b>a</b> and <b>b</b>. What could be simpler?</p>
121
122<p>Query results are returned as a list of column values. If a
123query requests 2 columns and there are 3 rows matching the query,
124then the returned list will contain 6 elements. For example:</p>
125
126<blockquote>
127<b>db1 eval {INSERT INTO t1 VALUES(1,'hello')}<br>
128db1 eval {INSERT INTO t1 VALUES(2,'goodbye')}<br>
129db1 eval {INSERT INTO t1 VALUES(3,'howdy!')}<br>
130set x [db1 eval {SELECT * FROM t1 ORDER BY a}]</b>
131</blockquote>
132
133<p>The variable <b>$x</b> is set by the above code to</p>
134
135<blockquote>
136<b>1 hello 2 goodbye 3 howdy!</b>
137</blockquote>
138
139<p>You can also process the results of a query one row at a time
140by specifying the name of an array variable and a script following
141the SQL code. For each row of the query result, the values of all
142columns will be inserted into the array variable and the script will
143be executed. For instance:</p>
144
145<blockquote>
146<b>db1 eval {SELECT * FROM t1 ORDER BY a} values {<br>
147&nbsp;&nbsp;&nbsp;&nbsp;parray values<br>
148&nbsp;&nbsp;&nbsp;&nbsp;puts ""<br>
149}</b>
150</blockquote>
151
152<p>This last code will give the following output:</p>
153
154<blockquote><b>
155values(*) = a b<br>
156values(a) = 1<br>
157values(b) = hello<p>
158
159values(*) = a b<br>
160values(a) = 2<br>
161values(b) = goodbye<p>
162
163values(*) = a b<br>
164values(a) = 3<br>
165values(b) = howdy!</b>
166</blockquote>
167
168<p>
169For each column in a row of the result, the name of that column
170is used as an index in to array. The value of the column is stored
171in the corresponding array entry. The special array index * is
172used to store a list of column names in the order that they appear.
173</p>
174
175<p>
176If the array variable name is omitted or is the empty string, then the value of
177each column is stored in a variable with the same name as the column
178itself. For example:
179</p>
180
181<blockquote>
182<b>db1 eval {SELECT * FROM t1 ORDER BY a} {<br>
183&nbsp;&nbsp;&nbsp;&nbsp;puts "a=$a b=$b"<br>
184}</b>
185</blockquote>
186
187<p>
188From this we get the following output
189</p>
190
191<blockquote><b>
192a=1 b=hello<br>
193a=2 b=goodbye<br>
194a=3 b=howdy!</b>
195</blockquote>
196
197<p>
198Tcl variable names can appear in the SQL statement of the second argument
199in any position where it is legal to put a string or number literal. The
200value of the variable is substituted for the variable name. If the
201variable does not exist a NULL values is used. For example:
202</p>
203
204<blockquote><b>
205db1 eval {INSERT INTO t1 VALUES(5,$bigstring)}
206</b></blockquote>
207
208<p>
209Note that it is not necessary to quote the $bigstring value. That happens
210automatically. If $bigstring is a large string or binary object, this
211technique is not only easier to write, it is also much more efficient
212since it avoids making a copy of the content of $bigstring.
213</p>
214
215<p>
216If the $bigstring variable has both a string and a "bytearray" representation,
217then TCL inserts the value as a string. If it has only a "bytearray"
218representation, then the value is inserted as a BLOB. To force a
219value to be inserted as a BLOB even if it also has a text representation,
220us a "@" character to in place of the "$". Like this:
221</p>
222
223<blockquote><b>
224db1 eval {INSERT INTO t1 VALUES(5,@bigstring)}
225</b></blockquote>
226
227<p>
228If the variable does not have a bytearray representation, then "@" works
229just like "$".
230</p>
231
232}
233
234##############################################################################
235METHOD close {
236
237<p>
238As its name suggests, the "close" method to an SQLite database just
239closes the database. This has the side-effect of deleting the
240<i>dbcmd</i> Tcl command. Here is an example of opening and then
241immediately closing a database:
242</p>
243
244<blockquote>
245<b>sqlite3 db1 ./testdb<br>
246db1 close</b>
247</blockquote>
248
249<p>
250If you delete the <i>dbcmd</i> directly, that has the same effect
251as invoking the "close" method. So the following code is equivalent
252to the previous:</p>
253
254<blockquote>
255<b>sqlite3 db1 ./testdb<br>
256rename db1 {}</b>
257</blockquote>
258}
259
260##############################################################################
261METHOD transaction {
262
263<p>
264The "transaction" method is used to execute a TCL script inside an SQLite
265database transaction. The transaction is committed when the script completes,
266or it rolls back if the script fails. If the transaction occurs within
267another transaction (even one that is started manually using BEGIN) it
268is a no-op.
269</p>
270
271<p>
272The transaction command can be used to group together several SQLite
273commands in a safe way. You can always start transactions manually using
274BEGIN, of
275course. But if an error occurs so that the COMMIT or ROLLBACK are never
276run, then the database will remain locked indefinitely. Also, BEGIN
277does not nest, so you have to make sure no other transactions are active
278before starting a new one. The "transaction" method takes care of
279all of these details automatically.
280</p>
281
282<p>
283The syntax looks like this:
284</p>
285
286<blockquote>
287<i>dbcmd</i>&nbsp;&nbsp;<b>transaction</b>&nbsp;&nbsp;<i>?transaction-type?</i>
288&nbsp;&nbsp;<i>SCRIPT,</i>
289</blockquote>
290
291
292<p>
293The <i>transaction-type</i> can be one of <b>deferred</b>,
294<b>exclusive</b> or <b>immediate</b>. The default is deferred.
295</p>
296}
297
298##############################################################################
299METHOD cache {
300
301<p>
302The "eval" method described <a href="#eval">above</a> keeps a cache of
303<a href="capi3ref.html#sqlite3_prepare">prepared statements</a>
304for recently evaluated SQL commands.
305The "cache" method is used to control this cache.
306The first form of this command is:</p>
307
308<blockquote>
309<i>dbcmd</i>&nbsp;&nbsp;<b>cache size</b>&nbsp;&nbsp;<i>N</i>
310</blockquote>
311
312<p>This sets the maximum number of statements that can be cached.
313The upper limit is 100. The default is 10. If you set the cache size
314to 0, no caching is done.</p>
315
316<p>The second form of the command is this:</p>
317
318
319<blockquote>
320<i>dbcmd</i>&nbsp;&nbsp;<b>cache flush</b>
321</blockquote>
322
323<p>The cache-flush method
324<a href="capi3ref.html#sqlite3_finalize">finalizes</a>
325all prepared statements currently
326in the cache.</p>
327
328}
329
330##############################################################################
331METHOD complete {
332
333<p>
334The "complete" method takes a string of supposed SQL as its only argument.
335It returns TRUE if the string is a complete statement of SQL and FALSE if
336there is more to be entered.</p>
337
338<p>The "complete" method is useful when building interactive applications
339in order to know when the user has finished entering a line of SQL code.
340This is really just an interface to the
341<a href="capi3ref.html#sqlite3_complete"><b>sqlite3_complete()</b></a> C
342function.
343}
344
345##############################################################################
346METHOD copy {
347
348<p>
349The "copy" method copies data from a file into a table.
350It returns the number of rows processed successfully from the file.
351The syntax of the copy method looks like this:</p>
352
353<blockquote>
354<i>dbcmd</i>&nbsp;&nbsp;<b>copy</b>&nbsp;&nbsp;<i>conflict-algorithm</i>
355&nbsp;&nbsp;<i>table-name&nbsp;</i>&nbsp;&nbsp;<i>file-name&nbsp;</i>
356&nbsp;&nbsp;&nbsp;&nbsp;?<i>column-separator&nbsp;</i>?
357&nbsp;&nbsp;?<i>null-indicator</i>?
358</blockquote>
359
360<p>Conflict-alogrithm must be one of the SQLite conflict algorithms for
361the INSERT statement: <i>rollback</i>, <i>abort</i>,
362<i>fail</i>,<i>ignore</i>, or <i>replace</i>. See the SQLite Language
363section for <a href="lang.html#conflict">ON CONFLICT</a> for more information.
364The conflict-algorithm must be specified in lower case.
365</p>
366
367<p>Table-name must already exists as a table. File-name must exist, and
368each row must contain the same number of columns as defined in the table.
369If a line in the file contains more or less than the number of columns defined,
370the copy method rollbacks any inserts, and returns an error.</p>
371
372<p>Column-separator is an optional column separator string. The default is
373the ASCII tab character \t. </p>
374
375<p>Null-indicator is an optional string that indicates a column value is null.
376The default is an empty string. Note that column-separator and
377null-indicator are optional positional arguments; if null-indicator
378is specified, a column-separator argument must be specifed and
379precede the null-indicator argument.</p>
380
381<p>The copy method implements similar functionality to the <b>.import</b>
382SQLite shell command.
383The SQLite 2.x <a href="lang.html#copy"><b>COPY</b></a> statement
384(using the PostgreSQL COPY file format)
385can be implemented with this method as:</p>
386
387<blockquote>
388dbcmd&nbsp;&nbsp;copy&nbsp;&nbsp;$conflictalgo
389&nbsp;&nbsp;$tablename&nbsp;&nbsp;&nbsp;$filename&nbsp;
390&nbsp;&nbsp;&nbsp;&nbsp;\t&nbsp;
391&nbsp;&nbsp;\\N
392</blockquote>
393
394}
395
396##############################################################################
397METHOD timeout {
398
399<p>The "timeout" method is used to control how long the SQLite library
400will wait for locks to clear before giving up on a database transaction.
401The default timeout is 0 millisecond. (In other words, the default behavior
402is not to wait at all.)</p>
403
404<p>The SQLite database allows multiple simultaneous
405readers or a single writer but not both. If any process is writing to
406the database no other process is allows to read or write. If any process
407is reading the database other processes are allowed to read but not write.
408The entire database shared a single lock.</p>
409
410<p>When SQLite tries to open a database and finds that it is locked, it
411can optionally delay for a short while and try to open the file again.
412This process repeats until the query times out and SQLite returns a
413failure. The timeout is adjustable. It is set to 0 by default so that
414if the database is locked, the SQL statement fails immediately. But you
415can use the "timeout" method to change the timeout value to a positive
416number. For example:</p>
417
418<blockquote><b>db1 timeout 2000</b></blockquote>
419
420<p>The argument to the timeout method is the maximum number of milliseconds
421to wait for the lock to clear. So in the example above, the maximum delay
422would be 2 seconds.</p>
423}
424
425##############################################################################
426METHOD busy {
427
428<p>The "busy" method, like "timeout", only comes into play when the
429database is locked. But the "busy" method gives the programmer much more
430control over what action to take. The "busy" method specifies a callback
431Tcl procedure that is invoked whenever SQLite tries to open a locked
432database. This callback can do whatever is desired. Presumably, the
433callback will do some other useful work for a short while (such as service
434GUI events) then return
435so that the lock can be tried again. The callback procedure should
436return "0" if it wants SQLite to try again to open the database and
437should return "1" if it wants SQLite to abandon the current operation.
438}
439
440##############################################################################
441METHOD exists {
442
443<p>The "exists" method is similar to "onecolumn" and "eval" in that
444it executes SQL statements. The difference is that the "exists" method
445always returns a boolean value which is TRUE if a query in the SQL
446statement it executes returns one or more rows and FALSE if the SQL
447returns an empty set.</p>
448
449<p>The "exists" method is often used to test for the existance of
450rows in a table. For example:</p>
451
452<blockquote><b>
453if {[db exists {SELECT 1 FROM table1 WHERE user=$user}]} {<br>
454&nbsp;&nbsp;&nbsp;# Processing if $user exists<br>
455} else {<br>
456&nbsp;&nbsp;&nbsp;# Processing if $user does not exist<br>
457}
458</b></blockquote>
459}
460
461
462##############################################################################
463METHOD last_insert_rowid {
464
465<p>The "last_insert_rowid" method returns an integer which is the ROWID
466of the most recently inserted database row.</p>
467}
468
469##############################################################################
470METHOD function {
471
472<p>The "function" method registers new SQL functions with the SQLite engine.
473The arguments are the name of the new SQL function and a TCL command that
474implements that function. Arguments to the function are appended to the
475TCL command before it is invoked.</p>
476
477<p>
478The following example creates a new SQL function named "hex" that converts
479its numeric argument in to a hexadecimal encoded string:
480</p>
481
482<blockquote><b>
483db function hex {format 0x%X}
484</b></blockquote>
485
486}
487
488##############################################################################
489METHOD nullvalue {
490
491<p>
492The "nullvalue" method changes the representation for NULL returned
493as result of the "eval" method.</p>
494
495<blockquote><b>
496db1 nullvalue NULL
497</b></blockquote>
498
499<p>The "nullvalue" method is useful to differ between NULL and empty
500column values as Tcl lacks a NULL representation. The default
501representation for NULL values is an empty string.</p>
502}
503
504
505
506##############################################################################
507METHOD onecolumn {
508
509<p>The "onecolumn" method works like
510"<a href="#eval">eval</a>" in that it evaluates the
511SQL query statement given as its argument. The difference is that
512"onecolumn" returns a single element which is the first column of the
513first row of the query result.</p>
514
515<p>This is a convenience method. It saves the user from having to
516do a "<tt>[lindex&nbsp;...&nbsp;0]</tt>" on the results of an "eval"
517in order to extract a single column result.</p>
518}
519
520##############################################################################
521METHOD changes {
522
523<p>The "changes" method returns an integer which is the number of rows
524in the database that were inserted, deleted, and/or modified by the most
525recent "eval" method.</p>
526}
527
528##############################################################################
529METHOD total_changes {
530
531<p>The "total_changes" method returns an integer which is the number of rows
532in the database that were inserted, deleted, and/or modified since the
533current database connection was first opened.</p>
534}
535
536##############################################################################
537METHOD authorizer {
538
539<p>The "authorizer" method provides access to the
540<a href="capi3ref.html#sqlite3_set_authorizer">sqlite3_set_authorizer</a>
541C/C++ interface. The argument to authorizer is the name of a procedure that
542is called when SQL statements are being compiled in order to authorize
543certain operations. The callback procedure takes 5 arguments which describe
544the operation being coded. If the callback returns the text string
545"SQLITE_OK", then the operation is allowed. If it returns "SQLITE_IGNORE",
546then the operation is silently disabled. If the return is "SQLITE_DENY"
547then the compilation fails with an error.
548</p>
549
550<p>If the argument is an empty string then the authorizer is disabled.
551If the argument is omitted, then the current authorizer is returned.</p>
552}
553
554##############################################################################
555METHOD progress {
556
557<p>This method registers a callback that is invoked periodically during
558query processing. There are two arguments: the number of SQLite virtual
559machine opcodes between invocations, and the TCL command to invoke.
560Setting the progress callback to an empty string disables it.</p>
561
562<p>The progress callback can be used to display the status of a lengthy
563query or to process GUI events during a lengthy query.</p>
564}
565
566
567##############################################################################
568METHOD collate {
569
570<p>This method registers new text collating sequences. There are
571two arguments: the name of the collating sequence and the name of a
572TCL procedure that implements a comparison function for the collating
573sequence.
574</p>
575
576<p>For example, the following code implements a collating sequence called
577"NOCASE" that sorts in text order without regard to case:
578</p>
579
580<blockquote><b>
581proc nocase_compare {a b} {<br>
582&nbsp;&nbsp;&nbsp;&nbsp;return [string compare [string tolower $a] [string tolower $b]]<br>
583}<br>
584db collate NOCASE nocase_compare<br>
585</b></blockquote>
586}
587
588##############################################################################
589METHOD collation_needed {
590
591<p>This method registers a callback routine that is invoked when the SQLite
592engine needs a particular collating sequence but does not have that
593collating sequence registered. The callback can register the collating
594sequence. The callback is invoked with a single parameter which is the
595name of the needed collating sequence.</p>
596}
597
598##############################################################################
599METHOD commit_hook {
600
601<p>This method registers a callback routine that is invoked just before
602SQLite tries to commit changes to a database. If the callback throws
603an exception or returns a non-zero result, then the transaction rolls back
604rather than commit.</p>
605}
606
607##############################################################################
608METHOD rollback_hook {
609
610<p>This method registers a callback routine that is invoked just before
611SQLite tries to do a rollback. The script argument is run without change.</p>
612}
613
614##############################################################################
615METHOD update_hook {
616
617<p>This method registers a callback routine that is invoked just before
618each row is modified by an UPDATE, INSERT, or DELETE statement. Four
619arguments are appended to the callback before it is invoked:</p>
620
621<ul>
622<li>The keyword "INSERT", "UPDATE", or "DELETE", as appropriate</li>
623<li>The name of the database which is being changed</li>
624<li>The table that is being changed</li>
625<li>The rowid of the row in the table being changed</li>
626</ul>
627}
628
629##############################################################################
630METHOD incrblob {
631
632<p>This method opens a TCL channel that can be used to read or write
633into a preexisting BLOB in the database. The syntax is like this:</p>
634
635<blockquote>
636<i>dbcmd</i>&nbsp;&nbsp;<b>incrblob</b>&nbsp;&nbsp;<b>?-readonly??</b>
637&nbsp;&nbsp;<i>?DB?&nbsp;&nbsp;TABLE&nbsp;&nbsp;COLUMN&nbsp;&nbsp;ROWID</i>
638</blockquote>
639
640<p>
641The command returns a new TCL channel for reading or writing to the BLOB.
642The channel is opened using the underlying
643<a href="/capi3ref.html#sqlite3_blob_open">sqlite3_blob_open()</a> C-langauge
644interface. Close the channel using the <b>close</b> command of TCL.
645</p>
646}
647
648##############################################################################
649METHOD errorcode {
650
651<p>This method returns the numeric error code that resulted from the most
652recent SQLite operation.</p>
653}
654
655##############################################################################
656METHOD trace {
657
658<p>The "trace" method registers a callback that is invoked as each SQL
659statement is compiled. The text of the SQL is appended as a single string
660to the command before it is invoked. This can be used (for example) to
661keep a log of all SQL operations that an application performs.
662</p>
663}
664
665
666footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/vdbe.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/vdbe.tcl
deleted file mode 100644
index ed0b712..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/vdbe.tcl
+++ /dev/null
@@ -1,1988 +0,0 @@
1#
2# Run this Tcl script to generate the vdbe.html file.
3#
4set rcsid {$Id: vdbe.tcl,v 1.14 2005/03/12 15:55:11 drh Exp $}
5source common.tcl
6header {The Virtual Database Engine of SQLite}
7puts {
8<h2>The Virtual Database Engine of SQLite</h2>
9
10<blockquote><b>
11This document describes the virtual machine used in SQLite version 2.8.0.
12The virtual machine in SQLite version 3.0 and 3.1 is very similar in
13concept but many of the opcodes have changed and the algorithms are
14somewhat different. Use this document as a rough guide to the idea
15behind the virtual machine in SQLite version 3, not as a reference on
16how the virtual machine works.
17</b></blockquote>
18}
19
20puts {
21<p>If you want to know how the SQLite library works internally,
22you need to begin with a solid understanding of the Virtual Database
23Engine or VDBE. The VDBE occurs right in the middle of the
24processing stream (see the <a href="arch.html">architecture diagram</a>)
25and so it seems to touch most parts of the library. Even
26parts of the code that do not directly interact with the VDBE
27are usually in a supporting role. The VDBE really is the heart of
28SQLite.</p>
29
30<p>This article is a brief introduction to how the VDBE
31works and in particular how the various VDBE instructions
32(documented <a href="opcode.html">here</a>) work together
33to do useful things with the database. The style is tutorial,
34beginning with simple tasks and working toward solving more
35complex problems. Along the way we will visit most
36submodules in the SQLite library. After completeing this tutorial,
37you should have a pretty good understanding of how SQLite works
38and will be ready to begin studying the actual source code.</p>
39
40<h2>Preliminaries</h2>
41
42<p>The VDBE implements a virtual computer that runs a program in
43its virtual machine language. The goal of each program is to
44interrogate or change the database. Toward this end, the machine
45language that the VDBE implements is specifically designed to
46search, read, and modify databases.</p>
47
48<p>Each instruction of the VDBE language contains an opcode and
49three operands labeled P1, P2, and P3. Operand P1 is an arbitrary
50integer. P2 is a non-negative integer. P3 is a pointer to a data
51structure or null-terminated string, possibly null. Only a few VDBE
52instructions use all three operands. Many instructions use only
53one or two operands. A significant number of instructions use
54no operands at all but instead take their data and store their results
55on the execution stack. The details of what each instruction
56does and which operands it uses are described in the separate
57<a href="opcode.html">opcode description</a> document.</p>
58
59<p>A VDBE program begins
60execution on instruction 0 and continues with successive instructions
61until it either (1) encounters a fatal error, (2) executes a
62Halt instruction, or (3) advances the program counter past the
63last instruction of the program. When the VDBE completes execution,
64all open database cursors are closed, all memory is freed, and
65everything is popped from the stack.
66So there are never any worries about memory leaks or
67undeallocated resources.</p>
68
69<p>If you have done any assembly language programming or have
70worked with any kind of abstract machine before, all of these
71details should be familiar to you. So let's jump right in and
72start looking as some code.</p>
73
74<a name="insert1">
75<h2>Inserting Records Into The Database</h2>
76
77<p>We begin with a problem that can be solved using a VDBE program
78that is only a few instructions long. Suppose we have an SQL
79table that was created like this:</p>
80
81<blockquote><pre>
82CREATE TABLE examp(one text, two int);
83</pre></blockquote>
84
85<p>In words, we have a database table named "examp" that has two
86columns of data named "one" and "two". Now suppose we want to insert a single
87record into this table. Like this:</p>
88
89<blockquote><pre>
90INSERT INTO examp VALUES('Hello, World!',99);
91</pre></blockquote>
92
93<p>We can see the VDBE program that SQLite uses to implement this
94INSERT using the <b>sqlite</b> command-line utility. First start
95up <b>sqlite</b> on a new, empty database, then create the table.
96Next change the output format of <b>sqlite</b> to a form that
97is designed to work with VDBE program dumps by entering the
98".explain" command.
99Finally, enter the INSERT statement shown above, but precede the
100INSERT with the special keyword "EXPLAIN". The EXPLAIN keyword
101will cause <b>sqlite</b> to print the VDBE program rather than
102execute it. We have:</p>
103}
104proc Code {body} {
105 puts {<blockquote><tt>}
106 regsub -all {&} [string trim $body] {\&amp;} body
107 regsub -all {>} $body {\&gt;} body
108 regsub -all {<} $body {\&lt;} body
109 regsub -all {\(\(\(} $body {<b>} body
110 regsub -all {\)\)\)} $body {</b>} body
111 regsub -all { } $body {\&nbsp;} body
112 regsub -all \n $body <br>\n body
113 puts $body
114 puts {</tt></blockquote>}
115}
116
117Code {
118$ (((sqlite test_database_1)))
119sqlite> (((CREATE TABLE examp(one text, two int);)))
120sqlite> (((.explain)))
121sqlite> (((EXPLAIN INSERT INTO examp VALUES('Hello, World!',99);)))
122addr opcode p1 p2 p3
123---- ------------ ----- ----- -----------------------------------
1240 Transaction 0 0
1251 VerifyCookie 0 81
1262 Transaction 1 0
1273 Integer 0 0
1284 OpenWrite 0 3 examp
1295 NewRecno 0 0
1306 String 0 0 Hello, World!
1317 Integer 99 0 99
1328 MakeRecord 2 0
1339 PutIntKey 0 1
13410 Close 0 0
13511 Commit 0 0
13612 Halt 0 0
137}
138
139puts {<p>As you can see above, our simple insert statement is
140implemented in 12 instructions. The first 3 and last 2 instructions are
141a standard prologue and epilogue, so the real work is done in the middle
1427 instructions. There are no jumps, so the program executes once through
143from top to bottom. Let's now look at each instruction in detail.<p>
144}
145
146Code {
1470 Transaction 0 0
1481 VerifyCookie 0 81
1492 Transaction 1 0
150}
151puts {
152<p>The instruction <a href="opcode.html#Transaction">Transaction</a>
153begins a transaction. The transaction ends when a Commit or Rollback
154opcode is encountered. P1 is the index of the database file on which
155the transaction is started. Index 0 is the main database file. A write
156lock is obtained on the database file when a transaction is started.
157No other process can read or write the file while the transaction is
158underway. Starting a transaction also creates a rollback journal. A
159transaction must be started before any changes can be made to the
160database.</p>
161
162<p>The instruction <a href="opcode.html#VerifyCookie">VerifyCookie</a>
163checks cookie 0 (the database schema version) to make sure it is equal
164to P2 (the value obtained when the database schema was last read).
165P1 is the database number (0 for the main database). This is done to
166make sure the database schema hasn't been changed by another thread, in
167which case it has to be reread.</p>
168
169<p> The second <a href="opcode.html#Transaction">Transaction</a>
170instruction begins a transaction and starts a rollback journal for
171database 1, the database used for temporary tables.</p>
172}
173
174proc stack args {
175 puts "<blockquote><table border=2>"
176 foreach elem $args {
177 puts "<tr><td align=left>$elem</td></tr>"
178 }
179 puts "</table></blockquote>"
180}
181
182Code {
1833 Integer 0 0
1844 OpenWrite 0 3 examp
185}
186puts {
187<p> The instruction <a href="opcode.html#Integer">Integer</a> pushes
188the integer value P1 (0) onto the stack. Here 0 is the number of the
189database to use in the following OpenWrite instruction. If P3 is not
190NULL then it is a string representation of the same integer. Afterwards
191the stack looks like this:</p>
192}
193stack {(integer) 0}
194
195puts {
196<p> The instruction <a href="opcode.html#OpenWrite">OpenWrite</a> opens
197a new read/write cursor with handle P1 (0 in this case) on table "examp",
198whose root page is P2 (3, in this database file). Cursor handles can be
199any non-negative integer. But the VDBE allocates cursors in an array
200with the size of the array being one more than the largest cursor. So
201to conserve memory, it is best to use handles beginning with zero and
202working upward consecutively. Here P3 ("examp") is the name of the
203table being opened, but this is unused, and only generated to make the
204code easier to read. This instruction pops the database number to use
205(0, the main database) from the top of the stack, so afterwards the
206stack is empty again.</p>
207}
208
209Code {
2105 NewRecno 0 0
211}
212puts {
213<p> The instruction <a href="opcode.html#NewRecno">NewRecno</a> creates
214a new integer record number for the table pointed to by cursor P1. The
215record number is one not currently used as a key in the table. The new
216record number is pushed onto the stack. Afterwards the stack looks like
217this:</p>
218}
219stack {(integer) new record key}
220
221Code {
2226 String 0 0 Hello, World!
223}
224puts {
225<p> The instruction <a href="opcode.html#String">String</a> pushes its
226P3 operand onto the stack. Afterwards the stack looks like this:</p>
227}
228stack {(string) "Hello, World!"} \
229 {(integer) new record key}
230
231Code {
2327 Integer 99 0 99
233}
234puts {
235<p> The instruction <a href="opcode.html#Integer">Integer</a> pushes
236its P1 operand (99) onto the stack. Afterwards the stack looks like
237this:</p>
238}
239stack {(integer) 99} \
240 {(string) "Hello, World!"} \
241 {(integer) new record key}
242
243Code {
2448 MakeRecord 2 0
245}
246puts {
247<p> The instruction <a href="opcode.html#MakeRecord">MakeRecord</a> pops
248the top P1 elements off the stack (2 in this case) and converts them into
249the binary format used for storing records in a database file.
250(See the <a href="fileformat.html">file format</a> description for
251details.) The new record generated by the MakeRecord instruction is
252pushed back onto the stack. Afterwards the stack looks like this:</p>
253</ul>
254}
255stack {(record) "Hello, World!", 99} \
256 {(integer) new record key}
257
258Code {
2599 PutIntKey 0 1
260}
261puts {
262<p> The instruction <a href="opcode.html#PutIntKey">PutIntKey</a> uses
263the top 2 stack entries to write an entry into the table pointed to by
264cursor P1. A new entry is created if it doesn't already exist or the
265data for an existing entry is overwritten. The record data is the top
266stack entry, and the key is the next entry down. The stack is popped
267twice by this instruction. Because operand P2 is 1 the row change count
268is incremented and the rowid is stored for subsequent return by the
269sqlite_last_insert_rowid() function. If P2 is 0 the row change count is
270unmodified. This instruction is where the insert actually occurs.</p>
271}
272
273Code {
27410 Close 0 0
275}
276puts {
277<p> The instruction <a href="opcode.html#Close">Close</a> closes a
278cursor previously opened as P1 (0, the only open cursor). If P1 is not
279currently open, this instruction is a no-op.</p>
280}
281
282Code {
28311 Commit 0 0
284}
285puts {
286<p> The instruction <a href="opcode.html#Commit">Commit</a> causes all
287modifications to the database that have been made since the last
288Transaction to actually take effect. No additional modifications are
289allowed until another transaction is started. The Commit instruction
290deletes the journal file and releases the write lock on the database.
291A read lock continues to be held if there are still cursors open.</p>
292}
293
294Code {
29512 Halt 0 0
296}
297puts {
298<p> The instruction <a href="opcode.html#Halt">Halt</a> causes the VDBE
299engine to exit immediately. All open cursors, Lists, Sorts, etc are
300closed automatically. P1 is the result code returned by sqlite_exec().
301For a normal halt, this should be SQLITE_OK (0). For errors, it can be
302some other value. The operand P2 is only used when there is an error.
303There is an implied "Halt 0 0 0" instruction at the end of every
304program, which the VDBE appends when it prepares a program to run.</p>
305
306
307<a name="trace">
308<h2>Tracing VDBE Program Execution</h2>
309
310<p>If the SQLite library is compiled without the NDEBUG preprocessor
311macro, then the PRAGMA <a href="pragma.html#pragma_vdbe_trace">vdbe_trace
312</a> causes the VDBE to trace the execution of programs. Though this
313feature was originally intended for testing and debugging, it can also
314be useful in learning about how the VDBE operates.
315Use "<tt>PRAGMA&nbsp;vdbe_trace=ON;</tt>" to turn tracing on and
316"<tt>PRAGMA&nbsp;vdbe_trace=OFF</tt>" to turn tracing back off.
317Like this:</p>
318}
319
320Code {
321sqlite> (((PRAGMA vdbe_trace=ON;)))
322 0 Halt 0 0
323sqlite> (((INSERT INTO examp VALUES('Hello, World!',99);)))
324 0 Transaction 0 0
325 1 VerifyCookie 0 81
326 2 Transaction 1 0
327 3 Integer 0 0
328Stack: i:0
329 4 OpenWrite 0 3 examp
330 5 NewRecno 0 0
331Stack: i:2
332 6 String 0 0 Hello, World!
333Stack: t[Hello,.World!] i:2
334 7 Integer 99 0 99
335Stack: si:99 t[Hello,.World!] i:2
336 8 MakeRecord 2 0
337Stack: s[...Hello,.World!.99] i:2
338 9 PutIntKey 0 1
339 10 Close 0 0
340 11 Commit 0 0
341 12 Halt 0 0
342}
343
344puts {
345<p>With tracing mode on, the VDBE prints each instruction prior
346to executing it. After the instruction is executed, the top few
347entries in the stack are displayed. The stack display is omitted
348if the stack is empty.</p>
349
350<p>On the stack display, most entries are shown with a prefix
351that tells the datatype of that stack entry. Integers begin
352with "<tt>i:</tt>". Floating point values begin with "<tt>r:</tt>".
353(The "r" stands for "real-number".) Strings begin with either
354"<tt>s:</tt>", "<tt>t:</tt>", "<tt>e:</tt>" or "<tt>z:</tt>".
355The difference among the string prefixes is caused by how their
356memory is allocated. The z: strings are stored in memory obtained
357from <b>malloc()</b>. The t: strings are statically allocated.
358The e: strings are ephemeral. All other strings have the s: prefix.
359This doesn't make any difference to you,
360the observer, but it is vitally important to the VDBE since the
361z: strings need to be passed to <b>free()</b> when they are
362popped to avoid a memory leak. Note that only the first 10
363characters of string values are displayed and that binary
364values (such as the result of the MakeRecord instruction) are
365treated as strings. The only other datatype that can be stored
366on the VDBE stack is a NULL, which is display without prefix
367as simply "<tt>NULL</tt>". If an integer has been placed on the
368stack as both an integer and a string, its prefix is "<tt>si:</tt>".
369
370
371<a name="query1">
372<h2>Simple Queries</h2>
373
374<p>At this point, you should understand the basics of how the VDBE
375writes to a database. Now let's look at how it does queries.
376We will use the following simple SELECT statement as our example:</p>
377
378<blockquote><pre>
379SELECT * FROM examp;
380</pre></blockquote>
381
382<p>The VDBE program generated for this SQL statement is as follows:</p>
383}
384
385Code {
386sqlite> (((EXPLAIN SELECT * FROM examp;)))
387addr opcode p1 p2 p3
388---- ------------ ----- ----- -----------------------------------
3890 ColumnName 0 0 one
3901 ColumnName 1 0 two
3912 Integer 0 0
3923 OpenRead 0 3 examp
3934 VerifyCookie 0 81
3945 Rewind 0 10
3956 Column 0 0
3967 Column 0 1
3978 Callback 2 0
3989 Next 0 6
39910 Close 0 0
40011 Halt 0 0
401}
402
403puts {
404<p>Before we begin looking at this problem, let's briefly review
405how queries work in SQLite so that we will know what we are trying
406to accomplish. For each row in the result of a query,
407SQLite will invoke a callback function with the following
408prototype:</p>
409
410<blockquote><pre>
411int Callback(void *pUserData, int nColumn, char *azData[], char *azColumnName[]);
412</pre></blockquote>
413
414<p>The SQLite library supplies the VDBE with a pointer to the callback function
415and the <b>pUserData</b> pointer. (Both the callback and the user data were
416originally passed in as arguments to the <b>sqlite_exec()</b> API function.)
417The job of the VDBE is to
418come up with values for <b>nColumn</b>, <b>azData[]</b>,
419and <b>azColumnName[]</b>.
420<b>nColumn</b> is the number of columns in the results, of course.
421<b>azColumnName[]</b> is an array of strings where each string is the name
422of one of the result columns. <b>azData[]</b> is an array of strings holding
423the actual data.</p>
424}
425
426Code {
4270 ColumnName 0 0 one
4281 ColumnName 1 0 two
429}
430puts {
431<p>The first two instructions in the VDBE program for our query are
432concerned with setting up values for <b>azColumn</b>.
433The <a href="opcode.html#ColumnName">ColumnName</a> instructions tell
434the VDBE what values to fill in for each element of the <b>azColumnName[]</b>
435array. Every query will begin with one ColumnName instruction for each
436column in the result, and there will be a matching Column instruction for
437each one later in the query.
438</p>
439}
440
441Code {
4422 Integer 0 0
4433 OpenRead 0 3 examp
4444 VerifyCookie 0 81
445}
446puts {
447<p>Instructions 2 and 3 open a read cursor on the database table that is
448to be queried. This works the same as the OpenWrite instruction in the
449INSERT example except that the cursor is opened for reading this time
450instead of for writing. Instruction 4 verifies the database schema as
451in the INSERT example.</p>
452}
453
454Code {
4555 Rewind 0 10
456}
457puts {
458<p> The <a href="opcode.html#Rewind">Rewind</a> instruction initializes
459a loop that iterates over the "examp" table. It rewinds the cursor P1
460to the first entry in its table. This is required by the the Column and
461Next instructions, which use the cursor to iterate through the table.
462If the table is empty, then jump to P2 (10), which is the instruction just
463past the loop. If the table is not empty, fall through to the following
464instruction at 6, which is the beginning of the loop body.</p>
465}
466
467Code {
4686 Column 0 0
4697 Column 0 1
4708 Callback 2 0
471}
472puts {
473<p> The instructions 6 through 8 form the body of the loop that will
474execute once for each record in the database file.
475
476The <a href="opcode.html#Column">Column</a> instructions at addresses 6
477and 7 each take the P2-th column from the P1-th cursor and push it onto
478the stack. In this example, the first Column instruction is pushing the
479value for the column "one" onto the stack and the second Column
480instruction is pushing the value for column "two".
481
482The <a href="opcode.html#Callback">Callback</a> instruction at address 8
483invokes the callback() function. The P1 operand to Callback becomes the
484value for <b>nColumn</b>. The Callback instruction pops P1 values from
485the stack and uses them to fill the <b>azData[]</b> array.</p>
486}
487
488Code {
4899 Next 0 6
490}
491puts {
492<p>The instruction at address 9 implements the branching part of the
493loop. Together with the Rewind at address 5 it forms the loop logic.
494This is a key concept that you should pay close attention to.
495The <a href="opcode.html#Next">Next</a> instruction advances the cursor
496P1 to the next record. If the cursor advance was successful, then jump
497immediately to P2 (6, the beginning of the loop body). If the cursor
498was at the end, then fall through to the following instruction, which
499ends the loop.</p>
500}
501
502Code {
50310 Close 0 0
50411 Halt 0 0
505}
506puts {
507<p>The Close instruction at the end of the program closes the
508cursor that points into the table "examp". It is not really necessary
509to call Close here since all cursors will be automatically closed
510by the VDBE when the program halts. But we needed an instruction
511for the Rewind to jump to so we might as well go ahead and have that
512instruction do something useful.
513The Halt instruction ends the VDBE program.</p>
514
515<p>Note that the program for this SELECT query didn't contain the
516Transaction and Commit instructions used in the INSERT example. Because
517the SELECT is a read operation that doesn't alter the database, it
518doesn't require a transaction.</p>
519}
520
521
522puts {
523<a name="query2">
524<h2>A Slightly More Complex Query</h2>
525
526<p>The key points of the previous example were the use of the Callback
527instruction to invoke the callback function, and the use of the Next
528instruction to implement a loop over all records of the database file.
529This example attempts to drive home those ideas by demonstrating a
530slightly more complex query that involves more columns of
531output, some of which are computed values, and a WHERE clause that
532limits which records actually make it to the callback function.
533Consider this query:</p>
534
535<blockquote><pre>
536SELECT one, two, one || two AS 'both'
537FROM examp
538WHERE one LIKE 'H%'
539</pre></blockquote>
540
541<p>This query is perhaps a bit contrived, but it does serve to
542illustrate our points. The result will have three column with
543names "one", "two", and "both". The first two columns are direct
544copies of the two columns in the table and the third result
545column is a string formed by concatenating the first and
546second columns of the table.
547Finally, the
548WHERE clause says that we will only chose rows for the
549results where the "one" column begins with an "H".
550Here is what the VDBE program looks like for this query:</p>
551}
552
553Code {
554addr opcode p1 p2 p3
555---- ------------ ----- ----- -----------------------------------
5560 ColumnName 0 0 one
5571 ColumnName 1 0 two
5582 ColumnName 2 0 both
5593 Integer 0 0
5604 OpenRead 0 3 examp
5615 VerifyCookie 0 81
5626 Rewind 0 18
5637 String 0 0 H%
5648 Column 0 0
5659 Function 2 0 ptr(0x7f1ac0)
56610 IfNot 1 17
56711 Column 0 0
56812 Column 0 1
56913 Column 0 0
57014 Column 0 1
57115 Concat 2 0
57216 Callback 3 0
57317 Next 0 7
57418 Close 0 0
57519 Halt 0 0
576}
577
578puts {
579<p>Except for the WHERE clause, the structure of the program for
580this example is very much like the prior example, just with an
581extra column. There are now 3 columns, instead of 2 as before,
582and there are three ColumnName instructions.
583A cursor is opened using the OpenRead instruction, just like in the
584prior example. The Rewind instruction at address 6 and the
585Next at address 17 form a loop over all records of the table.
586The Close instruction at the end is there to give the
587Rewind instruction something to jump to when it is done. All of
588this is just like in the first query demonstration.</p>
589
590<p>The Callback instruction in this example has to generate
591data for three result columns instead of two, but is otherwise
592the same as in the first query. When the Callback instruction
593is invoked, the left-most column of the result should be
594the lowest in the stack and the right-most result column should
595be the top of the stack. We can see the stack being set up
596this way at addresses 11 through 15. The Column instructions at
59711 and 12 push the values for the first two columns in the result.
598The two Column instructions at 13 and 14 pull in the values needed
599to compute the third result column and the Concat instruction at
60015 joins them together into a single entry on the stack.</p>
601
602<p>The only thing that is really new about the current example
603is the WHERE clause which is implemented by instructions at
604addresses 7 through 10. Instructions at address 7 and 8 push
605onto the stack the value of the "one" column from the table
606and the literal string "H%".
607The <a href="opcode.html#Function">Function</a> instruction at address 9
608pops these two values from the stack and pushes the result of the LIKE()
609function back onto the stack.
610The <a href="opcode.html#IfNot">IfNot</a> instruction pops the top stack
611value and causes an immediate jump forward to the Next instruction if the
612top value was false (<em>not</em> not like the literal string "H%").
613Taking this jump effectively skips the callback, which is the whole point
614of the WHERE clause. If the result
615of the comparison is true, the jump is not taken and control
616falls through to the Callback instruction below.</p>
617
618<p>Notice how the LIKE operator is implemented. It is a user-defined
619function in SQLite, so the address of its function definition is
620specified in P3. The operand P1 is the number of function arguments for
621it to take from the stack. In this case the LIKE() function takes 2
622arguments. The arguments are taken off the stack in reverse order
623(right-to-left), so the pattern to match is the top stack element, and
624the next element is the data to compare. The return value is pushed
625onto the stack.</p>
626
627
628<a name="pattern1">
629<h2>A Template For SELECT Programs</h2>
630
631<p>The first two query examples illustrate a kind of template that
632every SELECT program will follow. Basically, we have:</p>
633
634<p>
635<ol>
636<li>Initialize the <b>azColumnName[]</b> array for the callback.</li>
637<li>Open a cursor into the table to be queried.</li>
638<li>For each record in the table, do:
639 <ol type="a">
640 <li>If the WHERE clause evaluates to FALSE, then skip the steps that
641 follow and continue to the next record.</li>
642 <li>Compute all columns for the current row of the result.</li>
643 <li>Invoke the callback function for the current row of the result.</li>
644 </ol>
645<li>Close the cursor.</li>
646</ol>
647</p>
648
649<p>This template will be expanded considerably as we consider
650additional complications such as joins, compound selects, using
651indices to speed the search, sorting, and aggregate functions
652with and without GROUP BY and HAVING clauses.
653But the same basic ideas will continue to apply.</p>
654
655<h2>UPDATE And DELETE Statements</h2>
656
657<p>The UPDATE and DELETE statements are coded using a template
658that is very similar to the SELECT statement template. The main
659difference, of course, is that the end action is to modify the
660database rather than invoke a callback function. Because it modifies
661the database it will also use transactions. Let's begin
662by looking at a DELETE statement:</p>
663
664<blockquote><pre>
665DELETE FROM examp WHERE two<50;
666</pre></blockquote>
667
668<p>This DELETE statement will remove every record from the "examp"
669table where the "two" column is less than 50.
670The code generated to do this is as follows:</p>
671}
672
673Code {
674addr opcode p1 p2 p3
675---- ------------ ----- ----- -----------------------------------
6760 Transaction 1 0
6771 Transaction 0 0
6782 VerifyCookie 0 178
6793 Integer 0 0
6804 OpenRead 0 3 examp
6815 Rewind 0 12
6826 Column 0 1
6837 Integer 50 0 50
6848 Ge 1 11
6859 Recno 0 0
68610 ListWrite 0 0
68711 Next 0 6
68812 Close 0 0
68913 ListRewind 0 0
69014 Integer 0 0
69115 OpenWrite 0 3
69216 ListRead 0 20
69317 NotExists 0 19
69418 Delete 0 1
69519 Goto 0 16
69620 ListReset 0 0
69721 Close 0 0
69822 Commit 0 0
69923 Halt 0 0
700}
701
702puts {
703<p>Here is what the program must do. First it has to locate all of
704the records in the table "examp" that are to be deleted. This is
705done using a loop very much like the loop used in the SELECT examples
706above. Once all records have been located, then we can go back through
707and delete them one by one. Note that we cannot delete each record
708as soon as we find it. We have to locate all records first, then
709go back and delete them. This is because the SQLite database
710backend might change the scan order after a delete operation.
711And if the scan
712order changes in the middle of the scan, some records might be
713visited more than once and other records might not be visited at all.</p>
714
715<p>So the implemention of DELETE is really in two loops. The first loop
716(instructions 5 through 11) locates the records that are to be deleted
717and saves their keys onto a temporary list, and the second loop
718(instructions 16 through 19) uses the key list to delete the records one
719by one. </p>
720}
721
722
723Code {
7240 Transaction 1 0
7251 Transaction 0 0
7262 VerifyCookie 0 178
7273 Integer 0 0
7284 OpenRead 0 3 examp
729}
730puts {
731<p>Instructions 0 though 4 are as in the INSERT example. They start
732transactions for the main and temporary databases, verify the database
733schema for the main database, and open a read cursor on the table
734"examp". Notice that the cursor is opened for reading, not writing. At
735this stage of the program we are only going to be scanning the table,
736not changing it. We will reopen the same table for writing later, at
737instruction 15.</p>
738}
739
740Code {
7415 Rewind 0 12
742}
743puts {
744<p>As in the SELECT example, the <a href="opcode.html#Rewind">Rewind</a>
745instruction rewinds the cursor to the beginning of the table, readying
746it for use in the loop body.</p>
747}
748
749Code {
7506 Column 0 1
7517 Integer 50 0 50
7528 Ge 1 11
753}
754puts {
755<p>The WHERE clause is implemented by instructions 6 through 8.
756The job of the where clause is to skip the ListWrite if the WHERE
757condition is false. To this end, it jumps ahead to the Next instruction
758if the "two" column (extracted by the Column instruction) is
759greater than or equal to 50.</p>
760
761<p>As before, the Column instruction uses cursor P1 and pushes the data
762record in column P2 (1, column "two") onto the stack. The Integer
763instruction pushes the value 50 onto the top of the stack. After these
764two instructions the stack looks like:</p>
765}
766stack {(integer) 50} \
767 {(record) current record for column "two" }
768
769puts {
770<p>The <a href="opcode.html#Ge">Ge</a> operator compares the top two
771elements on the stack, pops them, and then branches based on the result
772of the comparison. If the second element is >= the top element, then
773jump to address P2 (the Next instruction at the end of the loop).
774Because P1 is true, if either operand is NULL (and thus the result is
775NULL) then take the jump. If we don't jump, just advance to the next
776instruction.</p>
777}
778
779Code {
7809 Recno 0 0
78110 ListWrite 0 0
782}
783puts {
784<p>The <a href="opcode.html#Recno">Recno</a> instruction pushes onto the
785stack an integer which is the first 4 bytes of the the key to the current
786entry in a sequential scan of the table pointed to by cursor P1.
787The <a href="opcode.html#ListWrite">ListWrite</a> instruction writes the
788integer on the top of the stack into a temporary storage list and pops
789the top element. This is the important work of this loop, to store the
790keys of the records to be deleted so we can delete them in the second
791loop. After this ListWrite instruction the stack is empty again.</p>
792}
793
794Code {
79511 Next 0 6
79612 Close 0 0
797}
798puts {
799<p> The Next instruction increments the cursor to point to the next
800element in the table pointed to by cursor P0, and if it was successful
801branches to P2 (6, the beginning of the loop body). The Close
802instruction closes cursor P1. It doesn't affect the temporary storage
803list because it isn't associated with cursor P1; it is instead a global
804working list (which can be saved with ListPush).</p>
805}
806
807Code {
80813 ListRewind 0 0
809}
810puts {
811<p> The <a href="opcode.html#ListRewind">ListRewind</a> instruction
812rewinds the temporary storage list to the beginning. This prepares it
813for use in the second loop.</p>
814}
815
816Code {
81714 Integer 0 0
81815 OpenWrite 0 3
819}
820puts {
821<p> As in the INSERT example, we push the database number P1 (0, the main
822database) onto the stack and use OpenWrite to open the cursor P1 on table
823P2 (base page 3, "examp") for modification.</p>
824}
825
826Code {
82716 ListRead 0 20
82817 NotExists 0 19
82918 Delete 0 1
83019 Goto 0 16
831}
832puts {
833<p>This loop does the actual deleting. It is organized differently from
834the one in the UPDATE example. The ListRead instruction plays the role
835that the Next did in the INSERT loop, but because it jumps to P2 on
836failure, and Next jumps on success, we put it at the start of the loop
837instead of the end. This means that we have to put a Goto at the end of
838the loop to jump back to the the loop test at the beginning. So this
839loop has the form of a C while(){...} loop, while the loop in the INSERT
840example had the form of a do{...}while() loop. The Delete instruction
841fills the role that the callback function did in the preceding examples.
842</p>
843<p>The <a href="opcode.html#ListRead">ListRead</a> instruction reads an
844element from the temporary storage list and pushes it onto the stack.
845If this was successful, it continues to the next instruction. If this
846fails because the list is empty, it branches to P2, which is the
847instruction just after the loop. Afterwards the stack looks like:</p>
848}
849stack {(integer) key for current record}
850
851puts {
852<p>Notice the similarity between the ListRead and Next instructions.
853Both operations work according to this rule:
854</p>
855<blockquote>
856Push the next "thing" onto the stack and fall through OR jump to P2,
857depending on whether or not there is a next "thing" to push.
858</blockquote>
859<p>One difference between Next and ListRead is their idea of a "thing".
860The "things" for the Next instruction are records in a database file.
861"Things" for ListRead are integer keys in a list. Another difference
862is whether to jump or fall through if there is no next "thing". In this
863case, Next falls through, and ListRead jumps. Later on, we will see
864other looping instructions (NextIdx and SortNext) that operate using the
865same principle.</p>
866
867<p>The <a href="opcode.html#NotExists">NotExists</a> instruction pops
868the top stack element and uses it as an integer key. If a record with
869that key does not exist in table P1, then jump to P2. If a record does
870exist, then fall thru to the next instruction. In this case P2 takes
871us to the Goto at the end of the loop, which jumps back to the ListRead
872at the beginning. This could have been coded to have P2 be 16, the
873ListRead at the start of the loop, but the SQLite parser which generated
874this code didn't make that optimization.</p>
875<p>The <a href="opcode.html#Delete">Delete</a> does the work of this
876loop; it pops an integer key off the stack (placed there by the
877preceding ListRead) and deletes the record of cursor P1 that has that key.
878Because P2 is true, the row change counter is incremented.</p>
879<p>The <a href="opcode.html#Goto">Goto</a> jumps back to the beginning
880of the loop. This is the end of the loop.</p>
881}
882
883Code {
88420 ListReset 0 0
88521 Close 0 0
88622 Commit 0 0
88723 Halt 0 0
888}
889puts {
890<p>This block of instruction cleans up the VDBE program. Three of these
891instructions aren't really required, but are generated by the SQLite
892parser from its code templates, which are designed to handle more
893complicated cases.</p>
894<p>The <a href="opcode.html#ListReset">ListReset</a> instruction empties
895the temporary storage list. This list is emptied automatically when the
896VDBE program terminates, so it isn't necessary in this case. The Close
897instruction closes the cursor P1. Again, this is done by the VDBE
898engine when it is finished running this program. The Commit ends the
899current transaction successfully, and causes all changes that occurred
900in this transaction to be saved to the database. The final Halt is also
901unneccessary, since it is added to every VDBE program when it is
902prepared to run.</p>
903
904
905<p>UPDATE statements work very much like DELETE statements except
906that instead of deleting the record they replace it with a new one.
907Consider this example:
908</p>
909
910<blockquote><pre>
911UPDATE examp SET one= '(' || one || ')' WHERE two < 50;
912</pre></blockquote>
913
914<p>Instead of deleting records where the "two" column is less than
91550, this statement just puts the "one" column in parentheses
916The VDBE program to implement this statement follows:</p>
917}
918
919Code {
920addr opcode p1 p2 p3
921---- ------------ ----- ----- -----------------------------------
9220 Transaction 1 0
9231 Transaction 0 0
9242 VerifyCookie 0 178
9253 Integer 0 0
9264 OpenRead 0 3 examp
9275 Rewind 0 12
9286 Column 0 1
9297 Integer 50 0 50
9308 Ge 1 11
9319 Recno 0 0
93210 ListWrite 0 0
93311 Next 0 6
93412 Close 0 0
93513 Integer 0 0
93614 OpenWrite 0 3
93715 ListRewind 0 0
93816 ListRead 0 28
93917 Dup 0 0
94018 NotExists 0 16
94119 String 0 0 (
94220 Column 0 0
94321 Concat 2 0
94422 String 0 0 )
94523 Concat 2 0
94624 Column 0 1
94725 MakeRecord 2 0
94826 PutIntKey 0 1
94927 Goto 0 16
95028 ListReset 0 0
95129 Close 0 0
95230 Commit 0 0
95331 Halt 0 0
954}
955
956puts {
957<p>This program is essentially the same as the DELETE program except
958that the body of the second loop has been replace by a sequence of
959instructions (at addresses 17 through 26) that update the record rather
960than delete it. Most of this instruction sequence should already be
961familiar to you, but there are a couple of minor twists so we will go
962over it briefly. Also note that the order of some of the instructions
963before and after the 2nd loop has changed. This is just the way the
964SQLite parser chose to output the code using a different template.</p>
965
966<p>As we enter the interior of the second loop (at instruction 17)
967the stack contains a single integer which is the key of the
968record we want to modify. We are going to need to use this
969key twice: once to fetch the old value of the record and
970a second time to write back the revised record. So the first instruction
971is a Dup to make a duplicate of the key on the top of the stack. The
972Dup instruction will duplicate any element of the stack, not just the top
973element. You specify which element to duplication using the
974P1 operand. When P1 is 0, the top of the stack is duplicated.
975When P1 is 1, the next element down on the stack duplication.
976And so forth.</p>
977
978<p>After duplicating the key, the next instruction, NotExists,
979pops the stack once and uses the value popped as a key to
980check the existence of a record in the database file. If there is no record
981for this key, it jumps back to the ListRead to get another key.</p>
982
983<p>Instructions 19 through 25 construct a new database record
984that will be used to replace the existing record. This is
985the same kind of code that we saw
986in the description of INSERT and will not be described further.
987After instruction 25 executes, the stack looks like this:</p>
988}
989
990stack {(record) new data record} {(integer) key}
991
992puts {
993<p>The PutIntKey instruction (also described
994during the discussion about INSERT) writes an entry into the
995database file whose data is the top of the stack and whose key
996is the next on the stack, and then pops the stack twice. The
997PutIntKey instruction will overwrite the data of an existing record
998with the same key, which is what we want here. Overwriting was not
999an issue with INSERT because with INSERT the key was generated
1000by the NewRecno instruction which is guaranteed to provide a key
1001that has not been used before.</p>
1002}
1003
1004if 0 {<p>(By the way, since keys must
1005all be unique and each key is a 32-bit integer, a single
1006SQLite database table can have no more than 2<sup>32</sup>
1007rows. Actually, the Key instruction starts to become
1008very inefficient as you approach this upper bound, so it
1009is best to keep the number of entries below 2<sup>31</sup>
1010or so. Surely a couple billion records will be enough for
1011most applications!)</p>
1012}
1013
1014puts {
1015<h2>CREATE and DROP</h2>
1016
1017<p>Using CREATE or DROP to create or destroy a table or index is
1018really the same as doing an INSERT or DELETE from the special
1019"sqlite_master" table, at least from the point of view of the VDBE.
1020The sqlite_master table is a special table that is automatically
1021created for every SQLite database. It looks like this:</p>
1022
1023<blockquote><pre>
1024CREATE TABLE sqlite_master (
1025 type TEXT, -- either "table" or "index"
1026 name TEXT, -- name of this table or index
1027 tbl_name TEXT, -- for indices: name of associated table
1028 sql TEXT -- SQL text of the original CREATE statement
1029)
1030</pre></blockquote>
1031
1032<p>Every table (except the "sqlite_master" table itself)
1033and every named index in an SQLite database has an entry
1034in the sqlite_master table. You can query this table using
1035a SELECT statement just like any other table. But you are
1036not allowed to directly change the table using UPDATE, INSERT,
1037or DELETE. Changes to sqlite_master have to occur using
1038the CREATE and DROP commands because SQLite also has to update
1039some of its internal data structures when tables and indices
1040are added or destroyed.</p>
1041
1042<p>But from the point of view of the VDBE, a CREATE works
1043pretty much like an INSERT and a DROP works like a DELETE.
1044When the SQLite library opens to an existing database,
1045the first thing it does is a SELECT to read the "sql"
1046columns from all entries of the sqlite_master table.
1047The "sql" column contains the complete SQL text of the
1048CREATE statement that originally generated the index or
1049table. This text is fed back into the SQLite parser
1050and used to reconstruct the
1051internal data structures describing the index or table.</p>
1052
1053<h2>Using Indexes To Speed Searching</h2>
1054
1055<p>In the example queries above, every row of the table being
1056queried must be loaded off of the disk and examined, even if only
1057a small percentage of the rows end up in the result. This can
1058take a long time on a big table. To speed things up, SQLite
1059can use an index.</p>
1060
1061<p>An SQLite file associates a key with some data. For an SQLite
1062table, the database file is set up so that the key is an integer
1063and the data is the information for one row of the table.
1064Indices in SQLite reverse this arrangement. The index key
1065is (some of) the information being stored and the index data
1066is an integer.
1067To access a table row that has some particular
1068content, we first look up the content in the index table to find
1069its integer index, then we use that integer to look up the
1070complete record in the table.</p>
1071
1072<p>Note that SQLite uses b-trees, which are a sorted data structure,
1073so indices can be used when the WHERE clause of the SELECT statement
1074contains tests for equality or inequality. Queries like the following
1075can use an index if it is available:</p>
1076
1077<blockquote><pre>
1078SELECT * FROM examp WHERE two==50;
1079SELECT * FROM examp WHERE two<50;
1080SELECT * FROM examp WHERE two IN (50, 100);
1081</pre></blockquote>
1082
1083<p>If there exists an index that maps the "two" column of the "examp"
1084table into integers, then SQLite will use that index to find the integer
1085keys of all rows in examp that have a value of 50 for column two, or
1086all rows that are less than 50, etc.
1087But the following queries cannot use the index:</p>
1088
1089<blockquote><pre>
1090SELECT * FROM examp WHERE two%50 == 10;
1091SELECT * FROM examp WHERE two&127 == 3;
1092</pre></blockquote>
1093
1094<p>Note that the SQLite parser will not always generate code to use an
1095index, even if it is possible to do so. The following queries will not
1096currently use the index:</p>
1097
1098<blockquote><pre>
1099SELECT * FROM examp WHERE two+10 == 50;
1100SELECT * FROM examp WHERE two==50 OR two==100;
1101</pre></blockquote>
1102
1103<p>To understand better how indices work, lets first look at how
1104they are created. Let's go ahead and put an index on the two
1105column of the examp table. We have:</p>
1106
1107<blockquote><pre>
1108CREATE INDEX examp_idx1 ON examp(two);
1109</pre></blockquote>
1110
1111<p>The VDBE code generated by the above statement looks like the
1112following:</p>
1113}
1114
1115Code {
1116addr opcode p1 p2 p3
1117---- ------------ ----- ----- -----------------------------------
11180 Transaction 1 0
11191 Transaction 0 0
11202 VerifyCookie 0 178
11213 Integer 0 0
11224 OpenWrite 0 2
11235 NewRecno 0 0
11246 String 0 0 index
11257 String 0 0 examp_idx1
11268 String 0 0 examp
11279 CreateIndex 0 0 ptr(0x791380)
112810 Dup 0 0
112911 Integer 0 0
113012 OpenWrite 1 0
113113 String 0 0 CREATE INDEX examp_idx1 ON examp(tw
113214 MakeRecord 5 0
113315 PutIntKey 0 0
113416 Integer 0 0
113517 OpenRead 2 3 examp
113618 Rewind 2 24
113719 Recno 2 0
113820 Column 2 1
113921 MakeIdxKey 1 0 n
114022 IdxPut 1 0 indexed columns are not unique
114123 Next 2 19
114224 Close 2 0
114325 Close 1 0
114426 Integer 333 0
114527 SetCookie 0 0
114628 Close 0 0
114729 Commit 0 0
114830 Halt 0 0
1149}
1150
1151puts {
1152<p>Remember that every table (except sqlite_master) and every named
1153index has an entry in the sqlite_master table. Since we are creating
1154a new index, we have to add a new entry to sqlite_master. This is
1155handled by instructions 3 through 15. Adding an entry to sqlite_master
1156works just like any other INSERT statement so we will not say anymore
1157about it here. In this example, we want to focus on populating the
1158new index with valid data, which happens on instructions 16 through
115923.</p>
1160}
1161
1162Code {
116316 Integer 0 0
116417 OpenRead 2 3 examp
1165}
1166puts {
1167<p>The first thing that happens is that we open the table being
1168indexed for reading. In order to construct an index for a table,
1169we have to know what is in that table. The index has already been
1170opened for writing using cursor 0 by instructions 3 and 4.</p>
1171}
1172
1173Code {
117418 Rewind 2 24
117519 Recno 2 0
117620 Column 2 1
117721 MakeIdxKey 1 0 n
117822 IdxPut 1 0 indexed columns are not unique
117923 Next 2 19
1180}
1181puts {
1182<p>Instructions 18 through 23 implement a loop over every row of the
1183table being indexed. For each table row, we first extract the integer
1184key for that row using Recno in instruction 19, then get the value of
1185the "two" column using Column in instruction 20.
1186The <a href="opcode.html#MakeIdxKey">MakeIdxKey</a> instruction at 21
1187converts data from the "two" column (which is on the top of the stack)
1188into a valid index key. For an index on a single column, this is
1189basically a no-op. But if the P1 operand to MakeIdxKey had been
1190greater than one multiple entries would have been popped from the stack
1191and converted into a single index key.
1192The <a href="opcode.html#IdxPut">IdxPut</a> instruction at 22 is what
1193actually creates the index entry. IdxPut pops two elements from the
1194stack. The top of the stack is used as a key to fetch an entry from the
1195index table. Then the integer which was second on stack is added to the
1196set of integers for that index and the new record is written back to the
1197database file. Note
1198that the same index entry can store multiple integers if there
1199are two or more table entries with the same value for the two
1200column.
1201</p>
1202
1203<p>Now let's look at how this index will be used. Consider the
1204following query:</p>
1205
1206<blockquote><pre>
1207SELECT * FROM examp WHERE two==50;
1208</pre></blockquote>
1209
1210<p>SQLite generates the following VDBE code to handle this query:</p>
1211}
1212
1213Code {
1214addr opcode p1 p2 p3
1215---- ------------ ----- ----- -----------------------------------
12160 ColumnName 0 0 one
12171 ColumnName 1 0 two
12182 Integer 0 0
12193 OpenRead 0 3 examp
12204 VerifyCookie 0 256
12215 Integer 0 0
12226 OpenRead 1 4 examp_idx1
12237 Integer 50 0 50
12248 MakeKey 1 0 n
12259 MemStore 0 0
122610 MoveTo 1 19
122711 MemLoad 0 0
122812 IdxGT 1 19
122913 IdxRecno 1 0
123014 MoveTo 0 0
123115 Column 0 0
123216 Column 0 1
123317 Callback 2 0
123418 Next 1 11
123519 Close 0 0
123620 Close 1 0
123721 Halt 0 0
1238}
1239
1240puts {
1241<p>The SELECT begins in a familiar fashion. First the column
1242names are initialized and the table being queried is opened.
1243Things become different beginning with instructions 5 and 6 where
1244the index file is also opened. Instructions 7 and 8 make
1245a key with the value of 50.
1246The <a href="opcode.html#MemStore">MemStore</a> instruction at 9 stores
1247the index key in VDBE memory location 0. The VDBE memory is used to
1248avoid having to fetch a value from deep in the stack, which can be done,
1249but makes the program harder to generate. The following instruction
1250<a href="opcode.html#MoveTo">MoveTo</a> at address 10 pops the key off
1251the stack and moves the index cursor to the first row of the index with
1252that key. This initializes the cursor for use in the following loop.</p>
1253
1254<p>Instructions 11 through 18 implement a loop over all index records
1255with the key that was fetched by instruction 8. All of the index
1256records with this key will be contiguous in the index table, so we walk
1257through them and fetch the corresponding table key from the index.
1258This table key is then used to move the cursor to that row in the table.
1259The rest of the loop is the same as the loop for the non-indexed SELECT
1260query.</p>
1261
1262<p>The loop begins with the <a href="opcode.html#MemLoad">MemLoad</a>
1263instruction at 11 which pushes a copy of the index key back onto the
1264stack. The instruction <a href="opcode.html#IdxGT">IdxGT</a> at 12
1265compares the key to the key in the current index record pointed to by
1266cursor P1. If the index key at the current cursor location is greater
1267than the the index we are looking for, then jump out of the loop.</p>
1268
1269<p>The instruction <a href="opcode.html#IdxRecno">IdxRecno</a> at 13
1270pushes onto the stack the table record number from the index. The
1271following MoveTo pops it and moves the table cursor to that row. The
1272next 3 instructions select the column data the same way as in the non-
1273indexed case. The Column instructions fetch the column data and the
1274callback function is invoked. The final Next instruction advances the
1275index cursor, not the table cursor, to the next row, and then branches
1276back to the start of the loop if there are any index records left.</p>
1277
1278<p>Since the index is used to look up values in the table,
1279it is important that the index and table be kept consistent.
1280Now that there is an index on the examp table, we will have
1281to update that index whenever data is inserted, deleted, or
1282changed in the examp table. Remember the first example above
1283where we were able to insert a new row into the "examp" table using
128412 VDBE instructions. Now that this table is indexed, 19
1285instructions are required. The SQL statement is this:</p>
1286
1287<blockquote><pre>
1288INSERT INTO examp VALUES('Hello, World!',99);
1289</pre></blockquote>
1290
1291<p>And the generated code looks like this:</p>
1292}
1293
1294Code {
1295addr opcode p1 p2 p3
1296---- ------------ ----- ----- -----------------------------------
12970 Transaction 1 0
12981 Transaction 0 0
12992 VerifyCookie 0 256
13003 Integer 0 0
13014 OpenWrite 0 3 examp
13025 Integer 0 0
13036 OpenWrite 1 4 examp_idx1
13047 NewRecno 0 0
13058 String 0 0 Hello, World!
13069 Integer 99 0 99
130710 Dup 2 1
130811 Dup 1 1
130912 MakeIdxKey 1 0 n
131013 IdxPut 1 0
131114 MakeRecord 2 0
131215 PutIntKey 0 1
131316 Close 0 0
131417 Close 1 0
131518 Commit 0 0
131619 Halt 0 0
1317}
1318
1319puts {
1320<p>At this point, you should understand the VDBE well enough to
1321figure out on your own how the above program works. So we will
1322not discuss it further in this text.</p>
1323
1324<h2>Joins</h2>
1325
1326<p>In a join, two or more tables are combined to generate a single
1327result. The result table consists of every possible combination
1328of rows from the tables being joined. The easiest and most natural
1329way to implement this is with nested loops.</p>
1330
1331<p>Recall the query template discussed above where there was a
1332single loop that searched through every record of the table.
1333In a join we have basically the same thing except that there
1334are nested loops. For example, to join two tables, the query
1335template might look something like this:</p>
1336
1337<p>
1338<ol>
1339<li>Initialize the <b>azColumnName[]</b> array for the callback.</li>
1340<li>Open two cursors, one to each of the two tables being queried.</li>
1341<li>For each record in the first table, do:
1342 <ol type="a">
1343 <li>For each record in the second table do:
1344 <ol type="i">
1345 <li>If the WHERE clause evaluates to FALSE, then skip the steps that
1346 follow and continue to the next record.</li>
1347 <li>Compute all columns for the current row of the result.</li>
1348 <li>Invoke the callback function for the current row of the result.</li>
1349 </ol></li>
1350 </ol>
1351<li>Close both cursors.</li>
1352</ol>
1353</p>
1354
1355<p>This template will work, but it is likely to be slow since we
1356are now dealing with an O(N<sup>2</sup>) loop. But it often works
1357out that the WHERE clause can be factored into terms and that one or
1358more of those terms will involve only columns in the first table.
1359When this happens, we can factor part of the WHERE clause test out of
1360the inner loop and gain a lot of efficiency. So a better template
1361would be something like this:</p>
1362
1363<p>
1364<ol>
1365<li>Initialize the <b>azColumnName[]</b> array for the callback.</li>
1366<li>Open two cursors, one to each of the two tables being queried.</li>
1367<li>For each record in the first table, do:
1368 <ol type="a">
1369 <li>Evaluate terms of the WHERE clause that only involve columns from
1370 the first table. If any term is false (meaning that the whole
1371 WHERE clause must be false) then skip the rest of this loop and
1372 continue to the next record.</li>
1373 <li>For each record in the second table do:
1374 <ol type="i">
1375 <li>If the WHERE clause evaluates to FALSE, then skip the steps that
1376 follow and continue to the next record.</li>
1377 <li>Compute all columns for the current row of the result.</li>
1378 <li>Invoke the callback function for the current row of the result.</li>
1379 </ol></li>
1380 </ol>
1381<li>Close both cursors.</li>
1382</ol>
1383</p>
1384
1385<p>Additional speed-up can occur if an index can be used to speed
1386the search of either or the two loops.</p>
1387
1388<p>SQLite always constructs the loops in the same order as the
1389tables appear in the FROM clause of the SELECT statement. The
1390left-most table becomes the outer loop and the right-most table
1391becomes the inner loop. It is possible, in theory, to reorder
1392the loops in some circumstances to speed the evaluation of the
1393join. But SQLite does not attempt this optimization.</p>
1394
1395<p>You can see how SQLite constructs nested loops in the following
1396example:</p>
1397
1398<blockquote><pre>
1399CREATE TABLE examp2(three int, four int);
1400SELECT * FROM examp, examp2 WHERE two<50 AND four==two;
1401</pre></blockquote>
1402}
1403
1404Code {
1405addr opcode p1 p2 p3
1406---- ------------ ----- ----- -----------------------------------
14070 ColumnName 0 0 examp.one
14081 ColumnName 1 0 examp.two
14092 ColumnName 2 0 examp2.three
14103 ColumnName 3 0 examp2.four
14114 Integer 0 0
14125 OpenRead 0 3 examp
14136 VerifyCookie 0 909
14147 Integer 0 0
14158 OpenRead 1 5 examp2
14169 Rewind 0 24
141710 Column 0 1
141811 Integer 50 0 50
141912 Ge 1 23
142013 Rewind 1 23
142114 Column 1 1
142215 Column 0 1
142316 Ne 1 22
142417 Column 0 0
142518 Column 0 1
142619 Column 1 0
142720 Column 1 1
142821 Callback 4 0
142922 Next 1 14
143023 Next 0 10
143124 Close 0 0
143225 Close 1 0
143326 Halt 0 0
1434}
1435
1436puts {
1437<p>The outer loop over table examp is implement by instructions
14387 through 23. The inner loop is instructions 13 through 22.
1439Notice that the "two<50" term of the WHERE expression involves
1440only columns from the first table and can be factored out of
1441the inner loop. SQLite does this and implements the "two<50"
1442test in instructions 10 through 12. The "four==two" test is
1443implement by instructions 14 through 16 in the inner loop.</p>
1444
1445<p>SQLite does not impose any arbitrary limits on the tables in
1446a join. It also allows a table to be joined with itself.</p>
1447
1448<h2>The ORDER BY clause</h2>
1449
1450<p>For historical reasons, and for efficiency, all sorting is currently
1451done in memory.</p>
1452
1453<p>SQLite implements the ORDER BY clause using a special
1454set of instructions to control an object called a sorter. In the
1455inner-most loop of the query, where there would normally be
1456a Callback instruction, instead a record is constructed that
1457contains both callback parameters and a key. This record
1458is added to the sorter (in a linked list). After the query loop
1459finishes, the list of records is sorted and this list is walked. For
1460each record on the list, the callback is invoked. Finally, the sorter
1461is closed and memory is deallocated.</p>
1462
1463<p>We can see the process in action in the following query:</p>
1464
1465<blockquote><pre>
1466SELECT * FROM examp ORDER BY one DESC, two;
1467</pre></blockquote>
1468}
1469
1470Code {
1471addr opcode p1 p2 p3
1472---- ------------ ----- ----- -----------------------------------
14730 ColumnName 0 0 one
14741 ColumnName 1 0 two
14752 Integer 0 0
14763 OpenRead 0 3 examp
14774 VerifyCookie 0 909
14785 Rewind 0 14
14796 Column 0 0
14807 Column 0 1
14818 SortMakeRec 2 0
14829 Column 0 0
148310 Column 0 1
148411 SortMakeKey 2 0 D+
148512 SortPut 0 0
148613 Next 0 6
148714 Close 0 0
148815 Sort 0 0
148916 SortNext 0 19
149017 SortCallback 2 0
149118 Goto 0 16
149219 SortReset 0 0
149320 Halt 0 0
1494}
1495
1496puts {
1497<p>There is only one sorter object, so there are no instructions to open
1498or close it. It is opened automatically when needed, and it is closed
1499when the VDBE program halts.</p>
1500
1501<p>The query loop is built from instructions 5 through 13. Instructions
15026 through 8 build a record that contains the azData[] values for a single
1503invocation of the callback. A sort key is generated by instructions
15049 through 11. Instruction 12 combines the invocation record and the
1505sort key into a single entry and puts that entry on the sort list.<p>
1506
1507<p>The P3 argument of instruction 11 is of particular interest. The
1508sort key is formed by prepending one character from P3 to each string
1509and concatenating all the strings. The sort comparison function will
1510look at this character to determine whether the sort order is
1511ascending or descending, and whether to sort as a string or number.
1512In this example, the first column should be sorted as a string
1513in descending order so its prefix is "D" and the second column should
1514sorted numerically in ascending order so its prefix is "+". Ascending
1515string sorting uses "A", and descending numeric sorting uses "-".</p>
1516
1517<p>After the query loop ends, the table being queried is closed at
1518instruction 14. This is done early in order to allow other processes
1519or threads to access that table, if desired. The list of records
1520that was built up inside the query loop is sorted by the instruction
1521at 15. Instructions 16 through 18 walk through the record list
1522(which is now in sorted order) and invoke the callback once for
1523each record. Finally, the sorter is closed at instruction 19.</p>
1524
1525<h2>Aggregate Functions And The GROUP BY and HAVING Clauses</h2>
1526
1527<p>To compute aggregate functions, the VDBE implements a special
1528data structure and instructions for controlling that data structure.
1529The data structure is an unordered set of buckets, where each bucket
1530has a key and one or more memory locations. Within the query
1531loop, the GROUP BY clause is used to construct a key and the bucket
1532with that key is brought into focus. A new bucket is created with
1533the key if one did not previously exist. Once the bucket is in
1534focus, the memory locations of the bucket are used to accumulate
1535the values of the various aggregate functions. After the query
1536loop terminates, each bucket is visited once to generate a
1537single row of the results.</p>
1538
1539<p>An example will help to clarify this concept. Consider the
1540following query:</p>
1541
1542<blockquote><pre>
1543SELECT three, min(three+four)+avg(four)
1544FROM examp2
1545GROUP BY three;
1546</pre></blockquote>
1547
1548
1549<p>The VDBE code generated for this query is as follows:</p>
1550}
1551
1552Code {
1553addr opcode p1 p2 p3
1554---- ------------ ----- ----- -----------------------------------
15550 ColumnName 0 0 three
15561 ColumnName 1 0 min(three+four)+avg(four)
15572 AggReset 0 3
15583 AggInit 0 1 ptr(0x7903a0)
15594 AggInit 0 2 ptr(0x790700)
15605 Integer 0 0
15616 OpenRead 0 5 examp2
15627 VerifyCookie 0 909
15638 Rewind 0 23
15649 Column 0 0
156510 MakeKey 1 0 n
156611 AggFocus 0 14
156712 Column 0 0
156813 AggSet 0 0
156914 Column 0 0
157015 Column 0 1
157116 Add 0 0
157217 Integer 1 0
157318 AggFunc 0 1 ptr(0x7903a0)
157419 Column 0 1
157520 Integer 2 0
157621 AggFunc 0 1 ptr(0x790700)
157722 Next 0 9
157823 Close 0 0
157924 AggNext 0 31
158025 AggGet 0 0
158126 AggGet 0 1
158227 AggGet 0 2
158328 Add 0 0
158429 Callback 2 0
158530 Goto 0 24
158631 Noop 0 0
158732 Halt 0 0
1588}
1589
1590puts {
1591<p>The first instruction of interest is the
1592<a href="opcode.html#AggReset">AggReset</a> at 2.
1593The AggReset instruction initializes the set of buckets to be the
1594empty set and specifies the number of memory slots available in each
1595bucket as P2. In this example, each bucket will hold 3 memory slots.
1596It is not obvious, but if you look closely at the rest of the program
1597you can figure out what each of these slots is intended for.</p>
1598
1599<blockquote><table border="2" cellpadding="5">
1600<tr><th>Memory Slot</th><th>Intended Use Of This Memory Slot</th></tr>
1601<tr><td>0</td><td>The "three" column -- the key to the bucket</td></tr>
1602<tr><td>1</td><td>The minimum "three+four" value</td></tr>
1603<tr><td>2</td><td>The sum of all "four" values. This is used to compute
1604 "avg(four)".</td></tr>
1605</table></blockquote>
1606
1607<p>The query loop is implemented by instructions 8 through 22.
1608The aggregate key specified by the GROUP BY clause is computed
1609by instructions 9 and 10. Instruction 11 causes the appropriate
1610bucket to come into focus. If a bucket with the given key does
1611not already exists, a new bucket is created and control falls
1612through to instructions 12 and 13 which initialize the bucket.
1613If the bucket does already exist, then a jump is made to instruction
161414. The values of aggregate functions are updated by the instructions
1615between 11 and 21. Instructions 14 through 18 update memory
1616slot 1 to hold the next value "min(three+four)". Then the sum of the
1617"four" column is updated by instructions 19 through 21.</p>
1618
1619<p>After the query loop is finished, the table "examp2" is closed at
1620instruction 23 so that its lock will be released and it can be
1621used by other threads or processes. The next step is to loop
1622over all aggregate buckets and output one row of the result for
1623each bucket. This is done by the loop at instructions 24
1624through 30. The AggNext instruction at 24 brings the next bucket
1625into focus, or jumps to the end of the loop if all buckets have
1626been examined already. The 3 columns of the result are fetched from
1627the aggregator bucket in order at instructions 25 through 27.
1628Finally, the callback is invoked at instruction 29.</p>
1629
1630<p>In summary then, any query with aggregate functions is implemented
1631by two loops. The first loop scans the input table and computes
1632aggregate information into buckets and the second loop scans through
1633all the buckets to compute the final result.</p>
1634
1635<p>The realization that an aggregate query is really two consequtive
1636loops makes it much easier to understand the difference between
1637a WHERE clause and a HAVING clause in SQL query statement. The
1638WHERE clause is a restriction on the first loop and the HAVING
1639clause is a restriction on the second loop. You can see this
1640by adding both a WHERE and a HAVING clause to our example query:</p>
1641
1642
1643<blockquote><pre>
1644SELECT three, min(three+four)+avg(four)
1645FROM examp2
1646WHERE three>four
1647GROUP BY three
1648HAVING avg(four)<10;
1649</pre></blockquote>
1650}
1651
1652Code {
1653addr opcode p1 p2 p3
1654---- ------------ ----- ----- -----------------------------------
16550 ColumnName 0 0 three
16561 ColumnName 1 0 min(three+four)+avg(four)
16572 AggReset 0 3
16583 AggInit 0 1 ptr(0x7903a0)
16594 AggInit 0 2 ptr(0x790700)
16605 Integer 0 0
16616 OpenRead 0 5 examp2
16627 VerifyCookie 0 909
16638 Rewind 0 26
16649 Column 0 0
166510 Column 0 1
166611 Le 1 25
166712 Column 0 0
166813 MakeKey 1 0 n
166914 AggFocus 0 17
167015 Column 0 0
167116 AggSet 0 0
167217 Column 0 0
167318 Column 0 1
167419 Add 0 0
167520 Integer 1 0
167621 AggFunc 0 1 ptr(0x7903a0)
167722 Column 0 1
167823 Integer 2 0
167924 AggFunc 0 1 ptr(0x790700)
168025 Next 0 9
168126 Close 0 0
168227 AggNext 0 37
168328 AggGet 0 2
168429 Integer 10 0 10
168530 Ge 1 27
168631 AggGet 0 0
168732 AggGet 0 1
168833 AggGet 0 2
168934 Add 0 0
169035 Callback 2 0
169136 Goto 0 27
169237 Noop 0 0
169338 Halt 0 0
1694}
1695
1696puts {
1697<p>The code generated in this last example is the same as the
1698previous except for the addition of two conditional jumps used
1699to implement the extra WHERE and HAVING clauses. The WHERE
1700clause is implemented by instructions 9 through 11 in the query
1701loop. The HAVING clause is implemented by instruction 28 through
170230 in the output loop.</p>
1703
1704<h2>Using SELECT Statements As Terms In An Expression</h2>
1705
1706<p>The very name "Structured Query Language" tells us that SQL should
1707support nested queries. And, in fact, two different kinds of nesting
1708are supported. Any SELECT statement that returns a single-row, single-column
1709result can be used as a term in an expression of another SELECT statement.
1710And, a SELECT statement that returns a single-column, multi-row result
1711can be used as the right-hand operand of the IN and NOT IN operators.
1712We will begin this section with an example of the first kind of nesting,
1713where a single-row, single-column SELECT is used as a term in an expression
1714of another SELECT. Here is our example:</p>
1715
1716<blockquote><pre>
1717SELECT * FROM examp
1718WHERE two!=(SELECT three FROM examp2
1719 WHERE four=5);
1720</pre></blockquote>
1721
1722<p>The way SQLite deals with this is to first run the inner SELECT
1723(the one against examp2) and store its result in a private memory
1724cell. SQLite then substitutes the value of this private memory
1725cell for the inner SELECT when it evaluates the outer SELECT.
1726The code looks like this:</p>
1727}
1728
1729Code {
1730addr opcode p1 p2 p3
1731---- ------------ ----- ----- -----------------------------------
17320 String 0 0
17331 MemStore 0 1
17342 Integer 0 0
17353 OpenRead 1 5 examp2
17364 VerifyCookie 0 909
17375 Rewind 1 13
17386 Column 1 1
17397 Integer 5 0 5
17408 Ne 1 12
17419 Column 1 0
174210 MemStore 0 1
174311 Goto 0 13
174412 Next 1 6
174513 Close 1 0
174614 ColumnName 0 0 one
174715 ColumnName 1 0 two
174816 Integer 0 0
174917 OpenRead 0 3 examp
175018 Rewind 0 26
175119 Column 0 1
175220 MemLoad 0 0
175321 Eq 1 25
175422 Column 0 0
175523 Column 0 1
175624 Callback 2 0
175725 Next 0 19
175826 Close 0 0
175927 Halt 0 0
1760}
1761
1762puts {
1763<p>The private memory cell is initialized to NULL by the first
1764two instructions. Instructions 2 through 13 implement the inner
1765SELECT statement against the examp2 table. Notice that instead of
1766sending the result to a callback or storing the result on a sorter,
1767the result of the query is pushed into the memory cell by instruction
176810 and the loop is abandoned by the jump at instruction 11.
1769The jump at instruction at 11 is vestigial and never executes.</p>
1770
1771<p>The outer SELECT is implemented by instructions 14 through 25.
1772In particular, the WHERE clause that contains the nested select
1773is implemented by instructions 19 through 21. You can see that
1774the result of the inner select is loaded onto the stack by instruction
177520 and used by the conditional jump at 21.</p>
1776
1777<p>When the result of a sub-select is a scalar, a single private memory
1778cell can be used, as shown in the previous
1779example. But when the result of a sub-select is a vector, such
1780as when the sub-select is the right-hand operand of IN or NOT IN,
1781a different approach is needed. In this case,
1782the result of the sub-select is
1783stored in a transient table and the contents of that table
1784are tested using the Found or NotFound operators. Consider this
1785example:</p>
1786
1787<blockquote><pre>
1788SELECT * FROM examp
1789WHERE two IN (SELECT three FROM examp2);
1790</pre></blockquote>
1791
1792<p>The code generated to implement this last query is as follows:</p>
1793}
1794
1795Code {
1796addr opcode p1 p2 p3
1797---- ------------ ----- ----- -----------------------------------
17980 OpenTemp 1 1
17991 Integer 0 0
18002 OpenRead 2 5 examp2
18013 VerifyCookie 0 909
18024 Rewind 2 10
18035 Column 2 0
18046 IsNull -1 9
18057 String 0 0
18068 PutStrKey 1 0
18079 Next 2 5
180810 Close 2 0
180911 ColumnName 0 0 one
181012 ColumnName 1 0 two
181113 Integer 0 0
181214 OpenRead 0 3 examp
181315 Rewind 0 25
181416 Column 0 1
181517 NotNull -1 20
181618 Pop 1 0
181719 Goto 0 24
181820 NotFound 1 24
181921 Column 0 0
182022 Column 0 1
182123 Callback 2 0
182224 Next 0 16
182325 Close 0 0
182426 Halt 0 0
1825}
1826
1827puts {
1828<p>The transient table in which the results of the inner SELECT are
1829stored is created by the <a href="opcode.html#OpenTemp">OpenTemp</a>
1830instruction at 0. This opcode is used for tables that exist for the
1831duration of a single SQL statement only. The transient cursor is always
1832opened read/write even if the main database is read-only. The transient
1833table is deleted automatically when the cursor is closed. The P2 value
1834of 1 means the cursor points to a BTree index, which has no data but can
1835have an arbitrary key.</p>
1836
1837<p>The inner SELECT statement is implemented by instructions 1 through 10.
1838All this code does is make an entry in the temporary table for each
1839row of the examp2 table with a non-NULL value for the "three" column.
1840The key for each temporary table entry is the "three" column of examp2
1841and the data is an empty string since it is never used.</p>
1842
1843<p>The outer SELECT is implemented by instructions 11 through 25. In
1844particular, the WHERE clause containing the IN operator is implemented
1845by instructions at 16, 17, and 20. Instruction 16 pushes the value of
1846the "two" column for the current row onto the stack and instruction 17
1847checks to see that it is non-NULL. If this is successful, execution
1848jumps to 20, where it tests to see if top of the stack matches any key
1849in the temporary table. The rest of the code is the same as what has
1850been shown before.</p>
1851
1852<h2>Compound SELECT Statements</h2>
1853
1854<p>SQLite also allows two or more SELECT statements to be joined as
1855peers using operators UNION, UNION ALL, INTERSECT, and EXCEPT. These
1856compound select statements are implemented using transient tables.
1857The implementation is slightly different for each operator, but the
1858basic ideas are the same. For an example we will use the EXCEPT
1859operator.</p>
1860
1861<blockquote><pre>
1862SELECT two FROM examp
1863EXCEPT
1864SELECT four FROM examp2;
1865</pre></blockquote>
1866
1867<p>The result of this last example should be every unique value
1868of the "two" column in the examp table, except any value that is
1869in the "four" column of examp2 is removed. The code to implement
1870this query is as follows:</p>
1871}
1872
1873Code {
1874addr opcode p1 p2 p3
1875---- ------------ ----- ----- -----------------------------------
18760 OpenTemp 0 1
18771 KeyAsData 0 1
18782 Integer 0 0
18793 OpenRead 1 3 examp
18804 VerifyCookie 0 909
18815 Rewind 1 11
18826 Column 1 1
18837 MakeRecord 1 0
18848 String 0 0
18859 PutStrKey 0 0
188610 Next 1 6
188711 Close 1 0
188812 Integer 0 0
188913 OpenRead 2 5 examp2
189014 Rewind 2 20
189115 Column 2 1
189216 MakeRecord 1 0
189317 NotFound 0 19
189418 Delete 0 0
189519 Next 2 15
189620 Close 2 0
189721 ColumnName 0 0 four
189822 Rewind 0 26
189923 Column 0 0
190024 Callback 1 0
190125 Next 0 23
190226 Close 0 0
190327 Halt 0 0
1904}
1905
1906puts {
1907<p>The transient table in which the result is built is created by
1908instruction 0. Three loops then follow. The loop at instructions
19095 through 10 implements the first SELECT statement. The second
1910SELECT statement is implemented by the loop at instructions 14 through
191119. Finally, a loop at instructions 22 through 25 reads the transient
1912table and invokes the callback once for each row in the result.</p>
1913
1914<p>Instruction 1 is of particular importance in this example. Normally,
1915the Column instruction extracts the value of a column from a larger
1916record in the data of an SQLite file entry. Instruction 1 sets a flag on
1917the transient table so that Column will instead treat the key of the
1918SQLite file entry as if it were data and extract column information from
1919the key.</p>
1920
1921<p>Here is what is going to happen: The first SELECT statement
1922will construct rows of the result and save each row as the key of
1923an entry in the transient table. The data for each entry in the
1924transient table is a never used so we fill it in with an empty string.
1925The second SELECT statement also constructs rows, but the rows
1926constructed by the second SELECT are removed from the transient table.
1927That is why we want the rows to be stored in the key of the SQLite file
1928instead of in the data -- so they can be easily located and deleted.</p>
1929
1930<p>Let's look more closely at what is happening here. The first
1931SELECT is implemented by the loop at instructions 5 through 10.
1932Instruction 5 intializes the loop by rewinding its cursor.
1933Instruction 6 extracts the value of the "two" column from "examp"
1934and instruction 7 converts this into a row. Instruction 8 pushes
1935an empty string onto the stack. Finally, instruction 9 writes the
1936row into the temporary table. But remember, the PutStrKey opcode uses
1937the top of the stack as the record data and the next on stack as the
1938key. For an INSERT statement, the row generated by the
1939MakeRecord opcode is the record data and the record key is an integer
1940created by the NewRecno opcode. But here the roles are reversed and
1941the row created by MakeRecord is the record key and the record data is
1942just an empty string.</p>
1943
1944<p>The second SELECT is implemented by instructions 14 through 19.
1945Instruction 14 intializes the loop by rewinding its cursor.
1946A new result row is created from the "four" column of table "examp2"
1947by instructions 15 and 16. But instead of using PutStrKey to write this
1948new row into the temporary table, we instead call Delete to remove
1949it from the temporary table if it exists.</p>
1950
1951<p>The result of the compound select is sent to the callback routine
1952by the loop at instructions 22 through 25. There is nothing new
1953or remarkable about this loop, except for the fact that the Column
1954instruction at 23 will be extracting a column out of the record key
1955rather than the record data.</p>
1956
1957<h2>Summary</h2>
1958
1959<p>This article has reviewed all of the major techniques used by
1960SQLite's VDBE to implement SQL statements. What has not been shown
1961is that most of these techniques can be used in combination to
1962generate code for an appropriately complex query statement. For
1963example, we have shown how sorting is accomplished on a simple query
1964and we have shown how to implement a compound query. But we did
1965not give an example of sorting in a compound query. This is because
1966sorting a compound query does not introduce any new concepts: it
1967merely combines two previous ideas (sorting and compounding)
1968in the same VDBE program.</p>
1969
1970<p>For additional information on how the SQLite library
1971functions, the reader is directed to look at the SQLite source
1972code directly. If you understand the material in this article,
1973you should not have much difficulty in following the sources.
1974Serious students of the internals of SQLite will probably
1975also what to make a careful study of the VDBE opcodes
1976as documented <a href="opcode.html">here</a>. Most of the
1977opcode documentation is extracted from comments in the source
1978code using a script so you can also get information about the
1979various opcodes directly from the <b>vdbe.c</b> source file.
1980If you have successfully read this far, you should have little
1981difficulty understanding the rest.</p>
1982
1983<p>If you find errors in either the documentation or the code,
1984feel free to fix them and/or contact the author at
1985<a href="mailto:drh@hwaci.com">drh@hwaci.com</a>. Your bug fixes or
1986suggestions are always welcomed.</p>
1987}
1988footer $rcsid
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/version3.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/version3.tcl
deleted file mode 100644
index 70e500d..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/version3.tcl
+++ /dev/null
@@ -1,293 +0,0 @@
1#!/usr/bin/tclsh
2source common.tcl
3header {SQLite Version 3 Overview}
4puts {
5<h2>SQLite Version 3 Overview</h2>
6
7<p>
8SQLite version 3.0 introduces important changes to the library, including:
9</p>
10
11<ul>
12<li>A more compact format for database files.</li>
13<li>Manifest typing and BLOB support.</li>
14<li>Support for both UTF-8 and UTF-16 text.</li>
15<li>User-defined text collating sequences.</li>
16<li>64-bit ROWIDs.</li>
17<li>Improved Concurrency.</li>
18</ul>
19
20<p>
21This document is a quick introduction to the changes for SQLite 3.0
22for users who are already familiar with SQLite version 2.8.
23</p>
24
25<h3>Naming Changes</h3>
26
27<p>
28SQLite version 2.8 will continue to be supported with bug fixes
29for the foreseeable future. In order to allow SQLite version 2.8
30and SQLite version 3.0 to peacefully coexist, the names of key files
31and APIs in SQLite version 3.0 have been changed to include the
32character "3". For example, the include file used by C programs
33has been changed from "sqlite.h" to "sqlite3.h". And the name of
34the shell program used to interact with databases has been changed
35from "sqlite.exe" to "sqlite3.exe". With these changes, it is possible
36to have both SQLite 2.8 and SQLite 3.0 installed on the same system at
37the same time. And it is possible for the same C program to link
38against both SQLite 2.8 and SQLite 3.0 at the same time and to use
39both libraries at the same time.
40</p>
41
42<h3>New File Format</h3>
43
44<p>
45The format used by SQLite database files has been completely revised.
46The old version 2.1 format and the new 3.0 format are incompatible with
47one another. Version 2.8 of SQLite will not read a version 3.0 database
48files and version 3.0 of SQLite will not read a version 2.8 database file.
49</p>
50
51<p>
52To convert an SQLite 2.8 database into an SQLite 3.0 database, have
53ready the command-line shells for both version 2.8 and 3.0. Then
54enter a command like the following:
55</p>
56
57<blockquote><pre>
58sqlite OLD.DB .dump | sqlite3 NEW.DB
59</pre></blockquote>
60
61<p>
62The new database file format uses B+trees for tables. In a B+tree, all
63data is stored in the leaves of the tree instead of in both the leaves and
64the intermediate branch nodes. The use of B+trees for tables allows for
65better scalability and the storage of larger data fields without the use of
66overflow pages. Traditional B-trees are still used for indices.</p>
67
68<p>
69The new file format also supports variable pages sizes between 512 and
7032768 bytes. The size of a page is stored in the file header so the
71same library can read databases with different pages sizes, in theory,
72though this feature has not yet been implemented in practice.
73</p>
74
75<p>
76The new file format omits unused fields from its disk images. For example,
77indices use only the key part of a B-tree record and not the data. So
78for indices, the field that records the length of the data is omitted.
79Integer values such as the length of key and data are stored using
80a variable-length encoding so that only one or two bytes are required to
81store the most common cases but up to 64-bits of information can be encoded
82if needed.
83Integer and floating point data is stored on the disk in binary rather
84than being converted into ASCII as in SQLite version 2.8.
85These changes taken together result in database files that are typically
8625% to 35% smaller than the equivalent files in SQLite version 2.8.
87</p>
88
89<p>
90Details of the low-level B-tree format used in SQLite version 3.0 can
91be found in header comments to the
92<a href="http://www.sqlite.org/cvstrac/getfile/sqlite/src/btree.c">btree.c</a>
93source file.
94</p>
95
96<h3>Manifest Typing and BLOB Support</h3>
97
98<p>
99SQLite version 2.8 will deal with data in various formats internally,
100but when writing to the disk or interacting through its API, SQLite 2.8
101always converts data into ASCII text. SQLite 3.0, in contrast, exposes
102its internal data representations to the user and stores binary representations
103to disk when appropriate. The exposing of non-ASCII representations was
104added in order to support BLOBs.
105</p>
106
107<p>
108SQLite version 2.8 had the feature that any type of data could be stored
109in any table column regardless of the declared type of that column. This
110feature is retained in version 3.0, though in a slightly modified form.
111Each table column will store any type of data, though columns have an
112affinity for the format of data defined by their declared datatype.
113When data is inserted into a column, that column will make at attempt
114to convert the data format into the columns declared type. All SQL
115database engines do this. The difference is that SQLite 3.0 will
116still store the data even if a format conversion is not possible.
117</p>
118
119<p>
120For example, if you have a table column declared to be of type "INTEGER"
121and you try to insert a string, the column will look at the text string
122and see if it looks like a number. If the string does look like a number
123it is converted into a number and into an integer if the number does not
124have a fractional part, and stored that way. But if the string is not
125a well-formed number it is still stored as a string. A column with a
126type of "TEXT" tries to convert numbers into an ASCII-Text representation
127before storing them. But BLOBs are stored in TEXT columns as BLOBs because
128you cannot in general convert a BLOB into text.
129</p>
130
131<p>
132In most other SQL database engines the datatype is associated with
133the table column that holds the data - with the data container.
134In SQLite 3.0, the datatype is associated with the data itself, not
135with its container.
136<a href="http://www.paulgraham.com/">Paul Graham</a> in his book
137<a href="http://www.paulgraham.com/acl.html"><i>ANSI Common Lisp</i></a>
138calls this property "Manifest Typing".
139Other writers have other definitions for the term "manifest typing",
140so beware of confusion. But by whatever name, that is the datatype
141model supported by SQLite 3.0.
142</p>
143
144<p>
145Additional information about datatypes in SQLite version 3.0 is
146available
147<a href="datatype3.html">separately</a>.
148</p>
149
150<h3>Support for UTF-8 and UTF-16</h3>
151
152<p>
153The new API for SQLite 3.0 contains routines that accept text as
154both UTF-8 and UTF-16 in the native byte order of the host machine.
155Each database file manages text as either UTF-8, UTF-16BE (big-endian),
156or UTF-16LE (little-endian). Internally and in the disk file, the
157same text representation is used everywhere. If the text representation
158specified by the database file (in the file header) does not match
159the text representation required by the interface routines, then text
160is converted on-the-fly.
161Constantly converting text from one representation to another can be
162computationally expensive, so it is suggested that programmers choose a
163single representation and stick with it throughout their application.
164</p>
165
166<p>
167In the current implementation of SQLite, the SQL parser only works
168with UTF-8 text. So if you supply UTF-16 text it will be converted.
169This is just an implementation issue and there is nothing to prevent
170future versions of SQLite from parsing UTF-16 encoded SQL natively.
171</p>
172
173<p>
174When creating new user-defined SQL functions and collating sequences,
175each function or collating sequence can specify it if works with
176UTF-8, UTF-16be, or UTF-16le. Separate implementations can be registered
177for each encoding. If an SQL function or collating sequences is required
178but a version for the current text encoding is not available, then
179the text is automatically converted. As before, this conversion takes
180computation time, so programmers are advised to pick a single
181encoding and stick with it in order to minimize the amount of unnecessary
182format juggling.
183</p>
184
185<p>
186SQLite is not particular about the text it receives and is more than
187happy to process text strings that are not normalized or even
188well-formed UTF-8 or UTF-16. Thus, programmers who want to store
189IS08859 data can do so using the UTF-8 interfaces. As long as no
190attempts are made to use a UTF-16 collating sequence or SQL function,
191the byte sequence of the text will not be modified in any way.
192</p>
193
194<h3>User-defined Collating Sequences</h3>
195
196<p>
197A collating sequence is just a defined order for text. When SQLite 3.0
198sorts (or uses a comparison operator like "<" or ">=") the sort order
199is first determined by the data type.
200</p>
201
202<ul>
203<li>NULLs sort first</li>
204<li>Numeric values sort next in numerical order</li>
205<li>Text values come after numerics</li>
206<li>BLOBs sort last</li>
207</ul>
208
209<p>
210Collating sequences are used for comparing two text strings.
211The collating sequence does not change the ordering of NULLs, numbers,
212or BLOBs, only text.
213</p>
214
215<p>
216A collating sequence is implemented as a function that takes the
217two strings being compared as inputs and returns negative, zero, or
218positive if the first string is less than, equal to, or greater than
219the second.
220SQLite 3.0 comes with a single built-in collating sequence named "BINARY"
221which is implemented using the memcmp() routine from the standard C library.
222The BINARY collating sequence works well for English text. For other
223languages or locales, alternative collating sequences may be preferred.
224</p>
225
226<p>
227The decision of which collating sequence to use is controlled by the
228COLLATE clause in SQL. A COLLATE clause can occur on a table definition,
229to define a default collating sequence to a table column, or on field
230of an index, or in the ORDER BY clause of a SELECT statement.
231Planned enhancements to SQLite are to include standard CAST() syntax
232to allow the collating sequence of an expression to be defined.
233</p>
234
235<h3>64-bit ROWIDs</h3>
236
237<p>
238Every row of a table has a unique rowid.
239If the table defines a column with the type "INTEGER PRIMARY KEY" then that
240column becomes an alias for the rowid. But with or without an INTEGER PRIMARY
241KEY column, every row still has a rowid.
242</p>
243
244<p>
245In SQLite version 3.0, the rowid is a 64-bit signed integer.
246This is an expansion of SQLite version 2.8 which only permitted
247rowids of 32-bits.
248</p>
249
250<p>
251To minimize storage space, the 64-bit rowid is stored as a variable length
252integer. Rowids between 0 and 127 use only a single byte.
253Rowids between 0 and 16383 use just 2 bytes. Up to 2097152 uses three
254bytes. And so forth. Negative rowids are allowed but they always use
255nine bytes of storage and so their use is discouraged. When rowids
256are generated automatically by SQLite, they will always be non-negative.
257</p>
258
259<h3>Improved Concurrency</h3>
260
261<p>
262SQLite version 2.8 allowed multiple simultaneous readers or a single
263writer but not both. SQLite version 3.0 allows one process to begin
264writing the database while other processes continue to read. The
265writer must still obtain an exclusive lock on the database for a brief
266interval in order to commit its changes, but the exclusive lock is no
267longer required for the entire write operation.
268A <a href="lockingv3.html">more detailed report</a> on the locking
269behavior of SQLite version 3.0 is available separately.
270</p>
271
272<p>
273A limited form of table-level locking is now also available in SQLite.
274If each table is stored in a separate database file, those separate
275files can be attached to the main database (using the ATTACH command)
276and the combined databases will function as one. But locks will only
277be acquired on individual files as needed. So if you redefine "database"
278to mean two or more database files, then it is entirely possible for
279two processes to be writing to the same database at the same time.
280To further support this capability, commits of transactions involving
281two or more ATTACHed database are now atomic.
282</p>
283
284<h3>Credits</h3>
285
286<p>
287SQLite version 3.0 is made possible in part by AOL developers
288supporting and embracing great Open-Source Software.
289</p>
290
291
292}
293footer {$Id: version3.tcl,v 1.6 2006/03/03 21:39:54 drh Exp $}
diff --git a/libraries/sqlite/unix/sqlite-3.5.1/www/whentouse.tcl b/libraries/sqlite/unix/sqlite-3.5.1/www/whentouse.tcl
deleted file mode 100644
index bb4378b..0000000
--- a/libraries/sqlite/unix/sqlite-3.5.1/www/whentouse.tcl
+++ /dev/null
@@ -1,254 +0,0 @@
1#
2# Run this TCL script to generate HTML for the goals.html file.
3#
4set rcsid {$Id: whentouse.tcl,v 1.7 2007/04/14 12:04:39 drh Exp $}
5source common.tcl
6header {Appropriate Uses For SQLite}
7
8puts {
9<p>
10SQLite is different from most other SQL database engines in that its
11primary design goal is to be simple:
12</p>
13
14<ul>
15<li>Simple to administer</li>
16<li>Simple to operate</li>
17<li>Simple to embed in a larger program</li>
18<li>Simple to maintain and customize</li>
19</ul>
20
21<p>
22Many people like SQLite because it is small and fast. But those
23qualities are just happy accidents.
24Users also find that SQLite is very reliable. Reliability is
25a consequence of simplicity. With less complication, there is
26less to go wrong. So, yes, SQLite is small, fast, and reliable,
27but first and foremost, SQLite strives to be simple.
28</p>
29
30<p>
31Simplicity in a database engine can be either a strength or a
32weakness, depending on what you are trying to do. In order to
33achieve simplicity, SQLite has had to sacrifice other characteristics
34that some people find useful, such as high concurrency, fine-grained
35access control, a rich set of built-in functions, stored procedures,
36esoteric SQL language features, XML and/or Java extensions,
37tera- or peta-byte scalability, and so forth. If you need some of these
38features and do not mind the added complexity that they
39bring, then SQLite is probably not the database for you.
40SQLite is not intended to be an enterprise database engine. It
41not designed to compete with Oracle or PostgreSQL.
42</p>
43
44<p>
45The basic rule of thumb for when it is appropriate to use SQLite is
46this: Use SQLite in situations where simplicity of administration,
47implementation, and maintenance are more important than the countless
48complex features that enterprise database engines provide.
49As it turns out, situations where simplicity is the better choice
50are more common than many people realize.
51</p>
52
53<h2>Situations Where SQLite Works Well</h2>
54
55<ul>
56<li><p><b>Websites</b></p>
57
58<p>SQLite usually will work great as the database engine for low to
59medium traffic websites (which is to say, 99.9% of all websites).
60The amount of web traffic that SQLite can handle depends, of course,
61on how heavily the website uses its database. Generally
62speaking, any site that gets fewer than a 100000 hits/day should work
63fine with SQLite.
64The 100000 hits/day figure is a conservative estimate, not a
65hard upper bound.
66SQLite has been demonstrated to work with 10 times that amount
67of traffic.</p>
68</li>
69
70<li><p><b>Embedded devices and applications</b></p>
71
72<p>Because an SQLite database requires little or no administration,
73SQLite is a good choice for devices or services that must work
74unattended and without human support. SQLite is a good fit for
75use in cellphones, PDAs, set-top boxes, and/or appliances. It also
76works well as an embedded database in downloadable consumer applications.
77</p>
78</li>
79
80<li><p><b>Application File Format</b></p>
81
82<p>
83SQLite has been used with great success as the on-disk file format
84for desktop applications such as financial analysis tools, CAD
85packages, record keeping programs, and so forth. The traditional
86File/Open operation does an sqlite3_open() and executes a
87BEGIN TRANSACTION to get exclusive access to the content. File/Save
88does a COMMIT followed by another BEGIN TRANSACTION. The use
89of transactions guarantees that updates to the application file are atomic,
90durable, isolated, and consistent.
91</p>
92
93<p>
94Temporary triggers can be added to the database to record all
95changes into a (temporary) undo/redo log table. These changes can then
96be played back when the user presses the Undo and Redo buttons. Using
97this technique, a unlimited depth undo/redo implementation can be written
98in surprising little code.
99</p>
100</li>
101
102<li><p><b>Replacement for <i>ad hoc</i> disk files</b></p>
103
104<p>Many programs use fopen(), fread(), and fwrite() to create and
105manage files of data in home-grown formats. SQLite works
106particularly well as a
107replacement for these <i>ad hoc</i> data files.</p>
108</li>
109
110<li><p><b>Internal or temporary databases</b></p>
111
112<p>
113For programs that have a lot of data that must be sifted and sorted
114in diverse ways, it is often easier and quicker to load the data into
115an in-memory SQLite database and use queries with joins and ORDER BY
116clauses to extract the data in the form and order needed rather than
117to try to code the same operations manually.
118Using an SQL database internally in this way also gives the program
119greater flexibility since new columns and indices can be added without
120having to recode every query.
121</p>
122</li>
123
124<li><p><b>Command-line dataset analysis tool</b></p>
125
126<p>
127Experienced SQL users can employ
128the command-line <b>sqlite</b> program to analyze miscellaneous
129datasets. Raw data can be imported from CSV files, then that
130data can be sliced and diced to generate a myriad of summary
131reports. Possible uses include website log analysis, sports
132statistics analysis, compilation of programming metrics, and
133analysis of experimental results.
134</p>
135
136<p>
137You can also do the same thing with a enterprise client/server
138database, of course. The advantages to using SQLite in this situation
139are that SQLite is much easier to set up and the resulting database
140is a single file that you can store on a floppy disk or flash-memory stick
141or email to a colleague.
142</p>
143</li>
144
145<li><p><b>Stand-in for an enterprise database during demos or testing</b></p>
146
147<p>
148If you are writing a client application for an enterprise database engine,
149it makes sense to use a generic database backend that allows you to connect
150to many different kinds of SQL database engines. It makes even better
151sense to
152go ahead and include SQLite in the mix of supported database and to statically
153link the SQLite engine in with the client. That way the client program
154can be used standalone with an SQLite data file for testing or for
155demonstrations.
156</p>
157</li>
158
159<li><p><b>Database Pedagogy</b></p>
160
161<p>
162Because it is simple to setup and use (installation is trivial: just
163copy the <b>sqlite</b> or <b>sqlite.exe</b> executable to the target machine
164and run it) SQLite makes a good database engine for use in teaching SQL.
165Students can easily create as many databases as they like and can
166email databases to the instructor for comments or grading. For more
167advanced students who are interested in studying how an RDBMS is
168implemented, the modular and well-commented and documented SQLite code
169can serve as a good basis. This is not to say that SQLite is an accurate
170model of how other database engines are implemented, but rather a student who
171understands how SQLite works can more quickly comprehend the operational
172principles of other systems.
173</p>
174</li>
175
176<li><p><b>Experimental SQL language extensions</b></p>
177
178<p>The simple, modular design of SQLite makes it a good platform for
179prototyping new, experimental database language features or ideas.
180</p>
181</li>
182
183
184</ul>
185
186<h2>Situations Where Another RDBMS May Work Better</h2>
187
188<ul>
189<li><p><b>Client/Server Applications</b><p>
190
191<p>If you have many client programs accessing a common database
192over a network, you should consider using a client/server database
193engine instead of SQLite. SQLite will work over a network filesystem,
194but because of the latency associated with most network filesystems,
195performance will not be great. Also, the file locking logic of
196many network filesystems implementation contains bugs (on both Unix
197and windows). If file locking does not work like it should,
198it might be possible for two or more client programs to modify the
199same part of the same database at the same time, resulting in
200database corruption. Because this problem results from bugs in
201the underlying filesystem implementation, there is nothing SQLite
202can do to prevent it.</p>
203
204<p>A good rule of thumb is that you should avoid using SQLite
205in situations where the same database will be accessed simultaneously
206from many computers over a network filesystem.</p>
207</li>
208
209<li><p><b>High-volume Websites</b></p>
210
211<p>SQLite will normally work fine as the database backend to a website.
212But if you website is so busy that your are thinking of splitting the
213database component off onto a separate machine, then you should
214definitely consider using an enterprise-class client/server database
215engine instead of SQLite.</p>
216</li>
217
218<li><p><b>Very large datasets</b></p>
219
220<p>When you start a transaction in SQLite (which happens automatically
221before any write operation that is not within an explicit BEGIN...COMMIT)
222the engine has to allocate a bitmap of dirty pages in the disk file to
223help it manage its rollback journal. SQLite needs 256 bytes of RAM for
224every 1MiB of database (assuming a 1024-byte page size: less memory is
225used with larger page sizes, of course).
226For smaller databases, the amount of memory
227required is not a problem, but when database begin to grow into the
228multi-gigabyte range, the size of the bitmap can get quite large. If
229you need to store and modify more than a few dozen GB of data, you should
230consider using a different database engine.
231</p>
232</li>
233
234<li><p><b>High Concurrency</b></p>
235
236<p>
237SQLite uses reader/writer locks on the entire database file. That means
238if any process is reading from any part of the database, all other
239processes are prevented from writing any other part of the database.
240Similarly, if any one process is writing to the database,
241all other processes are prevented from reading any other part of the
242database.
243For many situations, this is not a problem. Each application
244does its database work quickly and moves on, and no lock lasts for more
245than a few dozen milliseconds. But there are some applications that require
246more concurrency, and those applications may need to seek a different
247solution.
248</p>
249</li>
250
251</ul>
252
253}
254footer $rcsid