diff options
author | dan miller | 2007-10-21 08:36:32 +0000 |
---|---|---|
committer | dan miller | 2007-10-21 08:36:32 +0000 |
commit | 2f8d7092bc2c9609fa98d6888106b96f38b22828 (patch) | |
tree | da6c37579258cc965b52a75aee6135fe44237698 /libraries/sqlite/unix/sqlite-3.5.1/www | |
parent | * Committing new PolicyManager based on an ACL system. (diff) | |
download | opensim-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 '')
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 | # | ||
4 | set rcsid {$Id: 34to35.tcl,v 1.4 2007/10/01 13:54:11 drh Exp $} | ||
5 | source common.tcl | ||
6 | header {SQLite Changes From Version 3.4.2 To 3.5.0} | ||
7 | |||
8 | proc CODE {text} { | ||
9 | puts "<blockquote><pre>" | ||
10 | puts $text | ||
11 | puts "</pre></blockquote>" | ||
12 | } | ||
13 | proc SYNTAX {text} { | ||
14 | puts "<blockquote><pre>" | ||
15 | set t2 [string map {& & < < > >} $text] | ||
16 | regsub -all "/(\[^\n/\]+)/" $t2 {</b><i>\1</i><b>} t3 | ||
17 | puts "<b>$t3</b>" | ||
18 | puts "</pre></blockquote>" | ||
19 | } | ||
20 | proc IMAGE {name {caption {}}} { | ||
21 | puts "<center><img src=\"$name\">" | ||
22 | if {$caption!=""} { | ||
23 | puts "<br>$caption" | ||
24 | } | ||
25 | puts "</center>" | ||
26 | } | ||
27 | proc 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 | } | ||
33 | proc 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 | } | ||
44 | set level(0) 0 | ||
45 | set level(1) 0 | ||
46 | proc 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 | |||
69 | HEADING 0 {Moving From SQLite 3.4.2 to 3.5.0} | ||
70 | |||
71 | PARAGRAPH { | ||
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 | |||
82 | HEADING 1 {Overview Of Changes} | ||
83 | |||
84 | PARAGRAPH { | ||
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 | } | ||
89 | PARAGRAPH { | ||
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 | } | ||
134 | PARAGRAPH { | ||
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 | |||
145 | HEADING 1 {The OS Interface Layer} | ||
146 | |||
147 | PARAGRAPH { | ||
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 | |||
165 | HEADING 2 {The Virtual File System Object} | ||
166 | |||
167 | PARAGRAPH { | ||
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 | |||
176 | PARAGRAPH { | ||
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 | |||
183 | PARAGRAPH { | ||
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 | |||
192 | HEADING 3 {Registering New VFS Objects} | ||
193 | |||
194 | PARAGRAPH { | ||
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 | |||
204 | CODE { | ||
205 | int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); | ||
206 | } | ||
207 | |||
208 | PARAGRAPH { | ||
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 | |||
222 | PARAGRAPH { | ||
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 | |||
236 | HEADING 3 {Additional Control Over VFS Objects} | ||
237 | |||
238 | PARAGRAPH { | ||
239 | The [sqlite3_vfs_unregister()] API is used to remove an existing | ||
240 | VFS from the system. | ||
241 | } | ||
242 | |||
243 | CODE { | ||
244 | int sqlite3_vfs_unregister(sqlite3_vfs*); | ||
245 | } | ||
246 | |||
247 | PARAGRAPH { | ||
248 | The [sqlite3_vfs_find()] API is used to locate a particular VFS | ||
249 | by name. Its prototype is as follows: | ||
250 | } | ||
251 | |||
252 | CODE { | ||
253 | sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName); | ||
254 | } | ||
255 | |||
256 | PARAGRAPH { | ||
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 | |||
264 | HEADING 3 {Modifications Of Existing VFSes} | ||
265 | |||
266 | PARAGRAPH { | ||
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 | |||
278 | HEADING 3 {The VFS Object} | ||
279 | |||
280 | PARAGRAPH { | ||
281 | A VFS object is an instance of the following structure: | ||
282 | } | ||
283 | |||
284 | CODE { | ||
285 | typedef struct sqlite3_vfs sqlite3_vfs; | ||
286 | struct 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 | |||
311 | PARAGRAPH { | ||
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 | |||
316 | PARAGRAPH { | ||
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 | |||
323 | PARAGRAPH { | ||
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 | |||
333 | PARAGRAPH { | ||
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 | |||
344 | PARAGRAPH { | ||
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 | |||
349 | PARAGRAPH { | ||
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 | |||
355 | PARAGRAPH { | ||
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 | |||
361 | PARAGRAPH { | ||
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 | |||
417 | PARAGRAPH { | ||
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 | |||
431 | PARAGRAPH { | ||
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 | |||
442 | PARAGRAPH { | ||
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 | |||
452 | PARAGRAPH { | ||
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 | |||
462 | PARAGRAPH { | ||
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 | |||
470 | PARAGRAPH { | ||
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 | |||
487 | PARAGRAPH { | ||
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 | |||
504 | PARAGRAPH { | ||
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 | |||
514 | PARAGRAPH { | ||
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 | |||
521 | HEADING 3 {The Open File Object} | ||
522 | |||
523 | PARAGRAPH { | ||
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 | |||
528 | CODE { | ||
529 | typedef struct sqlite3_file sqlite3_file; | ||
530 | struct sqlite3_file { | ||
531 | const struct sqlite3_io_methods *pMethods; | ||
532 | }; | ||
533 | } | ||
534 | |||
535 | PARAGRAPH { | ||
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 | |||
543 | PARAGRAPH { | ||
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 | |||
549 | CODE { | ||
550 | typedef struct sqlite3_io_methods sqlite3_io_methods; | ||
551 | struct 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 | |||
569 | PARAGRAPH { | ||
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 | |||
575 | PARAGRAPH { | ||
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 | |||
582 | PARAGRAPH { | ||
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 | |||
591 | PARAGRAPH { | ||
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 | |||
604 | PARAGRAPH { | ||
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 | |||
611 | PARAGRAPH { | ||
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 | |||
622 | PARAGRAPH { | ||
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 | |||
628 | PARAGRAPH { | ||
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 | |||
661 | PARAGRAPH { | ||
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 | |||
667 | PARAGRAPH { | ||
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 | |||
685 | PARAGRAPH { | ||
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 | |||
696 | PARAGRAPH { | ||
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 | |||
727 | HEADING 3 {Checklist For Constructing A New VFS} | ||
728 | |||
729 | PARAGRAPH { | ||
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 | |||
735 | PARAGRAPH { | ||
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 | |||
757 | PARAGRAPH { | ||
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 | |||
763 | HEADING 1 {The Memory Allocation Subsystem} | ||
764 | |||
765 | PARAGRAPH { | ||
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 | |||
773 | PARAGRAPH { | ||
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 | |||
784 | PARAGRAPH { | ||
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 | |||
797 | PARAGRAPH { | ||
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 | |||
804 | CODE { | ||
805 | int sqlite3_memory_alarm( | ||
806 | void(*xCallback)(void *pArg, sqlite3_int64 used, int N), | ||
807 | void *pArg, | ||
808 | sqlite3_int64 iThreshold | ||
809 | ); | ||
810 | } | ||
811 | |||
812 | PARAGRAPH { | ||
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 | |||
823 | PARAGRAPH { | ||
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 | |||
833 | PARAGRAPH { | ||
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 | |||
845 | PARAGRAPH { | ||
846 | The built-in memory allocators in SQLite also provide the following | ||
847 | additional interfaces: | ||
848 | } | ||
849 | |||
850 | CODE { | ||
851 | sqlite3_int64 sqlite3_memory_used(void); | ||
852 | sqlite3_int64 sqlite3_memory_highwater(int resetFlag); | ||
853 | } | ||
854 | |||
855 | PARAGRAPH { | ||
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 | |||
867 | HEADING 1 {The Mutex Subsystem} | ||
868 | |||
869 | PARAGRAPH { | ||
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 | |||
877 | PARAGRAPH { | ||
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 | |||
884 | CODE { | ||
885 | sqlite3_mutex *sqlite3_mutex_alloc(int); | ||
886 | void sqlite3_mutex_free(sqlite3_mutex*); | ||
887 | void sqlite3_mutex_enter(sqlite3_mutex*); | ||
888 | int sqlite3_mutex_try(sqlite3_mutex*); | ||
889 | void sqlite3_mutex_leave(sqlite3_mutex*); | ||
890 | } | ||
891 | |||
892 | PARAGRAPH { | ||
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 | |||
915 | PARAGRAPH { | ||
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 | |||
921 | PARAGRAPH { | ||
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 | |||
933 | PARAGRAPH { | ||
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 | |||
944 | PARAGRAPH { | ||
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 | |||
952 | HEADING 1 {Other Interface Changes} | ||
953 | |||
954 | PARAGRAPH { | ||
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 | |||
962 | PARAGRAPH { | ||
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 | |||
975 | PARAGRAPH { | ||
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 | |||
984 | PARAGRAPH { | ||
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 | |||
992 | HEADING 1 {Summary} | ||
993 | |||
994 | PARAGRAPH { | ||
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 | ||
2 | Portrait | ||
3 | Center | ||
4 | Inches | ||
5 | Letter | ||
6 | 100.00 | ||
7 | Single | ||
8 | -2 | ||
9 | 1200 2 | ||
10 | 2 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 | ||
13 | 2 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 | ||
16 | 2 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 | ||
19 | 2 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 | ||
22 | 2 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 | ||
25 | 2 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 | ||
28 | 2 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 | ||
31 | 2 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 | ||
33 | 2 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 | ||
35 | 2 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 | ||
37 | 2 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 | ||
39 | 2 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 | ||
41 | 2 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 | ||
43 | 2 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 | ||
45 | 2 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 | ||
47 | 4 1 0 100 0 0 20 0.0000 4 195 1020 3675 750 Interface\001 | ||
48 | 4 1 0 100 0 0 14 0.0000 4 195 2040 3675 1125 main.c table.c tclsqlite.c\001 | ||
49 | 4 1 0 100 0 0 20 0.0000 4 195 1920 3675 6675 Virtual Machine\001 | ||
50 | 4 1 0 100 0 0 14 0.0000 4 150 570 3675 7050 vdbe.c\001 | ||
51 | 4 1 0 100 0 0 20 0.0000 4 195 1830 3675 4875 Code Generator\001 | ||
52 | 4 1 0 100 0 0 14 0.0000 4 195 1860 3675 5175 build.c delete.c expr.c\001 | ||
53 | 4 1 0 100 0 0 14 0.0000 4 195 2115 3675 5400 insert.c select.c update.c\001 | ||
54 | 4 1 0 100 0 0 14 0.0000 4 150 705 3675 5625 where.c\001 | ||
55 | 4 1 0 100 0 0 20 0.0000 4 195 735 3675 3450 Parser\001 | ||
56 | 4 1 0 100 0 0 20 0.0000 4 195 1140 3675 2100 Tokenizer\001 | ||
57 | 4 1 0 100 0 0 14 0.0000 4 150 870 3675 2475 tokenize.c\001 | ||
58 | 4 1 0 100 0 0 20 0.0000 4 255 1350 3675 9375 Page Cache\001 | ||
59 | 4 1 0 100 0 0 14 0.0000 4 150 630 3675 3825 parse.y\001 | ||
60 | 4 1 0 100 0 0 14 0.0000 4 150 600 3675 8400 btree.c\001 | ||
61 | 4 1 0 100 0 0 14 0.0000 4 150 645 3675 9750 pager.c\001 | ||
62 | 4 1 0 100 0 0 20 0.0000 4 195 1620 3675 8025 B-tree Driver\001 | ||
63 | 4 1 0 100 0 0 14 0.0000 4 105 345 3675 11100 os.c\001 | ||
64 | 4 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 | # | ||
4 | set rcsid {$Id: arch.tcl,v 1.16 2004/10/10 17:24:54 drh Exp $} | ||
5 | source common.tcl | ||
6 | header {Architecture of SQLite} | ||
7 | puts { | ||
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. | ||
17 | The information here is useful to those who want to understand or | ||
18 | modify the inner workings of SQLite. | ||
19 | </p> | ||
20 | |||
21 | <p> | ||
22 | A block diagram showing the main components of SQLite | ||
23 | and how they interrelate is shown at the right. The text that | ||
24 | follows will provide a quick overview of each of these components. | ||
25 | </p> | ||
26 | |||
27 | |||
28 | <p> | ||
29 | This document describes SQLite version 3.0. Version 2.8 and | ||
30 | earlier 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 | ||
36 | functions found in the <b>main.c</b>, <b>legacy.c</b>, and | ||
37 | <b>vdbeapi.c</b> source files | ||
38 | though some routines are | ||
39 | scattered about in other files where they can have access to data | ||
40 | structures 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>. | ||
44 | The Tcl interface is implemented by <b>tclsqlite.c</b>. More | ||
45 | information 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 | ||
49 | symbols in the SQLite library begin with the prefix <b>sqlite3</b>. | ||
50 | Those symbols that are intended for external use (in other words, | ||
51 | those symbols which form the API for SQLite) begin | ||
52 | with <b>sqlite3_</b>.</p> | ||
53 | |||
54 | <h3>Tokenizer</h3> | ||
55 | |||
56 | <p>When a string containing SQL statements is to be executed, the | ||
57 | interface passes that string to the tokenizer. The job of the tokenizer | ||
58 | is to break the original string up into tokens and pass those tokens | ||
59 | one by one to the parser. The tokenizer is hand-coded in C in | ||
60 | the file <b>tokenize.c</b>. | ||
61 | |||
62 | <p>Note that in this design, the tokenizer calls the parser. People | ||
63 | who are familiar with YACC and BISON may be used to doing things the | ||
64 | other way around -- having the parser call the tokenizer. The author | ||
65 | of SQLite | ||
66 | has done it both ways and finds things generally work out nicer for | ||
67 | the 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 | ||
72 | their context. The parser for SQLite is generated using the | ||
73 | <a href="http://www.hwaci.com/sw/lemon/">Lemon</a> LALR(1) parser | ||
74 | generator. Lemon does the same job as YACC/BISON, but it uses | ||
75 | a different input syntax which is less error-prone. | ||
76 | Lemon also generates a parser which is reentrant and thread-safe. | ||
77 | And lemon defines the concept of a non-terminal destructor so | ||
78 | that it does not leak memory when syntax errors are encountered. | ||
79 | The source file that drives Lemon is found in <b>parse.y</b>.</p> | ||
80 | |||
81 | <p>Because | ||
82 | lemon is a program not normally found on development machines, the | ||
83 | complete source code to lemon (just one C file) is included in the | ||
84 | SQLite distribution in the "tool" subdirectory. Documentation on | ||
85 | lemon 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, | ||
91 | it calls the code generator to produce virtual machine code that | ||
92 | will do the work that the SQL statements request. There are many | ||
93 | files 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> | ||
105 | and <b>where.c</b>. | ||
106 | In 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 | ||
109 | SELECT, 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 | ||
112 | for SQL statements with the same names. (Each of these files calls routines | ||
113 | in <b>expr.c</b> and <b>where.c</b> as necessary.) All other | ||
114 | SQL statements are coded out of <b>build.c</b>. | ||
115 | The <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 | ||
121 | the virtual machine. Additional information about the virtual | ||
122 | machine is <a href="opcode.html">available separately</a>. | ||
123 | To summarize, the virtual machine implements an abstract computing | ||
124 | engine specifically designed to manipulate database files. The | ||
125 | machine has a stack which is used for intermediate storage. | ||
126 | Each instruction contains an opcode and | ||
127 | up to three additional operands.</p> | ||
128 | |||
129 | <p>The virtual machine itself is entirely contained in a single | ||
130 | source file <b>vdbe.c</b>. The virtual machine also has | ||
131 | its own header files: <b>vdbe.h</b> that defines an interface | ||
132 | between the virtual machine and the rest of the SQLite library and | ||
133 | <b>vdbeInt.h</b> which defines structure private the virtual machine. | ||
134 | The <b>vdbeaux.c</b> file contains utilities used by the virtual | ||
135 | machine and interface modules used by the rest of the library to | ||
136 | construct VM programs. The <b>vdbeapi.c</b> file contains external | ||
137 | interfaces 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 | ||
140 | in an internal object named "Mem" which is implemented by | ||
141 | <b>vdbemem.c</b>.</p> | ||
142 | |||
143 | <p> | ||
144 | SQLite implements SQL functions using callbacks to C-language routines. | ||
145 | Even the built-in SQL functions are implemented this way. Most of | ||
146 | the 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>. | ||
148 | Date 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 | ||
154 | found in the <b>btree.c</b> source file. A separate B-tree is used for | ||
155 | each table and index in the database. All B-trees are stored in the | ||
156 | same disk file. Details of the file format are recorded in a large | ||
157 | comment 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 | ||
166 | chunks. The default chunk size is 1024 bytes but can vary between 512 | ||
167 | and 65536 bytes. | ||
168 | The page cache is responsible for reading, writing, and | ||
169 | caching these chunks. | ||
170 | The page cache also provides the rollback and atomic commit abstraction | ||
171 | and takes care of locking of the database file. The | ||
172 | B-tree driver requests particular pages from the page cache and notifies | ||
173 | the page cache when it wants to modify pages or commit or rollback | ||
174 | changes and the page cache handles all the messy details of making sure | ||
175 | the requests are handled quickly, safely, and efficiently.</p> | ||
176 | |||
177 | <p>The code to implement the page cache is contained in the single C | ||
178 | source file <b>pager.c</b>. The interface to the page cache subsystem | ||
179 | is defined by the header file <b>pager.h</b>. | ||
180 | </p> | ||
181 | |||
182 | <h3>OS Interface</h3> | ||
183 | |||
184 | <p> | ||
185 | In order to provide portability between POSIX and Win32 operating systems, | ||
186 | SQLite uses an abstraction layer to interface with the operating system. | ||
187 | The 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. | ||
190 | Each of these operating-specific implements typically has its own | ||
191 | header file: <b>os_unix.h</b>, <b>os_win.h</b>, etc. | ||
192 | </p> | ||
193 | |||
194 | <h3>Utilities</h3> | ||
195 | |||
196 | <p> | ||
197 | Memory allocation and caseless string comparison routines are located | ||
198 | in <b>util.c</b>. | ||
199 | Symbol tables used by the parser are maintained by hash tables found | ||
200 | in <b>hash.c</b>. The <b>utf.c</b> source file contains Unicode | ||
201 | conversion subroutines. | ||
202 | SQLite has its own private implementation of <b>printf()</b> (with | ||
203 | some extensions) in <b>printf.c</b> and its own random number generator | ||
204 | in <b>random.c</b>. | ||
205 | </p> | ||
206 | |||
207 | <h3>Test Code</h3> | ||
208 | |||
209 | <p> | ||
210 | If you count regression test scripts, | ||
211 | more than half the total code base of SQLite is devoted to testing. | ||
212 | There are many <b>assert()</b> statements in the main code files. | ||
213 | In additional, the source files <b>test1.c</b> through <b>test5.c</b> | ||
214 | together with <b>md5.c</b> implement extensions used for testing | ||
215 | purposes only. The <b>os_test.c</b> backend interface is used to | ||
216 | simulate power failures to verify the crash-recovery mechanism in | ||
217 | the pager. | ||
218 | </p> | ||
219 | |||
220 | } | ||
221 | footer $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 | ||
2 | Landscape | ||
3 | Center | ||
4 | Inches | ||
5 | Letter | ||
6 | 100.00 | ||
7 | Single | ||
8 | -2 | ||
9 | 1200 2 | ||
10 | 0 32 #000000 | ||
11 | 0 33 #868686 | ||
12 | 0 34 #dfefd7 | ||
13 | 0 35 #d7efef | ||
14 | 0 36 #efdbef | ||
15 | 0 37 #efdbd7 | ||
16 | 0 38 #e7efcf | ||
17 | 0 39 #9e9e9e | ||
18 | 6 3225 3900 4650 6000 | ||
19 | 2 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 | ||
21 | 2 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 | ||
23 | 2 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 | ||
25 | 2 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 | ||
27 | 2 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 | ||
29 | 2 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 | ||
31 | 2 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 | ||
34 | 2 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 | ||
37 | 4 1 0 50 0 2 12 0.0000 4 135 1050 3900 5775 OS Interface\001 | ||
38 | 4 1 0 50 0 2 12 0.0000 4 135 615 3900 4200 B-Tree\001 | ||
39 | 4 1 0 50 0 2 12 0.0000 4 180 495 3900 4950 Pager\001 | ||
40 | -6 | ||
41 | 6 5400 4725 6825 5250 | ||
42 | 2 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 | ||
44 | 2 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 | ||
46 | 4 1 0 50 0 2 12 0.0000 4 135 630 6000 5025 Utilities\001 | ||
47 | -6 | ||
48 | 6 5400 5550 6825 6075 | ||
49 | 2 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 | ||
51 | 2 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 | ||
53 | 4 1 0 50 0 2 12 0.0000 4 135 855 6000 5850 Test Code\001 | ||
54 | -6 | ||
55 | 6 5400 2775 6825 3750 | ||
56 | 2 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 | ||
58 | 2 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 | ||
60 | 4 1 0 50 0 2 12 0.0000 4 135 420 6075 3150 Code\001 | ||
61 | 4 1 0 50 0 2 12 0.0000 4 135 855 6075 3375 Generator\001 | ||
62 | -6 | ||
63 | 6 5400 1950 6825 2475 | ||
64 | 2 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 | ||
66 | 2 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 | ||
68 | 4 1 0 50 0 2 12 0.0000 4 135 570 6075 2250 Parser\001 | ||
69 | -6 | ||
70 | 2 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 | ||
72 | 2 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 | ||
74 | 2 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 | ||
76 | 2 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 | ||
78 | 2 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 | ||
80 | 2 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 | ||
82 | 2 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 | ||
84 | 2 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 | ||
86 | 2 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 | ||
89 | 2 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 | ||
92 | 2 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 | ||
95 | 2 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 | ||
98 | 2 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 | ||
101 | 2 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 | ||
103 | 2 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 | ||
106 | 2 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 | ||
108 | 2 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 | ||
110 | 2 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 | ||
112 | 2 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 | ||
115 | 4 1 0 50 0 2 12 0.0000 4 135 855 6075 1350 Tokenizer\001 | ||
116 | 4 1 0 50 0 1 12 1.5708 4 180 1020 7125 2250 SQL Compiler\001 | ||
117 | 4 1 0 50 0 1 12 1.5708 4 135 345 3075 2025 Core\001 | ||
118 | 4 1 0 50 0 2 12 0.0000 4 135 1290 3900 2850 Virtual Machine\001 | ||
119 | 4 1 0 50 0 2 12 0.0000 4 165 1185 3900 1995 SQL Command\001 | ||
120 | 4 1 0 50 0 2 12 0.0000 4 135 855 3900 2183 Processor\001 | ||
121 | 4 1 0 50 0 2 14 0.0000 4 150 870 3900 1350 Interface\001 | ||
122 | 4 1 0 50 0 1 12 1.5708 4 135 885 7125 5400 Accessories\001 | ||
123 | 4 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 | ||
2 | Landscape | ||
3 | Center | ||
4 | Inches | ||
5 | Letter | ||
6 | 100.00 | ||
7 | Single | ||
8 | -2 | ||
9 | 1200 2 | ||
10 | 0 32 #000000 | ||
11 | 0 33 #868686 | ||
12 | 0 34 #dfefd7 | ||
13 | 0 35 #d7efef | ||
14 | 0 36 #efdbef | ||
15 | 0 37 #efdbd7 | ||
16 | 0 38 #e7efcf | ||
17 | 0 39 #9e9e9e | ||
18 | 6 3225 3900 4650 6000 | ||
19 | 2 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 | ||
21 | 2 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 | ||
23 | 2 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 | ||
25 | 2 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 | ||
27 | 2 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 | ||
29 | 2 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 | ||
31 | 2 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 | ||
34 | 2 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 | ||
37 | 4 1 0 50 0 2 12 0.0000 4 135 1050 3900 5775 OS Interface\001 | ||
38 | 4 1 0 50 0 2 12 0.0000 4 135 615 3900 4200 B-Tree\001 | ||
39 | 4 1 0 50 0 2 12 0.0000 4 180 495 3900 4950 Pager\001 | ||
40 | -6 | ||
41 | 6 5175 4275 7200 6150 | ||
42 | 6 5400 4519 6825 5090 | ||
43 | 2 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 | ||
45 | 2 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 | ||
47 | 4 1 0 50 0 2 12 0.0000 4 135 630 6000 4845 Utilities\001 | ||
48 | -6 | ||
49 | 6 5400 5416 6825 5987 | ||
50 | 2 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 | ||
52 | 2 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 | ||
54 | 4 1 0 50 0 2 12 0.0000 4 135 855 6000 5742 Test Code\001 | ||
55 | -6 | ||
56 | 2 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 | ||
58 | 4 1 0 50 0 1 12 1.5708 4 135 885 7125 5253 Accessories\001 | ||
59 | -6 | ||
60 | 6 5400 2700 6825 3675 | ||
61 | 2 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 | ||
63 | 2 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 | ||
65 | 4 1 0 50 0 2 12 0.0000 4 135 420 6075 3075 Code\001 | ||
66 | 4 1 0 50 0 2 12 0.0000 4 135 855 6075 3300 Generator\001 | ||
67 | -6 | ||
68 | 6 5400 1875 6825 2400 | ||
69 | 2 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 | ||
71 | 2 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 | ||
73 | 4 1 0 50 0 2 12 0.0000 4 135 570 6075 2175 Parser\001 | ||
74 | -6 | ||
75 | 2 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 | ||
77 | 2 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 | ||
79 | 2 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 | ||
81 | 2 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 | ||
83 | 2 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 | ||
85 | 2 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 | ||
87 | 2 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 | ||
89 | 2 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 | ||
91 | 2 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 | ||
94 | 2 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 | ||
97 | 2 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 | ||
100 | 2 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 | ||
103 | 2 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 | ||
106 | 2 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 | ||
108 | 2 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 | ||
111 | 2 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 | ||
113 | 2 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 | ||
115 | 2 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 | ||
118 | 4 1 0 50 0 2 12 0.0000 4 135 855 6075 1350 Tokenizer\001 | ||
119 | 4 1 0 50 0 1 12 1.5708 4 180 1020 7125 2250 SQL Compiler\001 | ||
120 | 4 1 0 50 0 1 12 1.5708 4 135 345 3075 2025 Core\001 | ||
121 | 4 1 0 50 0 2 12 0.0000 4 135 1290 3900 2850 Virtual Machine\001 | ||
122 | 4 1 0 50 0 2 12 0.0000 4 165 1185 3900 1995 SQL Command\001 | ||
123 | 4 1 0 50 0 2 12 0.0000 4 135 855 3900 2183 Processor\001 | ||
124 | 4 1 0 50 0 2 14 0.0000 4 150 870 3900 1350 Interface\001 | ||
125 | 4 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 | # | ||
4 | set rcsid {$Id: audit.tcl,v 1.1 2002/07/13 16:52:35 drh Exp $} | ||
5 | |||
6 | puts {<html> | ||
7 | <head> | ||
8 | <title>SQLite Security Audit Procedure</title> | ||
9 | </head> | ||
10 | <body bgcolor=white> | ||
11 | <h1 align=center> | ||
12 | SQLite Security Audit Procedure | ||
13 | </h1>} | ||
14 | puts "<p align=center> | ||
15 | (This page was last modified on [lrange $rcsid 3 4] UTC) | ||
16 | </p>" | ||
17 | |||
18 | puts { | ||
19 | <p> | ||
20 | A security audit for SQLite consists of two components. First, there is | ||
21 | a check for common errors that often lead to security problems. Second, | ||
22 | an attempt is made to construct a proof that SQLite has certain desirable | ||
23 | security properties. | ||
24 | </p> | ||
25 | |||
26 | <h2>Part I: Things to check</h2> | ||
27 | |||
28 | <p> | ||
29 | Scan all source code and check for the following common errors: | ||
30 | </p> | ||
31 | |||
32 | <ol> | ||
33 | <li><p> | ||
34 | Verify that the destination buffer is large enough to hold its result | ||
35 | in 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> | ||
49 | Verify that pointers returned by subroutines are not NULL before using | ||
50 | the pointers. In particular, make sure the return values for the following | ||
51 | routines 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> | ||
87 | On all functions and procedures, verify that pointer parameters are not NULL | ||
88 | before dereferencing those parameters. | ||
89 | </p></li> | ||
90 | <li><p> | ||
91 | Check to make sure that temporary files are opened safely: that the process | ||
92 | will not overwrite an existing file when opening the temp file and that | ||
93 | another process is unable to substitute a file for the temp file being | ||
94 | opened. | ||
95 | </p></li> | ||
96 | </ol> | ||
97 | |||
98 | |||
99 | |||
100 | <h2>Part II: Things to prove</h2> | ||
101 | |||
102 | <p> | ||
103 | Prove that SQLite exhibits the characteristics outlined below: | ||
104 | </p> | ||
105 | |||
106 | <ol> | ||
107 | <li><p> | ||
108 | The 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> | ||
116 | CREATE 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> | ||
123 | sqlite_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> | ||
132 | The call to <b>sqlite_exec_printf()</b> will | ||
133 | return in a length of time that is a polynomial in <b>strlen(Z)</b>. | ||
134 | It might return an error code but it will not crash. | ||
135 | </p></li> | ||
136 | <li><p> | ||
137 | At most one new row will be inserted into table t1. | ||
138 | </p></li> | ||
139 | <li><p> | ||
140 | No preexisting rows of t1 will be deleted or modified. | ||
141 | </p></li> | ||
142 | <li><p> | ||
143 | No tables other than t1 will be altered in any way. | ||
144 | </p></li> | ||
145 | <li><p> | ||
146 | No preexisting files on the host computers filesystem, other than | ||
147 | the database file itself, will be deleted or modified. | ||
148 | </p></li> | ||
149 | <li><p> | ||
150 | For some constants <b>K1</b> and <b>K2</b>, | ||
151 | if at least <b>K1*strlen(Z) + K2</b> bytes of contiguous memory are | ||
152 | available to <b>malloc()</b>, then the call to <b>sqlite_exec_printf()</b> | ||
153 | will not return SQLITE_NOMEM. | ||
154 | </p></li> | ||
155 | </ol> | ||
156 | </p></li> | ||
157 | |||
158 | |||
159 | <li><p> | ||
160 | The 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> | ||
174 | sqlite_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> | ||
179 | The call to <b>sqlite_exec()</b> will | ||
180 | return in a length of time which is a polynomial in <b>strlen(Z)</b>. | ||
181 | It might return an error code but it will not crash. | ||
182 | </p></li> | ||
183 | <li><p> | ||
184 | After <b>sqlite_exec()</b> returns, the buffer <b>Y</b> will not contain | ||
185 | any content from any preexisting file on the host computers file system, | ||
186 | except for the database file. | ||
187 | </p></li> | ||
188 | <li><p> | ||
189 | After the call to <b>sqlite_exec()</b> returns, the database file will | ||
190 | still be well-formed. It might not contain the same data, but it will | ||
191 | still be a properly constructed SQLite database file. | ||
192 | </p></li> | ||
193 | <li><p> | ||
194 | No preexisting files on the host computers filesystem, other than | ||
195 | the database file itself, will be deleted or modified. | ||
196 | </p></li> | ||
197 | <li><p> | ||
198 | For some constants <b>K1</b> and <b>K2</b>, | ||
199 | if at least <b>K1*strlen(Z) + K2</b> bytes of contiguous memory are | ||
200 | available to <b>malloc()</b>, then the call to <b>sqlite_exec()</b> | ||
201 | will not return SQLITE_NOMEM. | ||
202 | </p></li> | ||
203 | </ol> | ||
204 | </p></li> | ||
205 | |||
206 | </ol> | ||
207 | } | ||
208 | puts { | ||
209 | <p><hr /></p> | ||
210 | <p><a href="index.html"><img src="/goback.jpg" border=0 /> | ||
211 | Back 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 | # | ||
4 | set rcsid {$Id: } | ||
5 | source common.tcl | ||
6 | |||
7 | if {[llength $argv]>0} { | ||
8 | set outputdir [lindex $argv 0] | ||
9 | } else { | ||
10 | set outputdir "" | ||
11 | } | ||
12 | |||
13 | header {SQLite Autoincrement} | ||
14 | puts { | ||
15 | <h1>SQLite Autoincrement</h1> | ||
16 | |||
17 | <p> | ||
18 | In SQLite, every row of every table has an integer ROWID. | ||
19 | The ROWID for each row is unique among all rows in the same table. | ||
20 | In SQLite version 2.8 the ROWID is a 32-bit signed integer. | ||
21 | Version 3.0 of SQLite expanded the ROWID to be a 64-bit signed integer. | ||
22 | </p> | ||
23 | |||
24 | <p> | ||
25 | You can access the ROWID of an SQLite table using one the special column | ||
26 | names ROWID, _ROWID_, or OID. | ||
27 | Except if you declare an ordinary table column to use one of those special | ||
28 | names, then the use of that name will refer to the declared column not | ||
29 | to the internal ROWID. | ||
30 | </p> | ||
31 | |||
32 | <p> | ||
33 | If a table contains a column of type INTEGER PRIMARY KEY, then that | ||
34 | column becomes an alias for the ROWID. You can then access the ROWID | ||
35 | using any of four different names, the original three names described above | ||
36 | or the name given to the INTEGER PRIMARY KEY column. All these names are | ||
37 | aliases for one another and work equally well in any context. | ||
38 | </p> | ||
39 | |||
40 | <p> | ||
41 | When a new row is inserted into an SQLite table, the ROWID can either | ||
42 | be specified as part of the INSERT statement or it can be assigned | ||
43 | automatically by the database engine. To specify a ROWID manually, | ||
44 | just include it in the list of values to be inserted. For example: | ||
45 | </p> | ||
46 | |||
47 | <blockquote><pre> | ||
48 | CREATE TABLE test1(a INT, b TEXT); | ||
49 | INSERT INTO test1(rowid, a, b) VALUES(123, 5, 'hello'); | ||
50 | </pre></blockquote> | ||
51 | |||
52 | <p> | ||
53 | If no ROWID is specified on the insert, an appropriate ROWID is created | ||
54 | automatically. The usual algorithm is to give the newly created row | ||
55 | a ROWID that is one larger than the largest ROWID in the table prior | ||
56 | to the insert. If the table is initially empty, then a ROWID of 1 is | ||
57 | used. If the largest ROWID is equal to the largest possible integer | ||
58 | (9223372036854775807 in SQLite version 3.0 and later) then the database | ||
59 | engine starts picking candidate ROWIDs at random until it finds one | ||
60 | that is not previously used. | ||
61 | </p> | ||
62 | |||
63 | <p> | ||
64 | The normal ROWID selection algorithm described above | ||
65 | will generate monotonically increasing | ||
66 | unique ROWIDs as long as you never use the maximum ROWID value and you never | ||
67 | delete the entry in the table with the largest ROWID. | ||
68 | If you ever delete rows or if you ever create a row with the maximum possible | ||
69 | ROWID, then ROWIDs from previously deleted rows might be reused when creating | ||
70 | new 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> | ||
77 | If a column has the type INTEGER PRIMARY KEY AUTOINCREMENT then a slightly | ||
78 | different ROWID selection algorithm is used. | ||
79 | The ROWID chosen for the new row is one larger than the largest ROWID | ||
80 | that has ever before existed in that same table. If the table has never | ||
81 | before contained any data, then a ROWID of 1 is used. If the table | ||
82 | has previously held a row with the largest possible ROWID, then new INSERTs | ||
83 | are not allowed and any attempt to insert a new row will fail with an | ||
84 | SQLITE_FULL error. | ||
85 | </p> | ||
86 | |||
87 | <p> | ||
88 | SQLite keeps track of the largest ROWID that a table has ever held using | ||
89 | the special SQLITE_SEQUENCE table. The SQLITE_SEQUENCE table is created | ||
90 | and initialized automatically whenever a normal table that contains an | ||
91 | AUTOINCREMENT column is created. The content of the SQLITE_SEQUENCE table | ||
92 | can be modified using ordinary UPDATE, INSERT, and DELETE statements. | ||
93 | But making modifications to this table will likely perturb the AUTOINCREMENT | ||
94 | key generation algorithm. Make sure you know what you are doing before | ||
95 | you undertake such changes. | ||
96 | </p> | ||
97 | |||
98 | <p> | ||
99 | The behavior implemented by the AUTOINCREMENT keyword is subtly different | ||
100 | from the default behavior. With AUTOINCREMENT, rows with automatically | ||
101 | selected ROWIDs are guaranteed to have ROWIDs that have never been used | ||
102 | before by the same table in the same database. And the automatically generated | ||
103 | ROWIDs are guaranteed to be monotonically increasing. These are important | ||
104 | properties in certain applications. But if your application does not | ||
105 | need these properties, you should probably stay with the default behavior | ||
106 | since the use of AUTOINCREMENT requires additional work to be done | ||
107 | as each row is inserted and thus causes INSERTs to run a little slower. | ||
108 | } | ||
109 | footer $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 | # | ||
4 | set rcsid {$Id: c_interface.tcl,v 1.43 2004/11/19 11:59:24 danielk1977 Exp $} | ||
5 | source common.tcl | ||
6 | header {The C language interface to the SQLite library} | ||
7 | puts { | ||
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 | ||
11 | a C or C++ program. This document gives an overview of the C/C++ | ||
12 | programming 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, | ||
17 | one opaque data structure, and some constants used as return values. | ||
18 | The core interface is as follows:</p> | ||
19 | |||
20 | <blockquote><pre> | ||
21 | typedef struct sqlite sqlite; | ||
22 | #define SQLITE_OK 0 /* Successful result */ | ||
23 | |||
24 | sqlite *sqlite_open(const char *dbname, int mode, char **errmsg); | ||
25 | |||
26 | void sqlite_close(sqlite *db); | ||
27 | |||
28 | int 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> | ||
38 | The above is all you really need to know in order to use SQLite | ||
39 | in your C or C++ programs. There are other interface functions | ||
40 | available (and described below) but we will begin by describing | ||
41 | the 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 | ||
48 | database or to create a new SQLite database. The first argument | ||
49 | is the database name. The second argument is intended to signal | ||
50 | whether the database is going to be used for reading and writing | ||
51 | or just for reading. But in the current implementation, the | ||
52 | second argument to <b>sqlite_open</b> is ignored. | ||
53 | The third argument is a pointer to a string pointer. | ||
54 | If the third argument is not NULL and an error occurs | ||
55 | while trying to open the database, then an error message will be | ||
56 | written to memory obtained from malloc() and *errmsg will be made | ||
57 | to point to this error message. The calling function is responsible | ||
58 | for 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 | ||
61 | contain the database. If the file does not exist, SQLite attempts | ||
62 | to create and initialize it. If the file is read-only (due to | ||
63 | permission bits or because it is located on read-only media like | ||
64 | a CD-ROM) then SQLite opens the database for reading only. The | ||
65 | entire SQL database is stored in a single file on the disk. But | ||
66 | additional temporary files may be created during the execution of | ||
67 | an SQL command in order to store the database rollback journal or | ||
68 | temporary and intermediate results of a query.</p> | ||
69 | |||
70 | <p>The return value of the <b>sqlite_open</b> function is a | ||
71 | pointer to an opaque <b>sqlite</b> structure. This pointer will | ||
72 | be the first argument to all subsequent SQLite function calls that | ||
73 | deal with the same database. NULL is returned if the open fails | ||
74 | for 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> | ||
80 | function passing it the sqlite structure pointer that was obtained | ||
81 | from a prior call to <b>sqlite_open</b>. | ||
82 | If a transaction is active when the database is closed, the transaction | ||
83 | is 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 | ||
89 | and 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> | ||
110 | The callback function is used to receive the results of a query. A | ||
111 | prototype for the callback function is as follows:</p> | ||
112 | |||
113 | <blockquote><pre> | ||
114 | int 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 | ||
121 | to <b>sqlite_exec</b> This parameter can be used to pass arbitrary | ||
122 | information through to the callback function from client code. | ||
123 | The second argument is the number of columns in the query result. | ||
124 | The third argument is an array of pointers to strings where each string | ||
125 | is a single column of the result for that record. Note that the | ||
126 | callback function reports a NULL value in the database as a NULL pointer, | ||
127 | which is very different from an empty string. If the i-th parameter | ||
128 | is an empty string, we will get:</p> | ||
129 | <blockquote><pre> | ||
130 | argv[i][0] == 0 | ||
131 | </pre></blockquote> | ||
132 | <p>But if the i-th parameter is NULL we will get:</p> | ||
133 | <blockquote><pre> | ||
134 | argv[i] == 0 | ||
135 | </pre></blockquote> | ||
136 | |||
137 | <p>The names of the columns are contained in first <i>argc</i> | ||
138 | entries of the fourth argument. | ||
139 | If the <a href="pragma.html#pragma_show_datatypes">SHOW_DATATYPES</a> pragma | ||
140 | is on (it is off by default) then | ||
141 | the second <i>argc</i> entries in the 4th argument are the datatypes | ||
142 | for the corresponding columns. | ||
143 | </p> | ||
144 | |||
145 | <p>If the <a href="pragma.html#pragma_empty_result_callbacks"> | ||
146 | EMPTY_RESULT_CALLBACKS</a> pragma is set to ON and the result of | ||
147 | a query is an empty set, then the callback is invoked once with the | ||
148 | third parameter (argv) set to 0. In other words | ||
149 | <blockquote><pre> | ||
150 | argv == 0 | ||
151 | </pre></blockquote> | ||
152 | The second parameter (argc) | ||
153 | and the fourth parameter (columnNames) are still valid | ||
154 | and can be used to determine the number and names of the result | ||
155 | columns if there had been a result. | ||
156 | The default behavior is not to invoke the callback at all if the | ||
157 | result set is empty.</p> | ||
158 | |||
159 | <a name="callback_returns_nonzero"> | ||
160 | <p>The callback function should normally return 0. If the callback | ||
161 | function 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> | ||
167 | The <b>sqlite_exec</b> function normally returns SQLITE_OK. But | ||
168 | if something goes wrong it can return a different value to indicate | ||
169 | the 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> | ||
202 | The 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 | ||
212 | the SQLite library failed. This can only happen if there is a bug in | ||
213 | the SQLite library. If you ever get an SQLITE_INTERNAL reply from | ||
214 | an <b>sqlite_exec</b> call, please report the problem on the SQLite | ||
215 | mailing list. | ||
216 | </p></dd> | ||
217 | <dt>SQLITE_ERROR</dt> | ||
218 | <dd><p>This return value indicates that there was an error in the SQL | ||
219 | that 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 | ||
223 | file 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 | ||
230 | the database locked. SQLite allows two or more threads to read the | ||
231 | database at the same time, but only one thread can have the database | ||
232 | open for writing at the same time. Locking in SQLite is on the | ||
233 | entire 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 | ||
237 | that the database is locked. But the source of the lock is a recursive | ||
238 | call to <b>sqlite_exec</b>. This return can only occur if you attempt | ||
239 | to invoke sqlite_exec from within a callback routine of a query | ||
240 | from a prior invocation of sqlite_exec. Recursive calls to | ||
241 | sqlite_exec are allowed as long as they do | ||
242 | not 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 | ||
249 | a 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> | ||
253 | interrupts 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 | ||
257 | that it is unable to perform some disk I/O operation. This could mean | ||
258 | that 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 | ||
262 | working on has become corrupted. Corruption might occur due to a rogue | ||
263 | process writing to the database file or it might happen due to an | ||
264 | perviously undetected logic error in of SQLite. This value is also | ||
265 | returned if a disk I/O error occurs in such a way that SQLite is forced | ||
266 | to leave the database file in a corrupted state. The latter should only | ||
267 | happen 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 | ||
271 | no space left on the disk, or the database is too big to hold any | ||
272 | more information. The latter case should only occur for databases | ||
273 | that 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 | ||
277 | for some reason. | ||
278 | </p></dd> | ||
279 | <dt>SQLITE_PROTOCOL</dt> | ||
280 | <dd><p>This value is returned if some other process is messing with | ||
281 | file locks and has violated the file locking protocol that SQLite uses | ||
282 | on 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 | ||
286 | into memory and uses that schema to parse new SQL statements. If another | ||
287 | process changes the schema, the command currently being processed will | ||
288 | abort because the virtual machine code generated assumed the old | ||
289 | schema. This is the return code for such cases. Retrying the | ||
290 | command 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 | ||
294 | row of a single table. If you attempt to store more than 1 megabyte | ||
295 | in 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 | ||
299 | a 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 | ||
303 | data into a column labeled INTEGER PRIMARY KEY. For most columns, SQLite | ||
304 | ignores the data type and allows any kind of data to be stored. But | ||
305 | an 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 | ||
309 | is 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 | ||
312 | calling <b>sqlite_exec</b> with the same | ||
313 | database 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 | ||
317 | database file that is larger that 2GB on a legacy Unix machine that | ||
318 | lacks large file support. | ||
319 | </p></dd> | ||
320 | <dt>SQLITE_AUTH</dt> | ||
321 | <dd><p>This error indicates that the authorizer callback | ||
322 | has 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. | ||
327 | It 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. | ||
332 | It indicates that the SQL statement has been completely executed and | ||
333 | the <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> | ||
341 | The <b>sqlite_exec</b> routine described above used to be the only | ||
342 | way to retrieve data from an SQLite database. But many programmers found | ||
343 | it inconvenient to use a callback function to obtain results. So beginning | ||
344 | with SQLite version 2.7.7, a second access interface is available that | ||
345 | does not use callbacks. | ||
346 | </p> | ||
347 | |||
348 | <p> | ||
349 | The new interface uses three separate functions to replace the single | ||
350 | <b>sqlite_exec</b> function. | ||
351 | </p> | ||
352 | |||
353 | <blockquote><pre> | ||
354 | typedef struct sqlite_vm sqlite_vm; | ||
355 | |||
356 | int 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 | |||
364 | int 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 | |||
371 | int 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> | ||
378 | The strategy is to compile a single SQL statement using | ||
379 | <b>sqlite_compile</b> then invoke <b>sqlite_step</b> multiple times, | ||
380 | once for each row of output, and finally call <b>sqlite_finalize</b> | ||
381 | to 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> | ||
387 | The <b>sqlite_compile</b> "compiles" a single SQL statement (specified | ||
388 | by the second parameter) and generates a virtual machine that is able | ||
389 | to execute that statement. | ||
390 | As with must interface routines, the first parameter must be a pointer | ||
391 | to an sqlite structure that was obtained from a prior call to | ||
392 | <b>sqlite_open</b>. | ||
393 | |||
394 | <p> | ||
395 | A pointer to the virtual machine is stored in a pointer which is passed | ||
396 | in as the 4th parameter. | ||
397 | Space to hold the virtual machine is dynamically allocated. To avoid | ||
398 | a memory leak, the calling function must invoke | ||
399 | <b>sqlite_finalize</b> on the virtual machine after it has finished | ||
400 | with it. | ||
401 | The 4th parameter may be set to NULL if an error is encountered during | ||
402 | compilation. | ||
403 | </p> | ||
404 | |||
405 | <p> | ||
406 | If any errors are encountered during compilation, an error message is | ||
407 | written into memory obtained from <b>malloc</b> and the 5th parameter | ||
408 | is made to point to that memory. If the 5th parameter is NULL, then | ||
409 | no error message is generated. If the 5th parameter is not NULL, then | ||
410 | the calling function should dispose of the memory containing the error | ||
411 | message by calling <b>sqlite_freemem</b>. | ||
412 | </p> | ||
413 | |||
414 | <p> | ||
415 | If the 2nd parameter actually contains two or more statements of SQL, | ||
416 | only the first statement is compiled. (This is different from the | ||
417 | behavior of <b>sqlite_exec</b> which executes all SQL statements | ||
418 | in its input string.) The 3rd parameter to <b>sqlite_compile</b> | ||
419 | is made to point to the first character beyond the end of the first | ||
420 | statement of SQL in the input. If the 2nd parameter contains only | ||
421 | a single SQL statement, then the 3rd parameter will be made to point | ||
422 | to the '\000' terminator at the end of the 2nd parameter. | ||
423 | </p> | ||
424 | |||
425 | <p> | ||
426 | On success, <b>sqlite_compile</b> returns SQLITE_OK. | ||
427 | Otherwise and error code is returned. | ||
428 | </p> | ||
429 | |||
430 | <h4>2.2 Step-By-Step Execution Of An SQL Statement</h4> | ||
431 | |||
432 | <p> | ||
433 | After a virtual machine has been generated using <b>sqlite_compile</b> | ||
434 | it is executed by one or more calls to <b>sqlite_step</b>. Each | ||
435 | invocation of <b>sqlite_step</b>, except the last one, | ||
436 | returns a single row of the result. | ||
437 | The number of columns in the result is stored in the integer that | ||
438 | the 2nd parameter points to. | ||
439 | The pointer specified by the 3rd parameter is made to point | ||
440 | to an array of pointers to column values. | ||
441 | The pointer in the 4th parameter is made to point to an array | ||
442 | of pointers to column names and datatypes. | ||
443 | The 2nd through 4th parameters to <b>sqlite_step</b> convey the | ||
444 | same information as the 2nd through 4th parameters of the | ||
445 | <b>callback</b> routine when using | ||
446 | the <b>sqlite_exec</b> interface. Except, with <b>sqlite_step</b> | ||
447 | the column datatype information is always included in the in the | ||
448 | 4th parameter regardless of whether or not the | ||
449 | <a href="pragma.html#pragma_show_datatypes">SHOW_DATATYPES</a> pragma | ||
450 | is on or off. | ||
451 | </p> | ||
452 | |||
453 | <p> | ||
454 | Each invocation of <b>sqlite_step</b> returns an integer code that | ||
455 | indicates what happened during that step. This code may be | ||
456 | SQLITE_BUSY, SQLITE_ROW, SQLITE_DONE, SQLITE_ERROR, or | ||
457 | SQLITE_MISUSE. | ||
458 | </p> | ||
459 | |||
460 | <p> | ||
461 | If the virtual machine is unable to open the database file because | ||
462 | it is locked by another thread or process, <b>sqlite_step</b> | ||
463 | will return SQLITE_BUSY. The calling function should do some other | ||
464 | activity, or sleep, for a short amount of time to give the lock a | ||
465 | chance to clear, then invoke <b>sqlite_step</b> again. This can | ||
466 | be repeated as many times as desired. | ||
467 | </p> | ||
468 | |||
469 | <p> | ||
470 | Whenever another row of result data is available, | ||
471 | <b>sqlite_step</b> will return SQLITE_ROW. The row data is | ||
472 | stored in an array of pointers to strings and the 2nd parameter | ||
473 | is made to point to this array. | ||
474 | </p> | ||
475 | |||
476 | <p> | ||
477 | When all processing is complete, <b>sqlite_step</b> will return | ||
478 | either SQLITE_DONE or SQLITE_ERROR. SQLITE_DONE indicates that the | ||
479 | statement completed successfully and SQLITE_ERROR indicates that there | ||
480 | was 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 | ||
482 | to call <b>sqlite_step</b> again after it has returned SQLITE_DONE | ||
483 | or SQLITE_ERROR. | ||
484 | </p> | ||
485 | |||
486 | <p> | ||
487 | When <b>sqlite_step</b> returns SQLITE_DONE or SQLITE_ERROR, | ||
488 | the *pN and *pazColName values are set to the number of columns | ||
489 | in the result set and to the names of the columns, just as they | ||
490 | are for an SQLITE_ROW return. This allows the calling code to | ||
491 | find the number of result columns and the column names and datatypes | ||
492 | even if the result set is empty. The *pazValue parameter is always | ||
493 | set to NULL when the return codes is SQLITE_DONE or SQLITE_ERROR. | ||
494 | If the SQL being executed is a statement that does not | ||
495 | return a result (such as an INSERT or an UPDATE) then *pN will | ||
496 | be set to zero and *pazColName will be set to NULL. | ||
497 | </p> | ||
498 | |||
499 | <p> | ||
500 | If you abuse the library by trying to call <b>sqlite_step</b> | ||
501 | inappropriately it will attempt return SQLITE_MISUSE. | ||
502 | This can happen if you call sqlite_step() on the same virtual machine | ||
503 | at the same | ||
504 | time from two or more threads or if you call sqlite_step() | ||
505 | again after it returned SQLITE_DONE or SQLITE_ERROR or if you | ||
506 | pass in an invalid virtual machine pointer to sqlite_step(). | ||
507 | You should not depend on the SQLITE_MISUSE return code to indicate | ||
508 | an error. It is possible that a misuse of the interface will go | ||
509 | undetected and result in a program crash. The SQLITE_MISUSE is | ||
510 | intended as a debugging aid only - to help you detect incorrect | ||
511 | usage prior to a mishap. The misuse detection logic is not guaranteed | ||
512 | to work in every case. | ||
513 | </p> | ||
514 | |||
515 | <h4>2.3 Deleting A Virtual Machine</h4> | ||
516 | |||
517 | <p> | ||
518 | Every virtual machine that <b>sqlite_compile</b> creates should | ||
519 | eventually be handed to <b>sqlite_finalize</b>. The sqlite_finalize() | ||
520 | procedure deallocates the memory and other resources that the virtual | ||
521 | machine uses. Failure to call sqlite_finalize() will result in | ||
522 | resource leaks in your program. | ||
523 | </p> | ||
524 | |||
525 | <p> | ||
526 | The <b>sqlite_finalize</b> routine also returns the result code | ||
527 | that indicates success or failure of the SQL operation that the | ||
528 | virtual machine carried out. | ||
529 | The value returned by sqlite_finalize() will be the same as would | ||
530 | have been returned had the same SQL been executed by <b>sqlite_exec</b>. | ||
531 | The error message returned will also be the same. | ||
532 | </p> | ||
533 | |||
534 | <p> | ||
535 | It is acceptable to call <b>sqlite_finalize</b> on a virtual machine | ||
536 | before <b>sqlite_step</b> has returned SQLITE_DONE. Doing so has | ||
537 | the effect of interrupting the operation in progress. Partially completed | ||
538 | changes will be rolled back and the database will be restored to its | ||
539 | original state (unless an alternative recovery algorithm is selected using | ||
540 | an ON CONFLICT clause in the SQL being executed.) The effect is the | ||
541 | same as if a callback function of <b>sqlite_exec</b> had returned | ||
542 | non-zero. | ||
543 | </p> | ||
544 | |||
545 | <p> | ||
546 | It is also acceptable to call <b>sqlite_finalize</b> on a virtual machine | ||
547 | that 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 | ||
553 | SQLite. But there are many other functions that provide | ||
554 | useful interfaces. These extended routines are as follows: | ||
555 | </p> | ||
556 | |||
557 | <blockquote><pre> | ||
558 | int sqlite_last_insert_rowid(sqlite*); | ||
559 | |||
560 | int sqlite_changes(sqlite*); | ||
561 | |||
562 | int sqlite_get_table( | ||
563 | sqlite*, | ||
564 | char *sql, | ||
565 | char ***result, | ||
566 | int *nrow, | ||
567 | int *ncolumn, | ||
568 | char **errmsg | ||
569 | ); | ||
570 | |||
571 | void sqlite_free_table(char**); | ||
572 | |||
573 | void sqlite_interrupt(sqlite*); | ||
574 | |||
575 | int sqlite_complete(const char *sql); | ||
576 | |||
577 | void sqlite_busy_handler(sqlite*, int (*)(void*,const char*,int), void*); | ||
578 | |||
579 | void sqlite_busy_timeout(sqlite*, int ms); | ||
580 | |||
581 | const char sqlite_version[]; | ||
582 | |||
583 | const char sqlite_encoding[]; | ||
584 | |||
585 | int sqlite_exec_printf( | ||
586 | sqlite*, | ||
587 | char *sql, | ||
588 | int (*)(void*,int,char**,char**), | ||
589 | void*, | ||
590 | char **errmsg, | ||
591 | ... | ||
592 | ); | ||
593 | |||
594 | int sqlite_exec_vprintf( | ||
595 | sqlite*, | ||
596 | char *sql, | ||
597 | int (*)(void*,int,char**,char**), | ||
598 | void*, | ||
599 | char **errmsg, | ||
600 | va_list | ||
601 | ); | ||
602 | |||
603 | int sqlite_get_table_printf( | ||
604 | sqlite*, | ||
605 | char *sql, | ||
606 | char ***result, | ||
607 | int *nrow, | ||
608 | int *ncolumn, | ||
609 | char **errmsg, | ||
610 | ... | ||
611 | ); | ||
612 | |||
613 | int 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 | |||
623 | char *sqlite_mprintf(const char *zFormat, ...); | ||
624 | |||
625 | char *sqlite_vmprintf(const char *zFormat, va_list); | ||
626 | |||
627 | void sqlite_freemem(char*); | ||
628 | |||
629 | void 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" | ||
634 | header 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 | ||
639 | table has a column labeled INTEGER PRIMARY KEY, then that column | ||
640 | serves as the key. If there is no INTEGER PRIMARY KEY column then | ||
641 | the key is a unique integer. The key for a row can be accessed in | ||
642 | a SELECT statement or used in a WHERE or ORDER BY clause using any | ||
643 | of 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 | ||
646 | KEY column, or if the table does have an INTEGER PRIMARY KEY but the value | ||
647 | for that column is not specified in the VALUES clause of the insert, then | ||
648 | the key is automatically generated. You can find the value of the key | ||
649 | for 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 | ||
655 | that have been inserted, deleted, or modified since the database was | ||
656 | last quiescent. A "quiescent" database is one in which there are | ||
657 | no 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>. | ||
659 | In common usage, <b>sqlite_changes</b> returns the number | ||
660 | of rows inserted, deleted, or modified by the most recent <b>sqlite_exec</b> | ||
661 | call or since the most recent <b>sqlite_compile</b>. But if you have | ||
662 | nested calls to <b>sqlite_exec</b> (that is, if the callback routine | ||
663 | of one <b>sqlite_exec</b> invokes another <b>sqlite_exec</b>) or if | ||
664 | you invoke <b>sqlite_compile</b> to create a new VM while there is | ||
665 | still another VM in existance, then | ||
666 | the meaning of the number returned by <b>sqlite_changes</b> is more | ||
667 | complex. | ||
668 | The number reported includes any changes | ||
669 | that were later undone by a ROLLBACK or ABORT. But rows that are | ||
670 | deleted because of a DROP TABLE are <em>not</em> counted.</p> | ||
671 | |||
672 | <p>SQLite implements the command "<b>DELETE FROM table</b>" (without | ||
673 | a WHERE clause) by dropping the table then recreating it. | ||
674 | This is much faster than deleting the elements of the table individually. | ||
675 | But it also means that the value returned from <b>sqlite_changes</b> | ||
676 | will be zero regardless of the number of elements that were originally | ||
677 | in the table. If an accurate count of the number of elements deleted | ||
678 | is 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 | ||
684 | callbacks and writes it into memory obtained from malloc(). This | ||
685 | is a convenience function that allows the application to get the | ||
686 | entire 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 | ||
689 | to strings. There is one element in this array for each column of | ||
690 | each row in the result. NULL results are represented by a NULL | ||
691 | pointer. In addition to the regular data, there is an added row at the | ||
692 | beginning of the array that contains the name of each column of the | ||
693 | result.</p> | ||
694 | |||
695 | <p>As an example, consider the following query:</p> | ||
696 | |||
697 | <blockquote> | ||
698 | SELECT 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 | ||
702 | for every employee whose login begins with the letter "d". If this | ||
703 | query is submitted to <b>sqlite_get_table</b> the result might | ||
704 | look like this:</p> | ||
705 | |||
706 | <blockquote> | ||
707 | nrow = 2<br> | ||
708 | ncolumn = 3<br> | ||
709 | result[0] = "employee_name"<br> | ||
710 | result[1] = "login"<br> | ||
711 | result[2] = "host"<br> | ||
712 | result[3] = "dummy"<br> | ||
713 | result[4] = "No such user"<br> | ||
714 | result[5] = 0<br> | ||
715 | result[6] = "D. Richard Hipp"<br> | ||
716 | result[7] = "drh"<br> | ||
717 | result[8] = "zadok" | ||
718 | </blockquote> | ||
719 | |||
720 | <p>Notice that the "host" value for the "dummy" record is NULL so | ||
721 | the 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 | ||
725 | result parameter is set to NULL. But if the EMPTY_RESULT_CALLBACKS | ||
726 | pragma is ON then the result parameter is initialized to the names | ||
727 | of the columns only. For example, consider this query which has | ||
728 | an empty result set:</p> | ||
729 | |||
730 | <blockquote> | ||
731 | SELECT employee_name, login, host FROM users WHERE employee_name IS NULL; | ||
732 | </blockquote> | ||
733 | |||
734 | <p> | ||
735 | The default behavior gives this results: | ||
736 | </p> | ||
737 | |||
738 | <blockquote> | ||
739 | nrow = 0<br> | ||
740 | ncolumn = 0<br> | ||
741 | result = 0<br> | ||
742 | </blockquote> | ||
743 | |||
744 | <p> | ||
745 | But if the EMPTY_RESULT_CALLBACKS pragma is ON, then the following | ||
746 | is returned: | ||
747 | </p> | ||
748 | |||
749 | <blockquote> | ||
750 | nrow = 0<br> | ||
751 | ncolumn = 3<br> | ||
752 | result[0] = "employee_name"<br> | ||
753 | result[1] = "login"<br> | ||
754 | result[2] = "host"<br> | ||
755 | </blockquote> | ||
756 | |||
757 | <p>Memory to hold the information returned by <b>sqlite_get_table</b> | ||
758 | is obtained from malloc(). But the calling function should not try | ||
759 | to free this information directly. Instead, pass the complete table | ||
760 | to <b>sqlite_free_table</b> when the table is no longer needed. | ||
761 | It is safe to call <b>sqlite_free_table</b> with a NULL pointer such | ||
762 | as would be returned if the result set is empty.</p> | ||
763 | |||
764 | <p>The <b>sqlite_get_table</b> routine returns the same integer | ||
765 | result 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 | ||
770 | different thread or from a signal handler to cause the current database | ||
771 | operation to exit at its first opportunity. When this happens, | ||
772 | the <b>sqlite_exec</b> routine (or the equivalent) that started | ||
773 | the 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 | ||
778 | to test whether or not a string forms a complete SQL statement. | ||
779 | If the <b>sqlite_complete</b> function returns true when its input | ||
780 | is a string, then the argument forms a complete SQL statement. | ||
781 | There are no guarantees that the syntax of that statement is correct, | ||
782 | but we at least know the statement is complete. If <b>sqlite_complete</b> | ||
783 | returns 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 | ||
786 | statement 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> | ||
789 | function to know when it needs to call <b>sqlite_exec</b>. After each | ||
790 | line of input is received, <b>sqlite</b> calls <b>sqlite_complete</b> | ||
791 | on all input in its buffer. If <b>sqlite_complete</b> returns true, | ||
792 | then <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 | ||
794 | the continuation prompt and another line of text is read and added to | ||
795 | the 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 | ||
801 | library. The header file contains a macro SQLITE_VERSION | ||
802 | with the same information. If desired, a program can compare | ||
803 | the SQLITE_VERSION macro against the <b>sqlite_version</b> | ||
804 | string constant to verify that the version number of the | ||
805 | header 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 | ||
810 | 8-bit character (iso8859). But if you give the --enable-utf8 option | ||
811 | to the configure script, then the library assumes UTF-8 variable | ||
812 | sized characters. This makes a difference for the LIKE and GLOB | ||
813 | operators and the LENGTH() and SUBSTR() functions. The static | ||
814 | string <b>sqlite_encoding</b> will be set to either "UTF-8" or | ||
815 | "iso8859" to indicate how the library was compiled. In addition, | ||
816 | the <b>sqlite.h</b> header file will define one of the | ||
817 | macros <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 | ||
820 | be 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 | ||
822 | was 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 | ||
827 | a busy callback with an open SQLite database. The busy callback will | ||
828 | be invoked whenever SQLite tries to access a database that is locked. | ||
829 | The callback will typically do some other useful work, or perhaps sleep, | ||
830 | in order to give the lock a chance to clear. If the callback returns | ||
831 | non-zero, then SQLite tries again to access the database and the cycle | ||
832 | repeats. If the callback returns zero, then SQLite aborts the current | ||
833 | operation and returns SQLITE_BUSY.</p> | ||
834 | |||
835 | <p>The arguments to <b>sqlite_busy_handler</b> are the opaque | ||
836 | structure returned from <b>sqlite_open</b>, a pointer to the busy | ||
837 | callback function, and a generic pointer that will be passed as | ||
838 | the first argument to the busy callback. When SQLite invokes the | ||
839 | busy callback, it sends it three arguments: the generic pointer | ||
840 | that was passed in as the third argument to <b>sqlite_busy_handler</b>, | ||
841 | the name of the database table or index that the library is trying | ||
842 | to access, and the number of times that the library has attempted to | ||
843 | access the database table or index.</p> | ||
844 | |||
845 | <p>For the common case where we want the busy callback to sleep, | ||
846 | the SQLite library provides a convenience routine <b>sqlite_busy_timeout</b>. | ||
847 | The first argument to <b>sqlite_busy_timeout</b> is a pointer to | ||
848 | an open SQLite database and the second argument is a number of milliseconds. | ||
849 | After <b>sqlite_busy_timeout</b> has been executed, the SQLite library | ||
850 | will wait for the lock to clear for at least the number of milliseconds | ||
851 | specified before it returns SQLITE_BUSY. Specifying zero milliseconds for | ||
852 | the 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> | ||
868 | and <b>sqlite_get_table</b>. But instead of taking a complete | ||
869 | SQL statement as their second argument, the four <b>_printf</b> | ||
870 | routines take a printf-style format string. The SQL statement to | ||
871 | be executed is generated from this format string and from whatever | ||
872 | additional arguments are attached to the end of the function call.</p> | ||
873 | |||
874 | <p>There are two advantages to using the SQLite printf | ||
875 | functions instead of <b>sprintf</b>. First of all, with the | ||
876 | SQLite printf routines, there is never a danger of overflowing a | ||
877 | static buffer as there is with <b>sprintf</b>. The SQLite | ||
878 | printf routines automatically allocate (and later frees) | ||
879 | as much memory as is | ||
880 | necessary 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 | ||
884 | to support string literals in SQL. Within the format string, | ||
885 | the %q formatting option works very much like %s in that it | ||
886 | reads a null-terminated string from the argument list and inserts | ||
887 | it into the result. But %q translates the inserted string by | ||
888 | making two copies of every single-quote (') character in the | ||
889 | substituted string. This has the effect of escaping the end-of-string | ||
890 | meaning of single-quote within a string literal. The %Q formatting | ||
891 | option works similar; it translates the single-quotes like %q and | ||
892 | additionally encloses the resulting string in single-quotes. | ||
893 | If the argument for the %Q formatting options is a NULL pointer, | ||
894 | the resulting string is NULL without single quotes. | ||
895 | </p> | ||
896 | |||
897 | <p>Consider an example. Suppose you are trying to insert a string | ||
898 | value into a database table where the string value was obtained from | ||
899 | user input. Suppose the string to be inserted is stored in a variable | ||
900 | named zString. The code to do the insertion might look like this:</p> | ||
901 | |||
902 | <blockquote><pre> | ||
903 | sqlite_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 | ||
909 | will 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> | ||
913 | INSERT 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". | ||
917 | But if the %q formatting option is used instead of %s, like this:</p> | ||
918 | |||
919 | <blockquote><pre> | ||
920 | sqlite_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> | ||
928 | INSERT 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. | ||
932 | When generating SQL on-the-fly from data that might contain a | ||
933 | single-quote character ('), it is always a good idea to use the | ||
934 | SQLite 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> | ||
940 | sqlite_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> | ||
948 | INSERT INTO table1 VALUES('Hi y''all') | ||
949 | </pre></blockquote> | ||
950 | |||
951 | <p>If the value of the zString variable is NULL, the generated SQL | ||
952 | will look like the following:</p> | ||
953 | |||
954 | <blockquote><pre> | ||
955 | INSERT INTO table1 VALUES(NULL) | ||
956 | </pre></blockquote> | ||
957 | |||
958 | <p>All of the _printf() routines above are built around the following | ||
959 | two functions:</p> | ||
960 | |||
961 | <blockquote><pre> | ||
962 | char *sqlite_mprintf(const char *zFormat, ...); | ||
963 | char *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 | ||
968 | from malloc() and returns a pointer to the malloced buffer. | ||
969 | <b>sqlite_mprintf()</b> also understands the %q and %Q extensions described | ||
970 | above. The <b>sqlite_vmprintf()</b> is a varargs version of the same | ||
971 | routine. The string pointer that these routines return should be freed | ||
972 | by 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 | ||
978 | callback routine with an SQLite database to be invoked periodically during long | ||
979 | running calls to <b>sqlite_exec()</b>, <b>sqlite_step()</b> and the various | ||
980 | wrapper functions. | ||
981 | </p> | ||
982 | |||
983 | <p>The callback is invoked every N virtual machine operations, where N is | ||
984 | supplied as the second argument to <b>sqlite_progress_handler()</b>. The third | ||
985 | and fourth arguments to <b>sqlite_progress_handler()</b> are a pointer to the | ||
986 | routine to be invoked and a void pointer to be passed as the first argument to | ||
987 | it. | ||
988 | </p> | ||
989 | |||
990 | <p>The time taken to execute each virtual machine operation can vary based on | ||
991 | many factors. A typical value for a 1 GHz PC is between half and three million | ||
992 | per second but may be much higher or lower, depending on the query. As such it | ||
993 | is difficult to schedule background operations based on virtual machine | ||
994 | operations. Instead, it is recommended that a callback be scheduled relatively | ||
995 | frequently (say every 1000 instructions) and external timer routines used to | ||
996 | determine 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 | ||
1003 | extended with new functions implemented as C code. The following interface | ||
1004 | is used: | ||
1005 | </p> | ||
1006 | |||
1007 | <blockquote><pre> | ||
1008 | typedef struct sqlite_func sqlite_func; | ||
1009 | |||
1010 | int 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 | ); | ||
1017 | int 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 | |||
1026 | char *sqlite_set_result_string(sqlite_func*,const char*,int); | ||
1027 | void sqlite_set_result_int(sqlite_func*,int); | ||
1028 | void sqlite_set_result_double(sqlite_func*,double); | ||
1029 | void sqlite_set_result_error(sqlite_func*,const char*,int); | ||
1030 | |||
1031 | void *sqlite_user_data(sqlite_func*); | ||
1032 | void *sqlite_aggregate_context(sqlite_func*, int nBytes); | ||
1033 | int sqlite_aggregate_count(sqlite_func*); | ||
1034 | </pre></blockquote> | ||
1035 | |||
1036 | <p> | ||
1037 | The <b>sqlite_create_function()</b> interface is used to create | ||
1038 | regular functions and <b>sqlite_create_aggregate()</b> is used to | ||
1039 | create new aggregate functions. In both cases, the <b>db</b> | ||
1040 | parameter is an open SQLite database on which the functions should | ||
1041 | be 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 | ||
1043 | a pointer which is passed through unchanged to the C implementation | ||
1044 | of the function. Both routines return 0 on success and non-zero | ||
1045 | if there are any errors. | ||
1046 | </p> | ||
1047 | |||
1048 | <p> | ||
1049 | The length of a function name may not exceed 255 characters. | ||
1050 | Any attempt to create a function whose name exceeds 255 characters | ||
1051 | in length will result in an error. | ||
1052 | </p> | ||
1053 | |||
1054 | <p> | ||
1055 | For regular functions, the <b>xFunc</b> callback is invoked once | ||
1056 | for each function call. The implementation of xFunc should call | ||
1057 | one of the <b>sqlite_set_result_...</b> interfaces to return its | ||
1058 | result. The <b>sqlite_user_data()</b> routine can be used to | ||
1059 | retrieve the <b>pUserData</b> pointer that was passed in when the | ||
1060 | function was registered. | ||
1061 | </p> | ||
1062 | |||
1063 | <p> | ||
1064 | For aggregate functions, the <b>xStep</b> callback is invoked once | ||
1065 | for each row in the result and then <b>xFinalize</b> is invoked at the | ||
1066 | end to compute a final answer. The xStep routine can use the | ||
1067 | <b>sqlite_aggregate_context()</b> interface to allocate memory that | ||
1068 | will be unique to that particular instance of the SQL function. | ||
1069 | This memory will be automatically deleted after xFinalize is called. | ||
1070 | The <b>sqlite_aggregate_count()</b> routine can be used to find out | ||
1071 | how many rows of data were passed to the aggregate. The xFinalize | ||
1072 | callback should invoke one of the <b>sqlite_set_result_...</b> | ||
1073 | interfaces to set the final result of the aggregate. | ||
1074 | </p> | ||
1075 | |||
1076 | <p> | ||
1077 | SQLite now implements all of its built-in functions using this | ||
1078 | interface. For additional information and examples on how to create | ||
1079 | new 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> | ||
1086 | If SQLite is compiled with the THREADSAFE preprocessor macro set to 1, | ||
1087 | then it is safe to use SQLite from two or more threads of the same process | ||
1088 | at the same time. But each thread should have its own <b>sqlite*</b> | ||
1089 | pointer returned from <b>sqlite_open</b>. It is never safe for two | ||
1090 | or more threads to access the same <b>sqlite*</b> pointer at the same time. | ||
1091 | </p> | ||
1092 | |||
1093 | <p> | ||
1094 | In precompiled SQLite libraries available on the website, the Unix | ||
1095 | versions are compiled with THREADSAFE turned off but the windows | ||
1096 | versions are compiled with THREADSAFE turned on. If you need something | ||
1097 | different that this you will have to recompile. | ||
1098 | </p> | ||
1099 | |||
1100 | <p> | ||
1101 | Under 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 | ||
1103 | should 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, | ||
1109 | refer to the source code for the <b>sqlite</b> program in the | ||
1110 | file <b>src/shell.c</b> of the source tree. | ||
1111 | Additional information about sqlite is available at | ||
1112 | <a href="sqlite.html">sqlite.html</a>. | ||
1113 | See also the sources to the Tcl interface for SQLite in | ||
1114 | the source file <b>src/tclsqlite.c</b>.</p> | ||
1115 | } | ||
1116 | footer $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 @@ | |||
1 | set rcsid {$Id: capi3.tcl,v 1.10 2007/04/27 17:16:22 drh Exp $} | ||
2 | source common.tcl | ||
3 | header {C/C++ Interface For SQLite Version 3} | ||
4 | |||
5 | proc 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 | |||
11 | AddHyperlinks { | ||
12 | <h2>C/C++ Interface For SQLite Version 3</h2> | ||
13 | |||
14 | <h3>1.0 Overview</h3> | ||
15 | |||
16 | <p> | ||
17 | SQLite version 3.0 is a new version of SQLite, derived from | ||
18 | the SQLite 2.8.13 code base, but with an incompatible file format | ||
19 | and API. | ||
20 | SQLite 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> | ||
30 | It was necessary to move to version 3.0 to implement these features because | ||
31 | each requires incompatible changes to the database file format. Other | ||
32 | incompatible changes, such as a cleanup of the API, were introduced at the | ||
33 | same time under the theory that it is best to get your incompatible changes | ||
34 | out of the way all at once. | ||
35 | </p> | ||
36 | |||
37 | <p> | ||
38 | The API for version 3.0 is similar to the version 2.X API, | ||
39 | but with some important changes. Most noticeably, the "<tt>sqlite_</tt>" | ||
40 | prefix that occurs on the beginning of all API functions and data | ||
41 | structures are changed to "<tt>sqlite3_</tt>". | ||
42 | This avoids confusion between the two APIs and allows linking against both | ||
43 | SQLite 2.X and SQLite 3.0 at the same time. | ||
44 | </p> | ||
45 | |||
46 | <p> | ||
47 | There is no agreement on what the C datatype for a UTF-16 | ||
48 | string should be. Therefore, SQLite uses a generic type of void* | ||
49 | to refer to UTF-16 strings. Client software can cast the void* | ||
50 | to whatever datatype is appropriate for their system. | ||
51 | </p> | ||
52 | |||
53 | <h3>2.0 C/C++ Interface</h3> | ||
54 | |||
55 | <p> | ||
56 | The API for SQLite 3.0 includes 83 separate functions in addition | ||
57 | to several data structures and #defines. (A complete | ||
58 | <a href="capi3ref.html">API reference</a> is provided as a separate document.) | ||
59 | Fortunately, the interface is not nearly as complex as its size implies. | ||
60 | Simple 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>. | ||
64 | More control over the execution of the database engine is provided | ||
65 | using | ||
66 | <a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a> | ||
67 | to compile an SQLite statement into byte code and | ||
68 | <a href="capi3ref.html#sqlite3_prepare">sqlite3_step()</a> | ||
69 | to execute that bytecode. | ||
70 | A family of routines with names beginning with | ||
71 | <a href="capi3ref.html#sqlite3_column_blob">sqlite3_column_</a> | ||
72 | is used to extract information about the result set of a query. | ||
73 | Many interface functions come in pairs, with both a UTF-8 and | ||
74 | UTF-16 version. And there is a collection of routines | ||
75 | used to implement user-defined SQL functions and user-defined | ||
76 | text 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> | ||
93 | The sqlite3_open() routine returns an integer error code rather than | ||
94 | a pointer to the sqlite3 structure as the version 2 interface did. | ||
95 | The difference between sqlite3_open() | ||
96 | and sqlite3_open16() is that sqlite3_open16() takes UTF-16 (in host native | ||
97 | byte order) for the name of the database file. If a new database file | ||
98 | needs to be created, then sqlite3_open16() sets the internal text | ||
99 | representation to UTF-16 whereas sqlite3_open() sets the text | ||
100 | representation to UTF-8. | ||
101 | </p> | ||
102 | |||
103 | <p> | ||
104 | The opening and/or creating of the database file is deferred until the | ||
105 | file is actually needed. This allows options and parameters, such | ||
106 | as the native text representation and default page size, to be | ||
107 | set using PRAGMA statements. | ||
108 | </p> | ||
109 | |||
110 | <p> | ||
111 | The sqlite3_errcode() routine returns a result code for the most | ||
112 | recent major API call. sqlite3_errmsg() returns an English-language | ||
113 | text error message for the most recent error. The error message is | ||
114 | represented in UTF-8 and will be ephemeral - it could disappear on | ||
115 | the next call to any SQLite API function. sqlite3_errmsg16() works like | ||
116 | sqlite3_errmsg() except that it returns the error message represented | ||
117 | as UTF-16 in host native byte order. | ||
118 | </p> | ||
119 | |||
120 | <p> | ||
121 | The error codes for SQLite version 3 are unchanged from version 2. | ||
122 | They 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> | ||
162 | The sqlite3_exec function works much as it did in SQLite version 2. | ||
163 | Zero or more SQL statements specified in the second parameter are compiled | ||
164 | and executed. Query results are returned to a callback routine. | ||
165 | See the <a href="capi3ref.html#sqlite3_exec">API reference</a> for additional | ||
166 | information. | ||
167 | </p> | ||
168 | |||
169 | <p> | ||
170 | In SQLite version 3, the sqlite3_exec routine is just a wrapper around | ||
171 | calls 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> | ||
183 | The sqlite3_prepare interface compiles a single SQL statement into byte code | ||
184 | for later execution. This interface is now the preferred way of accessing | ||
185 | the database. | ||
186 | </p> | ||
187 | |||
188 | <p> | ||
189 | The SQL statement is a UTF-8 string for sqlite3_prepare(). | ||
190 | The sqlite3_prepare16() works the same way except | ||
191 | that it expects a UTF-16 string as SQL input. | ||
192 | Only the first SQL statement in the input string is compiled. | ||
193 | The fourth parameter is filled in with a pointer to the next (uncompiled) | ||
194 | SQLite statement in the input string, if any. | ||
195 | The sqlite3_finalize() routine deallocates a prepared SQL statement. | ||
196 | All prepared statements must be finalized before the database can be | ||
197 | closed. | ||
198 | The sqlite3_reset() routine resets a prepared SQL statement so that it | ||
199 | can be executed again. | ||
200 | </p> | ||
201 | |||
202 | <p> | ||
203 | The SQL statement may contain tokens of the form "?" or "?nnn" or ":aaa" | ||
204 | where "nnn" is an integer and "aaa" is an identifier. | ||
205 | Such tokens represent unspecified literal values (or "wildcards") | ||
206 | to be filled in later by the | ||
207 | <a href="capi3ref.html#sqlite3_bind_blob">sqlite3_bind</a> interface. | ||
208 | Each wildcard has an associated number which is its sequence in the | ||
209 | statement or the "nnn" in the case of a "?nnn" form. | ||
210 | It is allowed for the same wildcard | ||
211 | to occur more than once in the same SQL statement, in which case | ||
212 | all instance of that wildcard will be filled in with the same value. | ||
213 | Unbound 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> | ||
228 | There is an assortment of sqlite3_bind routines used to assign values | ||
229 | to wildcards in a prepared SQL statement. Unbound wildcards | ||
230 | are interpreted as NULLs. Bindings are not reset by sqlite3_reset(). | ||
231 | But wildcards can be rebound to new values after an sqlite3_reset(). | ||
232 | </p> | ||
233 | |||
234 | <p> | ||
235 | After an SQL statement has been prepared (and optionally bound), it | ||
236 | is executed using: | ||
237 | </p> | ||
238 | |||
239 | <blockquote><pre> | ||
240 | int sqlite3_step(sqlite3_stmt*); | ||
241 | </pre></blockquote> | ||
242 | |||
243 | <p> | ||
244 | The sqlite3_step() routine return SQLITE_ROW if it is returning a single | ||
245 | row of the result set, or SQLITE_DONE if execution has completed, either | ||
246 | normally or due to an error. It might also return SQLITE_BUSY if it is | ||
247 | unable to open the database file. If the return value is SQLITE_ROW, then | ||
248 | the following routines can be used to extract information about that row | ||
249 | of 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> | ||
270 | The | ||
271 | <a href="capi3ref.html#sqlite3_column_count">sqlite3_column_count()</a> | ||
272 | function returns the number of columns in | ||
273 | the results set. sqlite3_column_count() can be called at any time after | ||
274 | sqlite3_prepare(). | ||
275 | <a href="capi3ref.html#sqlite3_data_count">sqlite3_data_count()</a> | ||
276 | works similarly to | ||
277 | sqlite3_column_count() except that it only works following sqlite3_step(). | ||
278 | If the previous call to sqlite3_step() returned SQLITE_DONE or an error code, | ||
279 | then sqlite3_data_count() will return 0 whereas sqlite3_column_count() will | ||
280 | continue 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, | ||
284 | all of which take a column number as their second parameter. Columns are | ||
285 | zero-indexed from left to right. Note that this is different to parameters, | ||
286 | which are indexed starting at one. | ||
287 | </p> | ||
288 | |||
289 | <p> | ||
290 | The sqlite3_column_type() function returns the | ||
291 | datatype for the value in the Nth column. The return value is one | ||
292 | of 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> | ||
304 | The sqlite3_column_decltype() routine returns text which is the | ||
305 | declared type of the column in the CREATE TABLE statement. For an | ||
306 | expression, the return type is an empty string. sqlite3_column_name() | ||
307 | returns the name of the Nth column. sqlite3_column_bytes() returns | ||
308 | the number of bytes in a column that has type BLOB or the number of bytes | ||
309 | in a TEXT string with UTF-8 encoding. sqlite3_column_bytes16() returns | ||
310 | the same value for BLOBs but for TEXT strings returns the number of bytes | ||
311 | in a UTF-16 encoding. | ||
312 | sqlite3_column_blob() return BLOB data. | ||
313 | sqlite3_column_text() return TEXT data as UTF-8. | ||
314 | sqlite3_column_text16() return TEXT data as UTF-16. | ||
315 | sqlite3_column_int() return INTEGER data in the host machines native | ||
316 | integer format. | ||
317 | sqlite3_column_int64() returns 64-bit INTEGER data. | ||
318 | Finally, sqlite3_column_double() return floating point data. | ||
319 | </p> | ||
320 | |||
321 | <p> | ||
322 | It is not necessary to retrieve data in the format specify by | ||
323 | sqlite3_column_type(). If a different format is requested, the data | ||
324 | is converted automatically. | ||
325 | </p> | ||
326 | |||
327 | <p> | ||
328 | Data format conversions can invalidate the pointer returned by | ||
329 | prior calls to sqlite3_column_blob(), sqlite3_column_text(), and/or | ||
330 | sqlite3_column_text16(). Pointers might be invalided in the following | ||
331 | cases: | ||
332 | </p> | ||
333 | <ul> | ||
334 | <li><p> | ||
335 | The initial content is a BLOB and sqlite3_column_text() | ||
336 | or sqlite3_column_text16() | ||
337 | is called. A zero-terminator might need to be added to the string. | ||
338 | </p></li> | ||
339 | <li><p> | ||
340 | The initial content is UTF-8 text and sqlite3_column_bytes16() or | ||
341 | sqlite3_column_text16() is called. The content must be converted to UTF-16. | ||
342 | </p></li> | ||
343 | <li><p> | ||
344 | The initial content is UTF-16 text and sqlite3_column_bytes() or | ||
345 | sqlite3_column_text() is called. The content must be converted to UTF-8. | ||
346 | </p></li> | ||
347 | </ul> | ||
348 | <p> | ||
349 | Note that conversions between UTF-16be and UTF-16le | ||
350 | are always done in place and do | ||
351 | not invalidate a prior pointer, though of course the content of the buffer | ||
352 | that the prior pointer points to will have been modified. Other kinds | ||
353 | of conversion are done in place when it is possible, but sometime it is | ||
354 | not possible and in those cases prior pointers are invalidated. | ||
355 | </p> | ||
356 | |||
357 | <p> | ||
358 | The safest and easiest to remember policy is this: assume that any | ||
359 | result from | ||
360 | <ul> | ||
361 | <li>sqlite3_column_blob(),</li> | ||
362 | <li>sqlite3_column_text(), or</li> | ||
363 | <li>sqlite3_column_text16()</li> | ||
364 | </ul> | ||
365 | is 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> | ||
372 | This means that you should always call sqlite3_column_bytes() or | ||
373 | sqlite3_column_bytes16() <u>before</u> calling sqlite3_column_blob(), | ||
374 | sqlite3_column_text(), or sqlite3_column_text16(). | ||
375 | </p> | ||
376 | |||
377 | <h4>2.3 User-defined functions</h4> | ||
378 | |||
379 | <p> | ||
380 | User 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> | ||
413 | The nArg parameter specifies the number of arguments to the function. | ||
414 | A value of 0 indicates that any number of arguments is allowed. The | ||
415 | eTextRep parameter specifies what representation text values are expected | ||
416 | to be in for arguments to this function. The value of this parameter should | ||
417 | be one of the parameters defined above. SQLite version 3 allows multiple | ||
418 | implementations of the same function using different text representations. | ||
419 | The database engine chooses the function that minimization the number | ||
420 | of text conversions required. | ||
421 | </p> | ||
422 | |||
423 | <p> | ||
424 | Normal functions specify only xFunc and leave xStep and xFinal set to NULL. | ||
425 | Aggregate functions specify xStep and xFinal and leave xFunc set to NULL. | ||
426 | There is no separate sqlite3_create_aggregate() API. | ||
427 | </p> | ||
428 | |||
429 | <p> | ||
430 | The function name is specified in UTF-8. A separate sqlite3_create_function16() | ||
431 | API works the same as sqlite_create_function() | ||
432 | except that the function name is specified in UTF-16 host byte order. | ||
433 | </p> | ||
434 | |||
435 | <p> | ||
436 | Notice that the parameters to functions are now pointers to sqlite3_value | ||
437 | structures instead of pointers to strings as in SQLite version 2.X. | ||
438 | The 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> | ||
455 | Function implementations use the following APIs to acquire context and | ||
456 | to 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> | ||
479 | The following routines are used to implement user-defined | ||
480 | collating 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> | ||
495 | The sqlite3_create_collation() function specifies a collating sequence name | ||
496 | and a comparison function to implement that collating sequence. The | ||
497 | comparison function is only used for comparing text values. The eTextRep | ||
498 | parameter is one of SQLITE_UTF8, SQLITE_UTF16LE, SQLITE_UTF16BE, or | ||
499 | SQLITE_ANY to specify which text representation the comparison function works | ||
500 | with. Separate comparison functions can exist for the same collating | ||
501 | sequence for each of the UTF-8, UTF-16LE and UTF-16BE text representations. | ||
502 | The sqlite3_create_collation16() works like sqlite3_create_collation() except | ||
503 | that the collation name is specified in UTF-16 host byte order instead of | ||
504 | in UTF-8. | ||
505 | </p> | ||
506 | |||
507 | <p> | ||
508 | The sqlite3_collation_needed() routine registers a callback which the | ||
509 | database engine will invoke if it encounters an unknown collating sequence. | ||
510 | The callback can lookup an appropriate comparison function and invoke | ||
511 | sqlite_3_create_collation() as needed. The fourth parameter to the callback | ||
512 | is the name of the collating sequence in UTF-8. For sqlite3_collation_need16() | ||
513 | the callback sends the collating sequence name in UTF-16 host byte order. | ||
514 | </p> | ||
515 | } | ||
516 | footer $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 | # | ||
4 | source common.tcl | ||
5 | header {SQLite changes} | ||
6 | puts { | ||
7 | <p> | ||
8 | This page provides a high-level summary of changes to SQLite. | ||
9 | For more detail, refer the the checkin logs generated by | ||
10 | CVS at | ||
11 | <a href="http://www.sqlite.org/cvstrac/timeline"> | ||
12 | http://www.sqlite.org/cvstrac/timeline</a>. | ||
13 | </p> | ||
14 | |||
15 | <DL> | ||
16 | } | ||
17 | |||
18 | |||
19 | proc 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 | |||
31 | chng {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 | |||
53 | chng {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 | |||
78 | chng {2007 August 13 (3.4.2)} { | ||
79 | <li>Fix a database corruption bug that might occur if a ROLLBACK command | ||
80 | is executed in <a href="pragma.html#pragma_auto_vacuum">auto-vacuum mode</a> | ||
81 | and a very small <a href="capi3ref.html#sqlite3_soft_heap_limit"> | ||
82 | soft_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 | ||
96 | are prefixed with either SQLITE_PRIVATE or SQLITE_API. | ||
97 | } | ||
98 | |||
99 | chng {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 | |||
129 | chng {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 | |||
193 | chng {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 | |||
200 | chng {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 | |||
212 | chng {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 | |||
224 | chng {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 | |||
266 | chng {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 | ||
269 | used by an expression. This feature is considered experimental pending | ||
270 | additional 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>. | ||
275 | Their 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 | ||
280 | causing incorrect results for updates on tables with triggers</li> | ||
281 | <li>Fix a bug in the ORDER BY clause optimizer for joins where the | ||
282 | left-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 | |||
287 | chng {2007 January 27 (3.3.12)} { | ||
288 | <li>Fix another bug in the IS NULL optimization that was added in | ||
289 | version 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> | ||
293 | generates.</li> | ||
294 | <li>Minor syntactic changes to support a wider variety of compilers.</li> | ||
295 | } | ||
296 | |||
297 | chng {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. | ||
300 | We'll get it right eventually...</li> | ||
301 | <li>Fix a bug in the IS NULL optimization that was added in version 3.3.9 - | ||
302 | the bug was causing incorrect results on certain LEFT JOINs that included | ||
303 | in the WHERE clause an IS NULL constraint for the right table of the | ||
304 | LEFT JOIN.</li> | ||
305 | <li>Make AreFileApisANSI() a no-op macro in winCE since winCE does not | ||
306 | support this function.</li> | ||
307 | } | ||
308 | |||
309 | chng {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 | ||
312 | that 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"> | ||
315 | strftime()</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 | ||
318 | database 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 | ||
322 | correctly set their column names in the result set</li> | ||
323 | <li>Documentation updates</li> | ||
324 | } | ||
325 | |||
326 | chng {2007 January 4 (3.3.9)} { | ||
327 | <li>Fix bugs in pager.c that could lead to database corruption if two | ||
328 | processes 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> | ||
330 | API.</li> | ||
331 | <li>Fixed the ".dump" command in the command-line shell to show | ||
332 | indices, triggers and views again.</li> | ||
333 | <li>Change the table_info pragma so that it returns NULL for the default | ||
334 | value 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 | ||
339 | clauses 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 | ||
342 | opportunity</li> | ||
343 | <li>The optimizer has more freedom to reorder tables in the FROM clause | ||
344 | even 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 | ||
350 | more 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 | ||
354 | same directory as the original database</li> | ||
355 | <li>The prefix on temporary filenames on windows is changed from "sqlite" | ||
356 | to "etilqs".</li> | ||
357 | } | ||
358 | |||
359 | chng {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 | ||
365 | kinds 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 | |||
374 | chng {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"> | ||
380 | dynamically loaded extensions</a> (beta)</li> | ||
381 | <li>The | ||
382 | <a href="capi3ref.html#sqlite3_interrupt">sqlite3_interrupt()</a> | ||
383 | routine 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 | |||
388 | chng {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 | |||
402 | chng {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 | |||
423 | chng {2006 February 11 (3.3.4)} { | ||
424 | <li>Fix a blunder in the Unix mutex implementation that can lead to | ||
425 | deadlock 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 | ||
429 | to give incorrect results.</li> | ||
430 | <li>The SUM function detects integer overflow and converts to accumulating | ||
431 | an 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 | |||
437 | chng {2006 January 31 (3.3.3)} { | ||
438 | <li>Removed support for an ON CONFLICT clause on CREATE INDEX - it never | ||
439 | worked correctly so this should not present any backward compatibility | ||
440 | problems.</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 | ||
443 | are invalidated and must be recreated using a new call to | ||
444 | sqlite3_prepare()</li> | ||
445 | <li>Other minor bug fixes in preparation for the first stable release | ||
446 | of version 3.3</li> | ||
447 | } | ||
448 | |||
449 | chng {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 | ||
453 | exception handling</li> | ||
454 | } | ||
455 | |||
456 | chng {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 | ||
460 | the thread in which they were created.</li> | ||
461 | } | ||
462 | |||
463 | chng {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 | ||
468 | files</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 | ||
475 | in the same thread</li> | ||
476 | <li>Optional READ UNCOMMITTED isolation (instead of the default | ||
477 | isolation level of SERIALIZABLE) and table level locking when | ||
478 | database connections share a common cache.</li> | ||
479 | } | ||
480 | |||
481 | chng {2005 December 19 (3.2.8)} { | ||
482 | <li>Fix an obscure bug that can cause database corruption under the | ||
483 | following unusual circumstances: A large INSERT or UPDATE statement which | ||
484 | is part of an even larger transaction fails due to a uniqueness contraint | ||
485 | but the containing transaction commits.</li> | ||
486 | } | ||
487 | |||
488 | chng {2005 December 19 (2.8.17)} { | ||
489 | <li>Fix an obscure bug that can cause database corruption under the | ||
490 | following unusual circumstances: A large INSERT or UPDATE statement which | ||
491 | is part of an even larger transaction fails due to a uniqueness contraint | ||
492 | but the containing transaction commits.</li> | ||
493 | } | ||
494 | |||
495 | chng {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 | ||
499 | that lack the fdatasync() function</li> | ||
500 | <li>Now compiles on MSVC++6 again</li> | ||
501 | <li>Fix uninitialized variables causing malfunctions for various obscure | ||
502 | queries</li> | ||
503 | <li>Correctly compute a LEFT OUTER JOINs that is constrained on the | ||
504 | left table only</li> | ||
505 | } | ||
506 | |||
507 | chng {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 | |||
524 | chng {2005 August 27 (3.2.5)} { | ||
525 | <li>Fix a bug effecting DELETE and UPDATE statements that changed | ||
526 | more 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 | ||
530 | operator is constant and the right-hand side is a SELECT statement</li> | ||
531 | <li>The PRAGMA synchronous=off statement now disables syncing of the | ||
532 | master journal file in addition to the normal rollback journals</li> | ||
533 | } | ||
534 | |||
535 | chng {2005 August 24 (3.2.4)} { | ||
536 | <li>Fix a bug introduced in the previous release | ||
537 | that can cause a segfault while generating code | ||
538 | for complex WHERE clauses.</li> | ||
539 | <li>Allow floating point literals to begin or end with a decimal point.</li> | ||
540 | } | ||
541 | |||
542 | chng {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 | ||
545 | functions</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 | ||
548 | operands</li> | ||
549 | <li>Added the ANALYZE command for gathering statistics on indices and | ||
550 | using those statistics when picking an index in the optimizer</li> | ||
551 | <li>Remove the limit (formerly 100) on the number of terms in the | ||
552 | WHERE clause</li> | ||
553 | <li>The right-hand side of the IN operator can now be a list of expressions | ||
554 | instead 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 | ||
557 | better use of indices</li> | ||
558 | <li>The IN operator is now a candidate for optimization even if the left-hand | ||
559 | side is not the left-most term of the index. Multiple IN operators can be | ||
560 | used with the same index.</li> | ||
561 | <li>WHERE clause expressions using BETWEEN and OR are now candidates | ||
562 | for optimization</li> | ||
563 | <li>Added the "case_sensitive_like" pragma and the SQLITE_CASE_SENSITIVE_LIKE | ||
564 | compile-time option to set its default value to "on".</li> | ||
565 | <li>Use indices to help with GLOB expressions and LIKE expressions too | ||
566 | when 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 | |||
572 | chng {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 | ||
576 | up this operator in the standard build but users can add their own using | ||
577 | sqlite3_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 | |||
583 | chng {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 | |||
588 | chng {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 | |||
595 | chng {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 | |||
603 | chng {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 | |||
608 | chng {2005 March 10 (3.1.4)} { | ||
609 | <li>Fix a bug in autovacuum that could cause database corruption if | ||
610 | a CREATE UNIQUE INDEX fails because of a constraint violation. | ||
611 | This problem only occurs if the new autovacuum feature introduced in | ||
612 | version 3.1 is turned on.</li> | ||
613 | <li>The F_FULLSYNC ioctl (currently only supported on OS-X) is disabled | ||
614 | if the synchronous pragma is set to something other than "full".</li> | ||
615 | <li>Add additional forward compatibility to the future version 3.2 database | ||
616 | file 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 | |||
624 | chng {2005 February 19 (3.1.3)} { | ||
625 | <li>Fix a problem with VACUUM on databases from which tables containing | ||
626 | AUTOINCREMENT have been dropped.</li> | ||
627 | <li>Add forward compatibility to the future version 3.2 database file | ||
628 | format.</li> | ||
629 | <li>Documentation updates</li> | ||
630 | } | ||
631 | |||
632 | chng {2005 February 15 (3.1.2)} { | ||
633 | <li>Fix a bug that can lead to database corruption if there are two | ||
634 | open connections to the same database and one connection does a VACUUM | ||
635 | and 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 | |||
643 | chng {2005 February 15 (2.8.16)} { | ||
644 | <li>Fix a bug that can lead to database corruption if there are two | ||
645 | open connections to the same database and one connection does a VACUUM | ||
646 | and 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 | |||
653 | chng {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 | |||
660 | chng {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 | |||
676 | chng {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 | ||
679 | already 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 | ||
683 | characters 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 | ||
688 | make the code footprint smaller.</li> | ||
689 | } | ||
690 | |||
691 | chng {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 | |||
707 | chng {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 | |||
716 | chng {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 | |||
731 | chng {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 | |||
741 | chng {2004 July 22 (2.8.15)} { | ||
742 | <li>This is a maintenance release only. Various minor bugs have been | ||
743 | fixed and some portability enhancements are added.</li> | ||
744 | } | ||
745 | |||
746 | chng {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 | ||
749 | the database.</li> | ||
750 | <li>Various bug fixes and documentation updates.</li> | ||
751 | } | ||
752 | |||
753 | chng {2004 June 30 (3.0.2 beta)} { | ||
754 | <li>The first beta release for SQLite 3.0.</li> | ||
755 | } | ||
756 | |||
757 | chng {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 | |||
763 | chng {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 | |||
777 | chng {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 | |||
793 | chng {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 | |||
809 | chng {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 "<expr> IN <table>" as a shorthand for | ||
816 | "<expr> IN (SELECT * FROM <table>".</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 | |||
821 | chng {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 | |||
826 | chng {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 | |||
839 | chng {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 | |||
851 | chng {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 | |||
859 | chng {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 | |||
874 | chng {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 | |||
889 | chng {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 | |||
900 | chng {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 | |||
907 | chng {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 | |||
918 | chng {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 | |||
923 | chng {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 | |||
938 | chng {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 | |||
944 | chng {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 | |||
954 | chng {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 | |||
959 | chng {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 | |||
971 | chng {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 | |||
982 | chng {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 | |||
993 | chng {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 | |||
999 | chng {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 | |||
1009 | chng {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 | |||
1018 | chng {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 | |||
1027 | chng {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 | |||
1036 | chng {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 | |||
1047 | chng {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 | |||
1053 | chng {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 | |||
1061 | chng {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 | |||
1071 | chng {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 | |||
1078 | chng {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 | |||
1091 | chng {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 | |||
1097 | chng {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 | |||
1111 | chng {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 | |||
1116 | chng {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 | |||
1122 | chng {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 | |||
1133 | chng {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 | |||
1138 | chng {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 | |||
1148 | chng {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 | |||
1161 | chng {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 | |||
1166 | chng {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 | |||
1176 | chng {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 | |||
1185 | chng {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 | |||
1192 | chng {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 | |||
1201 | chng {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 | |||
1209 | chng {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 | |||
1236 | chng {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 | |||
1249 | chng {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 | |||
1256 | chng {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 | |||
1262 | chng {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 | |||
1279 | chng {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 | |||
1286 | chng {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 | |||
1297 | chng {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 | |||
1304 | chng {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 | |||
1311 | chng {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 | |||
1321 | chng {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 | |||
1332 | chng {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 | |||
1342 | chng {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 | |||
1349 | chng {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 | |||
1356 | chng {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 | |||
1366 | chng {2001 Nov 23 (2.1.3)} { | ||
1367 | <li>Fix the behavior of comparison operators | ||
1368 | (ex: "<b><</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 | |||
1374 | chng {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 | |||
1386 | chng {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 | |||
1391 | chng {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 | |||
1398 | chng {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 | |||
1408 | chng {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 | |||
1420 | chng {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 | |||
1427 | chng {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 | |||
1434 | chng {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 | |||
1440 | chng {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>&</b> (bitwise-and) | ||
1447 | <b>|</b> (bitwise-or), <b>~</b> (ones-complement), | ||
1448 | <b><<</b> (shift left), <b>>></b> (shift right).</li> | ||
1449 | <li>Added new functions: <b>round()</b> and <b>abs()</b>.</li> | ||
1450 | } | ||
1451 | |||
1452 | chng {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 | |||
1464 | chng {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 | |||
1476 | chng {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 | |||
1481 | chng {2001 Sep 28 (2.0-alpha-4)} { | ||
1482 | <li>Incorporate makefile patches form A. Rottmann to use LIBTOOL</li> | ||
1483 | } | ||
1484 | |||
1485 | chng {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 | |||
1492 | chng {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 | |||
1503 | chng {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 | |||
1510 | chng {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 | |||
1516 | chng {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 | |||
1525 | chng {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 | |||
1536 | chng {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 | |||
1549 | chng {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 | |||
1558 | chng {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 | |||
1563 | chng {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 | |||
1572 | chng {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 | |||
1580 | chng {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 | |||
1587 | chng {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 | |||
1592 | chng {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 | |||
1598 | chng {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 | |||
1604 | chng {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 | |||
1609 | chng {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 | |||
1616 | chng {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 | |||
1622 | chng {2000 Dec 4 (1.0.16)} { | ||
1623 | <li>Documentation updates. Mostly fixing of typos and spelling errors.</li> | ||
1624 | } | ||
1625 | |||
1626 | chng {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 | |||
1633 | chng {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 | |||
1638 | chng {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 | |||
1645 | chng {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 | |||
1656 | chng {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 | |||
1661 | chng {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 | |||
1669 | chng {2000 Sep 30 (1.0.8)} { | ||
1670 | <li>Begin writing documentation on the TCL interface.</li> | ||
1671 | } | ||
1672 | |||
1673 | chng {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 | |||
1683 | chng {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 | |||
1690 | chng {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 | |||
1697 | chng {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 | |||
1704 | chng {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 | |||
1715 | chng {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 | |||
1720 | chng {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 | |||
1726 | chng {2000 Aug 9} { | ||
1727 | <li>Treat carriage returns as white space.</li> | ||
1728 | } | ||
1729 | |||
1730 | chng {2000 Aug 8} { | ||
1731 | <li>Added pattern matching to the ".table" command in the "sqlite" | ||
1732 | command shell.</li> | ||
1733 | } | ||
1734 | |||
1735 | chng {2000 Aug 4} { | ||
1736 | <li>Documentation updates</li> | ||
1737 | <li>Added "busy" and "timeout" methods to the Tcl interface</li> | ||
1738 | } | ||
1739 | |||
1740 | chng {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 | |||
1745 | chng {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 | |||
1752 | chng {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 | |||
1757 | chng {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 | |||
1764 | chng {2000 July 29} { | ||
1765 | <li>Better labels on column names of the result.</li> | ||
1766 | } | ||
1767 | |||
1768 | chng {2000 July 28} { | ||
1769 | <li>Added the <b>sqlite_busy_handler()</b> | ||
1770 | and <b>sqlite_busy_timeout()</b> interface.</li> | ||
1771 | } | ||
1772 | |||
1773 | chng {2000 June 23} { | ||
1774 | <li>Begin writing the <a href="vdbe.html">VDBE tutorial</a>.</li> | ||
1775 | } | ||
1776 | |||
1777 | chng {2000 June 21} { | ||
1778 | <li>Clean up comments and variable names. Changes to documentation. | ||
1779 | No functional changes to the code.</li> | ||
1780 | } | ||
1781 | |||
1782 | chng {2000 June 19} { | ||
1783 | <li>Column names in UPDATE statements were case sensitive. | ||
1784 | This mistake has now been fixed.</li> | ||
1785 | } | ||
1786 | |||
1787 | chng {2000 June 16} { | ||
1788 | <li>Added the concatenate string operator (||)</li> | ||
1789 | } | ||
1790 | |||
1791 | chng {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 | |||
1801 | chng {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 | |||
1807 | chng {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 | |||
1817 | chng {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 | ||
1820 | improved tests.</li> | ||
1821 | } | ||
1822 | |||
1823 | chng {2000 June 2} { | ||
1824 | <li>All database files to be modified by an UPDATE, INSERT or DELETE are | ||
1825 | now locked before any changes are made to any files. | ||
1826 | This makes it safe (I think) to access | ||
1827 | the same database simultaneously from multiple processes.</li> | ||
1828 | <li>The code appears stable so we are now calling it "beta".</li> | ||
1829 | } | ||
1830 | |||
1831 | chng {2000 June 1} { | ||
1832 | <li>Better support for file locking so that two or more processes | ||
1833 | (or threads) | ||
1834 | can access the same database simultaneously. More work needed in | ||
1835 | this area, though.</li> | ||
1836 | } | ||
1837 | |||
1838 | chng {2000 May 31} { | ||
1839 | <li>Added support for aggregate functions (Ex: <b>COUNT(*)</b>, <b>MIN(...)</b>) | ||
1840 | to the SELECT statement.</li> | ||
1841 | <li>Added support for <B>SELECT DISTINCT ...</B></li> | ||
1842 | } | ||
1843 | |||
1844 | chng {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> | ||
1847 | but it uses Unix shell globbing wildcards instead of the '%' | ||
1848 | and '_' 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 | ||
1851 | can now read the output of the <b>pg_dump</b> database dump utility | ||
1852 | of PostgreSQL.</li> | ||
1853 | <li>Added a <B>VACUUM</B> command that that calls the | ||
1854 | <b>gdbm_reorganize()</b> function on the underlying database | ||
1855 | files.</li> | ||
1856 | <li>And many, many bug fixes...</li> | ||
1857 | } | ||
1858 | |||
1859 | chng {2000 May 29} { | ||
1860 | <li>Initial Public Release of Alpha code</li> | ||
1861 | } | ||
1862 | |||
1863 | puts { | ||
1864 | </DL> | ||
1865 | } | ||
1866 | footer {$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 | |||
5 | proc 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 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 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 | |||
50 | proc 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 | # | ||
66 | proc 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> ::=</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\\ \\ \\ \\ " 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 | # | ||
4 | set rcsid {$Id: compile.tcl,v 1.5 2005/03/19 15:10:45 drh Exp $ } | ||
5 | source common.tcl | ||
6 | header {Compilation Options For SQLite} | ||
7 | |||
8 | puts { | ||
9 | <h1>Compilation Options For SQLite</h1> | ||
10 | |||
11 | <p> | ||
12 | For most purposes, SQLite can be built just fine using the default | ||
13 | compilation options. However, if required, the compile-time options | ||
14 | documented below can be used to | ||
15 | <a href="#omitfeatures">omit SQLite features</a> (resulting in | ||
16 | a smaller compiled library size) or to change the | ||
17 | <a href="#defaults">default values</a> of some parameters. | ||
18 | </p> | ||
19 | <p> | ||
20 | Every effort has been made to ensure that the various combinations | ||
21 | of compilation options work harmoniously and produce a working library. | ||
22 | Nevertheless, it is strongly recommended that the SQLite test-suite | ||
23 | be executed to check for errors before using an SQLite library built | ||
24 | with 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><1 or 0></i></b><br> | ||
30 | This macro determines if SQLite creates databases with the | ||
31 | <a href="pragma.html#pragma_auto_vacuum">auto-vacuum</a> | ||
32 | flag set by default. The default value is 0 (do not create auto-vacuum | ||
33 | databases). 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><pages></i></b><br> | ||
38 | This macro sets the default size of the page-cache for each attached | ||
39 | database, in pages. This can be overridden by the "PRAGMA cache_size" | ||
40 | comamnd. The default value is 2000. | ||
41 | </p> | ||
42 | |||
43 | <p><b>SQLITE_DEFAULT_PAGE_SIZE=<i><bytes></i></b><br> | ||
44 | This macro is used to set the default page-size used when a | ||
45 | database is created. The value assigned must be a power of 2. The | ||
46 | default value is 1024. The compile-time default may be overridden at | ||
47 | runtime by the "PRAGMA page_size" command. | ||
48 | </p> | ||
49 | |||
50 | <p><b>SQLITE_DEFAULT_TEMP_CACHE_SIZE=<i><pages></i></b><br> | ||
51 | This macro sets the default size of the page-cache for temporary files | ||
52 | created by SQLite to store intermediate results, in pages. It does | ||
53 | not affect the page-cache for the temp database, where tables created | ||
54 | using "CREATE TEMP TABLE" are stored. The default value is 500. | ||
55 | </p> | ||
56 | |||
57 | <p><b>SQLITE_MAX_PAGE_SIZE=<i><bytes></i></b><br> | ||
58 | This is used to set the maximum allowable page-size that can | ||
59 | be specified by the "PRAGMA page_size" command. The default value | ||
60 | is 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 | ||
67 | library by omiting optional features. This is probably only useful | ||
68 | in embedded systems where space is especially tight, as even with all | ||
69 | features included the SQLite library is relatively small. Don't forget | ||
70 | to tell your compiler to optimize for binary size! (the -Os option if | ||
71 | using GCC).</p> | ||
72 | |||
73 | <p>The macros in this section do not require values. The following | ||
74 | compilation 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 | ||
81 | options must also be defined when using the 'lemon' tool to generate a parse.c | ||
82 | file. Because of this, these options may only used when the library is built | ||
83 | from source, not from the collection of pre-packaged C files provided for | ||
84 | non-UNIX like platforms on the website. | ||
85 | </p> | ||
86 | |||
87 | <p><b>SQLITE_OMIT_ALTERTABLE</b><br> | ||
88 | When this option is defined, the | ||
89 | <a href="lang_altertable.html">ALTER TABLE</a> command is not included in the | ||
90 | library. Executing an ALTER TABLE statement causes a parse error. | ||
91 | </p> | ||
92 | |||
93 | <p><b>SQLITE_OMIT_AUTHORIZATION</b><br> | ||
94 | Defining this option omits the authorization callback feature from the | ||
95 | library. The <a href="capi3ref.html#sqlite3_set_authorizer"> | ||
96 | sqlite3_set_authorizer()</a> API function is not present in the library. | ||
97 | </p> | ||
98 | |||
99 | <p><b>SQLITE_OMIT_AUTOVACUUM</b><br> | ||
100 | If this option is defined, the library cannot create or write to | ||
101 | databases 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 | ||
104 | or modify the auto-vacuum flag in the database file. If a database that | ||
105 | supports auto-vacuum is opened by a library compiled with this option, it | ||
106 | is automatically opened in read-only mode. | ||
107 | </p> | ||
108 | |||
109 | <p><b>SQLITE_OMIT_AUTOINCREMENT</b><br> | ||
110 | This option is used to omit the AUTOINCREMENT functionality. When this | ||
111 | is macro is defined, columns declared as "INTEGER PRIMARY KEY AUTOINCREMENT" | ||
112 | behave in the same way as columns declared as "INTEGER PRIMARY KEY" when a | ||
113 | NULL is inserted. The sqlite_sequence system table is neither created, nor | ||
114 | respected 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> | ||
119 | When this option is defined, it is not possible to specify a blob in | ||
120 | an 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> | ||
127 | puts { | ||
128 | |||
129 | <p><b>SQLITE_OMIT_COMPLETE</b><br> | ||
130 | This option causes the <a href="capi3ref.html#sqlite3_complete"> | ||
131 | sqlite3_complete</a> API to be omitted. | ||
132 | </p> | ||
133 | |||
134 | <p><b>SQLITE_OMIT_COMPOUND_SELECT</b><br> | ||
135 | This option is used to omit the compound SELECT functionality. | ||
136 | <a href="lang_select.html">SELECT statements</a> that use the | ||
137 | UNION, UNION ALL, INTERSECT or EXCEPT compound SELECT operators will | ||
138 | cause a parse error. | ||
139 | </p> | ||
140 | |||
141 | <p><b>SQLITE_OMIT_CONFLICT_CLAUSE</b><br> | ||
142 | In 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> | ||
147 | If this option is defined, SQLite's built-in date and time manipulation | ||
148 | functions are omitted. Specifically, the SQL functions julianday(), date(), | ||
149 | time(), datetime() and strftime() are not available. The default column | ||
150 | values CURRENT_TIME, CURRENT_DATE and CURRENT_DATETIME are still available. | ||
151 | </p> | ||
152 | |||
153 | <p><b>SQLITE_OMIT_EXPLAIN</b><br> | ||
154 | Defining this option causes the EXPLAIN command to be omitted from the | ||
155 | library. Attempting to execute an EXPLAIN statement will cause a parse | ||
156 | error. | ||
157 | </p> | ||
158 | |||
159 | <p><b>SQLITE_OMIT_FLOATING_POINT</b><br> | ||
160 | This option is used to omit floating-point number support from the SQLite | ||
161 | library. 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 | ||
165 | functionality, for example the sqlite3_result_double(), | ||
166 | sqlite3_bind_double(), sqlite3_value_double() and sqlite3_column_double() | ||
167 | API functions. | ||
168 | </p> | ||
169 | |||
170 | <p><b>SQLITE_OMIT_FOREIGN_KEY</b><br> | ||
171 | If this option is defined, FOREIGN KEY clauses in column declarations are | ||
172 | ignored. | ||
173 | </p> | ||
174 | |||
175 | <p><b>SQLITE_OMIT_INTEGRITY_CHECK</b><br> | ||
176 | This option may be used to omit the | ||
177 | <a href="pragma.html#pragma_integrity_check">"PRAGMA integrity_check"</a> | ||
178 | command from the compiled library. | ||
179 | </p> | ||
180 | |||
181 | <p><b>SQLITE_OMIT_MEMORYDB</b><br> | ||
182 | When this is defined, the library does not respect the special database | ||
183 | name ":memory:" (normally used to create an in-memory database). If | ||
184 | ":memory:" is passed to sqlite3_open(), a file with this name will be | ||
185 | opened or created. | ||
186 | </p> | ||
187 | |||
188 | <p><b>SQLITE_OMIT_PAGER_PRAGMAS</b><br> | ||
189 | Defining this option omits pragmas related to the pager subsystem from | ||
190 | the 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> | ||
196 | This option is used to omit the <a href="pragma.html">PRAGMA command</a> | ||
197 | from the library. Note that it is useful to define the macros that omit | ||
198 | specific pragmas in addition to this, as they may also remove supporting code | ||
199 | in other sub-systems. This macro removes the PRAGMA command only. | ||
200 | </p> | ||
201 | |||
202 | <p><b>SQLITE_OMIT_PROGRESS_CALLBACK</b><br> | ||
203 | This option may be defined to omit the capability to issue "progress" | ||
204 | callbacks during long-running SQL statements. The | ||
205 | <a href="capi3ref.html#sqlite3_progress_handler">sqlite3_progress_handler()</a> | ||
206 | API function is not present in the library. | ||
207 | |||
208 | <p><b>SQLITE_OMIT_REINDEX</b><br> | ||
209 | When this option is defined, the <a href="lang_reindex.html">REINDEX</a> | ||
210 | command is not included in the library. Executing a REINDEX statement causes | ||
211 | a parse error. | ||
212 | </p> | ||
213 | |||
214 | <p><b>SQLITE_OMIT_SCHEMA_PRAGMAS</b><br> | ||
215 | Defining this option omits pragmas for querying the database schema from | ||
216 | the 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> | ||
221 | pragmas are omitted. | ||
222 | </p> | ||
223 | |||
224 | <p><b>SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS</b><br> | ||
225 | Defining this option omits pragmas for querying and modifying the | ||
226 | database 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> | ||
229 | pragmas 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 | ||
237 | used to automatically bind SQL variables to TCL variables is omitted. | ||
238 | </p> | ||
239 | |||
240 | <p><b>SQLITE_OMIT_TRIGGER</b><br> | ||
241 | Defining 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> | ||
244 | commands are available in this case, attempting to execute either will result | ||
245 | in a parse error. | ||
246 | </p> | ||
247 | <p> | ||
248 | WARNING: If this macro is defined, it will not be possible to open a database | ||
249 | for which the schema contains TRIGGER objects. | ||
250 | </p> | ||
251 | |||
252 | <p><b>SQLITE_OMIT_UTF16</b><br> | ||
253 | This macro is used to omit support for UTF16 text encoding. When this is | ||
254 | defined all API functions that return or accept UTF16 encoded text are | ||
255 | unavailable. These functions can be identified by the fact that they end | ||
256 | with '16', for example sqlite3_prepare16(), sqlite3_column_text16() and | ||
257 | sqlite3_bind_text16(). | ||
258 | </p> | ||
259 | |||
260 | <p><b>SQLITE_OMIT_VACUUM</b><br> | ||
261 | When this option is defined, the <a href="lang_vacuum.html">VACUUM</a> | ||
262 | command is not included in the library. Executing a VACUUM statement causes | ||
263 | a parse error. | ||
264 | </p> | ||
265 | |||
266 | <p><b>SQLITE_OMIT_VIEW</b><br> | ||
267 | Defining 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> | ||
270 | commands are available in this case, attempting to execute either will result | ||
271 | in a parse error. | ||
272 | </p> | ||
273 | <p> | ||
274 | WARNING: If this macro is defined, it will not be possible to open a database | ||
275 | for which the schema contains VIEW objects. | ||
276 | </p> | ||
277 | } | ||
278 | footer $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 | # | ||
4 | set rcsid {$Id: conflict.tcl,v 1.4 2004/10/10 17:24:55 drh Exp $ } | ||
5 | source common.tcl | ||
6 | header {Constraint Conflict Resolution in SQLite} | ||
7 | puts { | ||
8 | <h1>Constraint Conflict Resolution in SQLite</h1> | ||
9 | |||
10 | <p> | ||
11 | In most SQL databases, if you have a UNIQUE constraint on | ||
12 | a table and you try to do an UPDATE or INSERT that violates | ||
13 | the constraint, the database will abort the operation in | ||
14 | progress, back out any prior changes associated with | ||
15 | UPDATE or INSERT command, and return an error. | ||
16 | This is the default behavior of SQLite. | ||
17 | Beginning with version 2.3.0, though, SQLite allows you to | ||
18 | define alternative ways for dealing with constraint violations. | ||
19 | This article describes those alternatives and how to use them. | ||
20 | </p> | ||
21 | |||
22 | <h2>Conflict Resolution Algorithms</h2> | ||
23 | |||
24 | <p> | ||
25 | SQLite defines five constraint conflict resolution algorithms | ||
26 | as follows: | ||
27 | </p> | ||
28 | |||
29 | <dl> | ||
30 | <dt><b>ROLLBACK</b></dt> | ||
31 | <dd><p>When a constraint violation occurs, an immediate ROLLBACK | ||
32 | occurs, thus ending the current transaction, and the command aborts | ||
33 | with a return code of SQLITE_CONSTRAINT. If no transaction is | ||
34 | active (other than the implied transaction that is created on every | ||
35 | command) 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 | ||
39 | any prior changes it might have made and aborts with a return code | ||
40 | of SQLITE_CONSTRAINT. But no ROLLBACK is executed so changes | ||
41 | from prior commands within the same transaction | ||
42 | are 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 | ||
46 | return code SQLITE_CONSTRAINT. But any changes to the database that | ||
47 | the command made prior to encountering the constraint violation | ||
48 | are preserved and are not backed out. For example, if an UPDATE | ||
49 | statement encountered a constraint violation on the 100th row that | ||
50 | it attempts to update, then the first 99 row changes are preserved | ||
51 | by 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 | ||
55 | the constraint violation is not inserted or changed. But the command | ||
56 | continues executing normally. Other rows before and after the row that | ||
57 | contained the constraint violation continue to be inserted or updated | ||
58 | normally. 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 | ||
62 | that caused the constraint violation is removed prior to inserting | ||
63 | or updating the current row. Thus the insert or update always occurs. | ||
64 | The 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 | ||
70 | couple of reasons. First, SQLite tries to be roughly compatible with as | ||
71 | many other SQL databases as possible, but different SQL database | ||
72 | engines exhibit different conflict resolution strategies. For | ||
73 | example, PostgreSQL always uses ROLLBACK, Oracle always uses ABORT, and | ||
74 | MySQL usually uses FAIL but can be instructed to use IGNORE or REPLACE. | ||
75 | By supporting all five alternatives, SQLite provides maximum | ||
76 | portability.</p> | ||
77 | |||
78 | <p>Another reason for supporting multiple algorithms is that sometimes | ||
79 | it is useful to use an algorithm other than the default. | ||
80 | Suppose, for example, you are | ||
81 | inserting 1000 records into a database, all within a single | ||
82 | transaction, but one of those records is malformed and causes | ||
83 | a constraint error. Under PostgreSQL or Oracle, none of the | ||
84 | 1000 records would get inserted. In MySQL, some subset of the | ||
85 | records that appeared before the malformed record would be inserted | ||
86 | but the rest would not. Neither behavior is especially helpful. | ||
87 | What you really want is to use the IGNORE algorithm to insert | ||
88 | all but the malformed record.</p> | ||
89 | |||
90 | } | ||
91 | footer $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"> | ||
4 | Copyright Release for<br> | ||
5 | Contributions To SQLite | ||
6 | </h1> | ||
7 | |||
8 | <p> | ||
9 | SQLite is software that implements an embeddable SQL database engine. | ||
10 | SQLite is available for free download from http://www.sqlite.org/. | ||
11 | The principal author and maintainer of SQLite has disclaimed all | ||
12 | copyright interest in his contributions to SQLite | ||
13 | and thus released his contributions into the public domain. | ||
14 | In order to keep the SQLite software unencumbered by copyright | ||
15 | claims, the principal author asks others who may from time to | ||
16 | time contribute changes and enhancements to likewise disclaim | ||
17 | their own individual copyright interest. | ||
18 | </p> | ||
19 | |||
20 | <p> | ||
21 | Because the SQLite software found at http://www.sqlite.org/ is in the | ||
22 | public domain, anyone is free to download the SQLite software | ||
23 | from that website, make changes to the software, use, distribute, | ||
24 | or sell the modified software, under either the original name or | ||
25 | under some new name, without any need to obtain permission, pay | ||
26 | royalties, acknowledge the original source of the software, or | ||
27 | in any other way compensate, identify, or notify the original authors. | ||
28 | Nobody is in any way compelled to contribute their SQLite changes and | ||
29 | enhancements back to the SQLite website. This document concerns | ||
30 | only changes and enhancements to SQLite that are intentionally and | ||
31 | deliberately contributed back to the SQLite website. | ||
32 | </p> | ||
33 | |||
34 | <p> | ||
35 | For the purposes of this document, "SQLite software" shall mean any | ||
36 | computer source code, documentation, makefiles, test scripts, or | ||
37 | other information that is published on the SQLite website, | ||
38 | http://www.sqlite.org/. Precompiled binaries are excluded from | ||
39 | the definition of "SQLite software" in this document because the | ||
40 | process of compiling the software may introduce information from | ||
41 | outside sources which is not properly a part of SQLite. | ||
42 | </p> | ||
43 | |||
44 | <p> | ||
45 | The header comments on the SQLite source files exhort the reader to | ||
46 | share freely and to never take more than one gives. | ||
47 | In the spirit of that exhortation I make the following declarations: | ||
48 | </p> | ||
49 | |||
50 | <ol> | ||
51 | <li><p> | ||
52 | I dedicate to the public domain | ||
53 | any and all copyright interest in the SQLite software that | ||
54 | was publicly available on the SQLite website (http://www.sqlite.org/) prior | ||
55 | to the date of the signature below and any changes or enhancements to | ||
56 | the SQLite software | ||
57 | that I may cause to be published on that website in the future. | ||
58 | I make this dedication for the benefit of the public at large and | ||
59 | to the detriment of my heirs and successors. I intend this | ||
60 | dedication to be an overt act of relinquishment in perpetuity of | ||
61 | all present and future rights to the SQLite software under copyright | ||
62 | law. | ||
63 | </p></li> | ||
64 | |||
65 | <li><p> | ||
66 | To the best of my knowledge and belief, the changes and enhancements that | ||
67 | I have contributed to SQLite are either originally written by me | ||
68 | or are derived from prior works which I have verified are also | ||
69 | in the public domain and are not subject to claims of copyright | ||
70 | by other parties. | ||
71 | </p></li> | ||
72 | |||
73 | <li><p> | ||
74 | To the best of my knowledge and belief, no individual, business, organization, | ||
75 | government, or other entity has any copyright interest | ||
76 | in the SQLite software as it existed on the | ||
77 | SQLite website as of the date on the signature line below. | ||
78 | </p></li> | ||
79 | |||
80 | <li><p> | ||
81 | I agree never to publish any additional information | ||
82 | to the SQLite website (by CVS, email, scp, FTP, or any other means) unless | ||
83 | that information is an original work of authorship by me or is derived from | ||
84 | prior published versions of SQLite. | ||
85 | I agree never to copy and paste code into the SQLite code base from | ||
86 | other sources. | ||
87 | I agree never to publish on the SQLite website any information that | ||
88 | would 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"> | ||
96 | Signature: | ||
97 | <p> </p> | ||
98 | <p> </p> | ||
99 | <p> </p> | ||
100 | </td><td valign="top" align="left"> | ||
101 | Date: | ||
102 | </td></tr> | ||
103 | <td colspan=2> | ||
104 | Name (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 @@ | |||
1 | set rcsid {$Id: copyright.tcl,v 1.7 2007/05/06 21:20:43 drh Exp $} | ||
2 | source common.tcl | ||
3 | header {SQLite Copyright} | ||
4 | puts { | ||
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> | ||
10 | SQLite 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> | ||
16 | All of the deliverable code in SQLite has been dedicated to the | ||
17 | <a href="http://en.wikipedia.org/wiki/Public_Domain">public domain</a> | ||
18 | by the authors. | ||
19 | All code authors, and representatives of the companies they work for, | ||
20 | have signed affidavits dedicating their contributions to | ||
21 | the public domain and originals of | ||
22 | those signed affidavits are stored in a firesafe at the main offices | ||
23 | of <a href="http://www.hwaci.com">Hwaci</a>. | ||
24 | Anyone is free to copy, modify, publish, use, compile, sell, or distribute | ||
25 | the original SQLite code, either in source code form or as a compiled binary, | ||
26 | for any purpose, commercial or non-commercial, and by any means. | ||
27 | </p> | ||
28 | |||
29 | <p> | ||
30 | The previous paragraph applies to the deliverable code in SQLite - | ||
31 | those parts of the SQLite library that you actually bundle and | ||
32 | ship with a larger application. Portions of the documentation and | ||
33 | some code used as part of the build process might fall under | ||
34 | other licenses. The details here are unclear. We do not worry | ||
35 | about the licensing of the documentation and build code so much | ||
36 | because none of these things are part of the core deliverable | ||
37 | SQLite library. | ||
38 | </p> | ||
39 | |||
40 | <p> | ||
41 | All of the deliverable code in SQLite has been written from scratch. | ||
42 | No code has been taken from other projects or from the open | ||
43 | internet. Every line of code can be traced back to its original | ||
44 | author, and all of those authors have public domain dedications | ||
45 | on file. So the SQLite code base is clean and is | ||
46 | uncontaminated with licensed code from other projects. | ||
47 | </p> | ||
48 | |||
49 | <h2>Obtaining An Explicit License To Use SQLite</h2> | ||
50 | |||
51 | <p> | ||
52 | Even though SQLite is in the public domain and does not require | ||
53 | a license, some users want to obtain a license anyway. Some reasons | ||
54 | for 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> | ||
71 | If 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 | ||
73 | the architect and principal developers of SQLite, will sell you | ||
74 | one. | ||
75 | Please contact: | ||
76 | </p> | ||
77 | |||
78 | <blockquote> | ||
79 | D. Richard Hipp <br /> | ||
80 | Hwaci - Applied Software Research <br /> | ||
81 | 704.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> | ||
88 | In order to keep SQLite completely free and unencumbered by copyright, | ||
89 | all new contributors to the SQLite code base are asked to dedicate | ||
90 | their contributions to the public domain. | ||
91 | If you want to send a patch or enhancement for possible inclusion in the | ||
92 | SQLite source tree, please accompany the patch with the following statement: | ||
93 | </p> | ||
94 | |||
95 | <blockquote><i> | ||
96 | The author or authors of this code dedicate any and all copyright interest | ||
97 | in this code to the public domain. We make this dedication for the benefit | ||
98 | of the public at large and to the detriment of our heirs and successors. | ||
99 | We intend this dedication to be an overt act of relinquishment in | ||
100 | perpetuity of all present and future rights to this code under copyright law. | ||
101 | </i></blockquote> | ||
102 | |||
103 | <p> | ||
104 | We are not able to accept patches or changes to | ||
105 | SQLite that are not accompanied by a statement such as the above. | ||
106 | In addition, if you make | ||
107 | changes or enhancements as an employee, then a simple statement such as the | ||
108 | above is insufficient. You must also send by surface mail a copyright release | ||
109 | signed by a company officer. | ||
110 | A signed original of the copyright release should be mailed to:</p> | ||
111 | |||
112 | <blockquote> | ||
113 | Hwaci<br> | ||
114 | 6200 Maple Cove Lane<br> | ||
115 | Charlotte, NC 28269<br> | ||
116 | USA | ||
117 | </blockquote> | ||
118 | |||
119 | <p> | ||
120 | A template copyright release is available | ||
121 | in <a href="copyright-release.pdf">PDF</a> or | ||
122 | <a href="copyright-release.html">HTML</a>. | ||
123 | You can use this release to make future changes. | ||
124 | </p> | ||
125 | } | ||
126 | footer $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 @@ | |||
1 | set rcsid {$Id: datatype3.tcl,v 1.17 2007/06/20 16:13:23 drh Exp $} | ||
2 | source common.tcl | ||
3 | header {Datatypes In SQLite Version 3} | ||
4 | puts { | ||
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. | ||
10 | Version 3 enhances this by providing the ability to store integer and | ||
11 | real numbers in a more compact format and the capability to store | ||
12 | BLOB data.</P> | ||
13 | |||
14 | <P>Each value stored in an SQLite database (or manipulated by the | ||
15 | database 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 | ||
29 | PRIMARY KEY may be used to store any type of value. The exception to | ||
30 | this rule is described below under 'Strict Affinity Mode'.</P> | ||
31 | |||
32 | <P>All values supplied to SQLite, whether as literals embedded in SQL | ||
33 | statements or values bound to pre-compiled SQL statements | ||
34 | are assigned a storage class before the SQL statement is executed. | ||
35 | Under circumstances described below, the | ||
36 | database 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 | ||
54 | operator depends on the outermost operator of the expression. | ||
55 | User-defined functions may return values with any storage class. It | ||
56 | is not generally possible to determine the storage class of the | ||
57 | result of an expression at compile time.</P> | ||
58 | |||
59 | <a name="affinity"> | ||
60 | <h3>2. Column Affinity</h3> | ||
61 | |||
62 | <p> | ||
63 | In SQLite version 3, the type of a value is associated with the value | ||
64 | itself, 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"> | ||
67 | manifest typing</a>.) | ||
68 | All other SQL databases engines that we are aware of use the more | ||
69 | restrictive system of static typing where the type is associated with | ||
70 | the container, not the value. | ||
71 | </p> | ||
72 | |||
73 | <p> | ||
74 | In order to maximize compatibility between SQLite and other database | ||
75 | engines, SQLite support the concept of "type affinity" on columns. | ||
76 | The type affinity of a column is the recommended type for data stored | ||
77 | in that column. The key here is that the type is recommended, not | ||
78 | required. Any column can still store any type of data, in theory. | ||
79 | It is just that some columns, given the choice, will prefer to use | ||
80 | one storage class over another. The preferred storage class for | ||
81 | a column is called its "affinity". | ||
82 | </p> | ||
83 | |||
84 | <P>Each column in an SQLite 3 database is assigned one of the | ||
85 | following 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 | ||
95 | NULL, TEXT or BLOB. If numerical data is inserted into a column with | ||
96 | TEXT 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 | ||
99 | storage classes. When text data is inserted into a NUMERIC column, an | ||
100 | attempt is made to convert it to an integer or real number before it | ||
101 | is stored. If the conversion is successful, then the value is stored | ||
102 | using the INTEGER or REAL storage class. If the conversion cannot be | ||
103 | performed the value is stored using the TEXT storage class. No | ||
104 | attempt 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 | ||
107 | column with NUMERIC affinity, except that if a real value with no | ||
108 | floating point component (or text value that converts to such) is | ||
109 | inserted it is converted to an integer and stored using the INTEGER | ||
110 | storage class.</P> | ||
111 | |||
112 | <P>A column with REAL affinity behaves like a column with NUMERIC | ||
113 | affinity except that it forces integer values into floating point | ||
114 | representation. (As an optimization, integer values are stored on | ||
115 | disk as integers in order to take up less space and are only converted | ||
116 | to 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 | ||
119 | another. It makes no attempt to coerce data before | ||
120 | it 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 | ||
125 | of the column, according to the following rules:</P> | ||
126 | <OL> | ||
127 | <LI><P>If the datatype contains the string "INT" then it | ||
128 | is assigned INTEGER affinity.</P> | ||
129 | |||
130 | <LI><P>If the datatype of the column contains any of the strings | ||
131 | "CHAR", "CLOB", or "TEXT" then that | ||
132 | column has TEXT affinity. Notice that the type VARCHAR contains the | ||
133 | string "CHAR" and is thus assigned TEXT affinity.</P> | ||
134 | |||
135 | <LI><P>If the datatype for a column | ||
136 | contains the string "BLOB" 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 "REAL", "FLOA", | ||
141 | or "DOUB" 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 <table> AS | ||
147 | SELECT..." statement, then all columns have no datatype specified | ||
148 | and 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 | ||
162 | INSERT INTO t1 VALUES('500.0', '500.0', '500.0', '500.0'); | ||
163 | |||
164 | -- Storage classes for the following row: | ||
165 | -- TEXT, REAL, INTEGER, REAL | ||
166 | INSERT 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 | ||
174 | features the binary comparison operators '=', | ||
175 | '<', '<=', '>=' and '!=', an operation to test for set | ||
176 | membership, 'IN', and the ternary comparison operator 'BETWEEN'.</P> | ||
177 | <P>The results of a comparison depend on the storage classes of the | ||
178 | two 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 | ||
197 | classes (INTEGER and REAL) and TEXT before performing a comparison. | ||
198 | For binary comparisons, this is done in the cases enumerated below. | ||
199 | The term "expression" used in the bullet points below means any | ||
200 | SQL scalar expression or literal other than a column value. Note that | ||
201 | if X and Y.Z are a column names, then +X and +Y.Z are considered | ||
202 | expressions.</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> | ||
220 | In SQLite, the expression "a BETWEEN b AND c" is equivalent to "a >= b | ||
221 | AND a <= 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 | ||
226 | rules enumerated above for binary comparisons (e.g. in a | ||
227 | similar manner to "a = b"). For example if 'b' is a column value | ||
228 | and 'a' is an expression, then the affinity of 'b' is applied to 'a' | ||
229 | before any comparisons take place.</P> | ||
230 | |||
231 | <P>SQLite treats the expression "a IN (x, y, z)" as equivalent to "a = +x OR | ||
232 | a = +y OR a = +z". The values to the right of the IN operator (the "x", "y", | ||
233 | and "z" values in this example) are considered to be expressions, even if they | ||
234 | happen to be column values. If the value of the left of the IN operator is | ||
235 | a column, then the affinity of that column is used. If the value is an | ||
236 | expression then no conversions occur. | ||
237 | </P> | ||
238 | |||
239 | <h4>3.1 Comparison Example</h4> | ||
240 | |||
241 | <blockquote> | ||
242 | <PRE> | ||
243 | CREATE TABLE t1( | ||
244 | a TEXT, | ||
245 | b NUMERIC, | ||
246 | c BLOB | ||
247 | ); | ||
248 | |||
249 | -- Storage classes for the following row: | ||
250 | -- TEXT, REAL, TEXT | ||
251 | INSERT INTO t1 VALUES('500', '500', '500'); | ||
252 | |||
253 | -- 60 and 40 are converted to '60' and '40' and values are compared as TEXT. | ||
254 | SELECT a < 60, a < 40 FROM t1; | ||
255 | 1|0 | ||
256 | |||
257 | -- Comparisons are numeric. No conversions are required. | ||
258 | SELECT b < 60, b < 600 FROM t1; | ||
259 | 0|1 | ||
260 | |||
261 | -- Both 60 and 600 (storage class NUMERIC) are less than '500' | ||
262 | -- (storage class TEXT). | ||
263 | SELECT c < 60, c < 600 FROM t1; | ||
264 | 0|0 | ||
265 | </PRE> | ||
266 | </blockquote> | ||
267 | <h3>4. Operators</h3> | ||
268 | |||
269 | <P>All mathematical operators (which is to say, all operators other | ||
270 | than the concatenation operator "||") apply NUMERIC | ||
271 | affinity to all operands prior to being carried out. If one or both | ||
272 | operands cannot be converted to NUMERIC then the result of the | ||
273 | operation is NULL.</P> | ||
274 | |||
275 | <P>For the concatenation operator, TEXT affinity is applied to both | ||
276 | operands. If either operand cannot be converted to TEXT (because it | ||
277 | is 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 | ||
282 | class NULL come first, followed by INTEGER and REAL values | ||
283 | interspersed in numeric order, followed by TEXT values usually in | ||
284 | memcmp() order, and finally BLOB values in memcmp() order. No storage | ||
285 | class conversions occur before the sort.</P> | ||
286 | |||
287 | <P>When grouping values with the GROUP BY clause values with | ||
288 | different storage classes are considered distinct, except for INTEGER | ||
289 | and REAL values which are considered equal if they are numerically | ||
290 | equal. No affinities are applied to any values as the result of a | ||
291 | GROUP by clause.</P> | ||
292 | |||
293 | <P>The compound SELECT operators UNION, | ||
294 | INTERSECT and EXCEPT perform implicit comparisons between values. | ||
295 | Before these comparisons are performed an affinity may be applied to | ||
296 | each value. The same affinity, if any, is applied to all values that | ||
297 | may be returned in a single column of the compound SELECT result set. | ||
298 | The affinity applied is the affinity of the column returned by the | ||
299 | left most component SELECTs that has a column value (and not some | ||
300 | other kind of expression) in that position. If for a given compound | ||
301 | SELECT column none of the component SELECTs return a column value, no | ||
302 | affinity is applied to the values from that column before they are | ||
303 | compared.</P> | ||
304 | |||
305 | <h3>6. Other Affinity Modes</h3> | ||
306 | |||
307 | <P>The above sections describe the operation of the database engine | ||
308 | in 'normal' affinity mode. SQLite version 3 will feature two other affinity | ||
309 | modes, 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> | ||
325 | By default, when SQLite compares two text values, the result of the | ||
326 | comparison is determined using memcmp(), regardless of the encoding of the | ||
327 | string. SQLite v3 provides the ability for users to supply arbitrary | ||
328 | comparison functions, known as user-defined collation sequences, to be used | ||
329 | instead of memcmp(). | ||
330 | </p> | ||
331 | <p> | ||
332 | Aside from the default collation sequence BINARY, implemented using | ||
333 | memcmp(), SQLite features one extra built-in collation sequences | ||
334 | intended 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> | ||
348 | Each column of each table has a default collation type. If a collation type | ||
349 | other 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> | ||
354 | Whenever two text values are compared by SQLite, a collation sequence is | ||
355 | used to determine the results of the comparison according to the following | ||
356 | rules. Sections 3 and 5 of this document describe the circumstances under | ||
357 | which such a comparison takes place. | ||
358 | </p> | ||
359 | |||
360 | <p> | ||
361 | For binary comparison operators (=, <, >, <= and >=) if either operand is a | ||
362 | column, then the default collation type of the column determines the | ||
363 | collation sequence to use for the comparison. If both operands are columns, | ||
364 | then the collation type for the left operand determines the collation | ||
365 | sequence used. If neither operand is a column, then the BINARY collation | ||
366 | sequence is used. For the purposes of this paragraph, a column name | ||
367 | preceded by one or more unary "+" operators is considered a column name. | ||
368 | </p> | ||
369 | |||
370 | <p> | ||
371 | The expression "x BETWEEN y and z" is equivalent to "x >= y AND x <= | ||
372 | z". The expression "x IN (SELECT y ...)" is handled in the same way as the | ||
373 | expression "x = y" for the purposes of determining the collation sequence | ||
374 | to 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 | ||
376 | otherwise. | ||
377 | </p> | ||
378 | |||
379 | <p> | ||
380 | An <a href="lang_select.html">ORDER BY</a> clause that is part of a SELECT | ||
381 | statement may be assigned a collation sequence to be used for the sort | ||
382 | operation explicitly. In this case the explicit collation sequence is | ||
383 | always used. Otherwise, if the expression sorted by an ORDER BY clause is | ||
384 | a column, then the default collation type of the column is used to | ||
385 | determine sort order. If the expression is not a column, then the BINARY | ||
386 | collation sequence is used. | ||
387 | </p> | ||
388 | |||
389 | <h4>7.2 Collation Sequences Example</h4> | ||
390 | <p> | ||
391 | The examples below identify the collation sequences that would be used to | ||
392 | determine the results of text comparisons that may be performed by various | ||
393 | SQL statements. Note that a text comparison may not be required, and no | ||
394 | collation sequence used, in the case of numeric, blob or NULL values. | ||
395 | </p> | ||
396 | <blockquote> | ||
397 | <PRE> | ||
398 | CREATE 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. | ||
406 | SELECT (a = b) FROM t1; | ||
407 | |||
408 | -- Text comparison is performed using the NOCASE collation sequence. | ||
409 | SELECT (d = a) FROM t1; | ||
410 | |||
411 | -- Text comparison is performed using the BINARY collation sequence. | ||
412 | SELECT (a = d) FROM t1; | ||
413 | |||
414 | -- Text comparison is performed using the REVERSE collation sequence. | ||
415 | SELECT ('abc' = c) FROM t1; | ||
416 | |||
417 | -- Text comparison is performed using the REVERSE collation sequence. | ||
418 | SELECT (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). | ||
422 | SELECT count(*) GROUP BY d FROM t1; | ||
423 | |||
424 | -- Grouping is performed using the BINARY collation sequence. | ||
425 | SELECT count(*) GROUP BY (d || '') FROM t1; | ||
426 | |||
427 | -- Sorting is performed using the REVERSE collation sequence. | ||
428 | SELECT * FROM t1 ORDER BY c; | ||
429 | |||
430 | -- Sorting is performed using the BINARY collation sequence. | ||
431 | SELECT * FROM t1 ORDER BY (c || ''); | ||
432 | |||
433 | -- Sorting is performed using the NOCASE collation sequence. | ||
434 | SELECT * FROM t1 ORDER BY c COLLATE NOCASE; | ||
435 | |||
436 | </PRE> | ||
437 | </blockquote> | ||
438 | |||
439 | } | ||
440 | footer $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 | # | ||
4 | set rcsid {$Id: datatypes.tcl,v 1.8 2004/10/10 17:24:55 drh Exp $} | ||
5 | source common.tcl | ||
6 | header {Datatypes In SQLite version 2} | ||
7 | puts { | ||
8 | <h2>Datatypes In SQLite Version 2</h2> | ||
9 | |||
10 | <h3>1.0 Typelessness</h3> | ||
11 | <p> | ||
12 | SQLite is "typeless". This means that you can store any | ||
13 | kind of data you want in any column of any table, regardless of the | ||
14 | declared datatype of that column. | ||
15 | (See the one exception to this rule in section 2.0 below.) | ||
16 | This behavior is a feature, not | ||
17 | a bug. A database is suppose to store and retrieve data and it | ||
18 | should not matter to the database what format that data is in. | ||
19 | The strong typing system found in most other SQL engines and | ||
20 | codified in the SQL language spec is a misfeature - | ||
21 | it is an example of the implementation showing through into the | ||
22 | interface. SQLite seeks to overcome this misfeature by allowing | ||
23 | you to store any kind of data into any kind of column and by | ||
24 | allowing flexibility in the specification of datatypes. | ||
25 | </p> | ||
26 | |||
27 | <p> | ||
28 | A datatype to SQLite is any sequence of zero or more names | ||
29 | optionally followed by a parenthesized lists of one or two | ||
30 | signed integers. Notice in particular that a datatype may | ||
31 | be <em>zero</em> or more names. That means that an empty | ||
32 | string is a valid datatype as far as SQLite is concerned. | ||
33 | So you can declare tables where the datatype of each column | ||
34 | is left unspecified, like this: | ||
35 | </p> | ||
36 | |||
37 | <blockquote><pre> | ||
38 | CREATE TABLE ex1(a,b,c); | ||
39 | </pre></blockquote> | ||
40 | |||
41 | <p> | ||
42 | Even though SQLite allows the datatype to be omitted, it is | ||
43 | still a good idea to include it in your CREATE TABLE statements, | ||
44 | since the data type often serves as a good hint to other | ||
45 | programmers about what you intend to put in the column. And | ||
46 | if you ever port your code to another database engine, that | ||
47 | other engine will probably require a datatype of some kind. | ||
48 | SQLite accepts all the usual datatypes. For example: | ||
49 | </p> | ||
50 | |||
51 | <blockquote><pre> | ||
52 | CREATE 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> | ||
69 | And so forth. Basically any sequence of names optionally followed by | ||
70 | one or two signed integers in parentheses will do. | ||
71 | </p> | ||
72 | |||
73 | <h3>2.0 The INTEGER PRIMARY KEY</h3> | ||
74 | |||
75 | <p> | ||
76 | One exception to the typelessness of SQLite is a column whose type | ||
77 | is INTEGER PRIMARY KEY. (And you must use "INTEGER" not "INT". | ||
78 | A column of type INT PRIMARY KEY is typeless just like any other.) | ||
79 | INTEGER PRIMARY KEY columns must contain a 32-bit signed integer. Any | ||
80 | attempt to insert non-integer data will result in an error. | ||
81 | </p> | ||
82 | |||
83 | <p> | ||
84 | INTEGER PRIMARY KEY columns can be used to implement the equivalent | ||
85 | of AUTOINCREMENT. If you try to insert a NULL into an INTEGER PRIMARY | ||
86 | KEY column, the column will actually be filled with a integer that is | ||
87 | one greater than the largest key already in the table. Or if the | ||
88 | largest key is 2147483647, then the column will be filled with a | ||
89 | random integer. Either way, the INTEGER PRIMARY KEY column will be | ||
90 | assigned a unique integer. You can retrieve this integer using | ||
91 | the <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 Comparison and Sort Order</h3> | ||
96 | |||
97 | <p> | ||
98 | SQLite is typeless for the purpose of deciding what data is allowed | ||
99 | to be stored in a column. But some notion of type comes into play | ||
100 | when sorting and comparing data. For these purposes, a column or | ||
101 | an expression can be one of two types: <b>numeric</b> and <b>text</b>. | ||
102 | The sort or comparison may give different results depending on which | ||
103 | type of data is being sorted or compared. | ||
104 | </p> | ||
105 | |||
106 | <p> | ||
107 | If data is of type <b>text</b> then the comparison is determined by | ||
108 | the standard C data comparison functions <b>memcmp()</b> or | ||
109 | <b>strcmp()</b>. The comparison looks at bytes from two inputs one | ||
110 | by one and returns the first non-zero difference. | ||
111 | Strings are '\000' terminated so shorter | ||
112 | strings sort before longer strings, as you would expect. | ||
113 | </p> | ||
114 | |||
115 | <p> | ||
116 | For numeric data, this situation is more complex. If both inputs | ||
117 | look like well-formed numbers, then they are converted | ||
118 | into floating point values using <b>atof()</b> and compared numerically. | ||
119 | If one input is not a well-formed number but the other is, then the | ||
120 | number is considered to be less than the non-number. If neither inputs | ||
121 | is a well-formed number, then <b>strcmp()</b> is used to do the | ||
122 | comparison. | ||
123 | </p> | ||
124 | |||
125 | <p> | ||
126 | Do not be confused by the fact that a column might have a "numeric" | ||
127 | datatype. This does not mean that the column can contain only numbers. | ||
128 | It merely means that if the column does contain a number, that number | ||
129 | will sort in numerical order. | ||
130 | </p> | ||
131 | |||
132 | <p> | ||
133 | For both text and numeric values, NULL sorts before any other value. | ||
134 | A comparison of any value against NULL using operators like "<" or | ||
135 | ">=" is always false. | ||
136 | </p> | ||
137 | |||
138 | <h3>4.0 How SQLite Determines Datatypes</h3> | ||
139 | |||
140 | <p> | ||
141 | For SQLite version 2.6.3 and earlier, all values used the numeric datatype. | ||
142 | The text datatype appears in version 2.7.0 and later. In the sequel it | ||
143 | is assumed that you are using version 2.7.0 or later of SQLite. | ||
144 | </p> | ||
145 | |||
146 | <p> | ||
147 | For an expression, the datatype of the result is often determined by | ||
148 | the outermost operator. For example, arithmetic operators ("+", "*", "%") | ||
149 | always return a numeric results. The string concatenation operator | ||
150 | ("||") returns a text result. And so forth. If you are ever in doubt | ||
151 | about the datatype of an expression you can use the special <b>typeof()</b> | ||
152 | SQL function to determine what the datatype is. For example: | ||
153 | </p> | ||
154 | |||
155 | <blockquote><pre> | ||
156 | sqlite> SELECT typeof('abc'+123); | ||
157 | numeric | ||
158 | sqlite> SELECT typeof('abc'||123); | ||
159 | text | ||
160 | </pre></blockquote> | ||
161 | |||
162 | <p> | ||
163 | For table columns, the datatype is determined by the type declaration | ||
164 | of the CREATE TABLE statement. The datatype is text if and only if | ||
165 | the type declaration contains one or more of the following strings: | ||
166 | </p> | ||
167 | |||
168 | <blockquote> | ||
169 | BLOB<br> | ||
170 | CHAR<br> | ||
171 | CLOB</br> | ||
172 | TEXT | ||
173 | </blockquote> | ||
174 | |||
175 | <p> | ||
176 | The search for these strings in the type declaration is case insensitive, | ||
177 | of course. If any of the above strings occur anywhere in the type | ||
178 | declaration, then the datatype of the column is text. Notice that | ||
179 | the type "VARCHAR" contains "CHAR" as a substring so it is considered | ||
180 | text.</p> | ||
181 | |||
182 | <p>If none of the strings above occur anywhere in the type declaration, | ||
183 | then the datatype is numeric. Note in particular that the datatype for columns | ||
184 | with an empty type declaration is numeric. | ||
185 | </p> | ||
186 | |||
187 | <h3>5.0 Examples</h3> | ||
188 | |||
189 | <p> | ||
190 | Consider the following two command sequences: | ||
191 | </p> | ||
192 | |||
193 | <blockquote><pre> | ||
194 | CREATE TABLE t1(a INTEGER UNIQUE); CREATE TABLE t2(b TEXT UNIQUE); | ||
195 | INSERT INTO t1 VALUES('0'); INSERT INTO t2 VALUES(0); | ||
196 | INSERT 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, | ||
200 | the strings '0' and '0.0' are treated as numbers since they are being | ||
201 | inserted into a numeric column but 0==0.0 which violates the uniqueness | ||
202 | constraint. However, the second insert in the right-hand sequence works. In | ||
203 | this case, the constants 0 and 0.0 are treated a strings which means that | ||
204 | they are distinct.</p> | ||
205 | |||
206 | <p>SQLite always converts numbers into double-precision (64-bit) floats | ||
207 | for comparison purposes. This means that a long sequence of digits that | ||
208 | differ only in insignificant digits will compare equal if they | ||
209 | are in a numeric column but will compare unequal if they are in a text | ||
210 | column. We have:</p> | ||
211 | |||
212 | <blockquote><pre> | ||
213 | INSERT INTO t1 INSERT INTO t2 | ||
214 | VALUES('12345678901234567890'); VALUES(12345678901234567890); | ||
215 | INSERT 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 | ||
220 | will convert both strings into floating-point number first and the only | ||
221 | difference in the strings is in the 20-th digit which exceeds the resolution | ||
222 | of a 64-bit float. In contrast, the second insert on the right will work | ||
223 | because in that case, the numbers being inserted are strings and are | ||
224 | compared using memcmp().</p> | ||
225 | |||
226 | <p> | ||
227 | Numeric and text types make a difference for the DISTINCT keyword too: | ||
228 | </p> | ||
229 | |||
230 | <blockquote><pre> | ||
231 | CREATE TABLE t3(a INTEGER); CREATE TABLE t4(b TEXT); | ||
232 | INSERT INTO t3 VALUES('0'); INSERT INTO t4 VALUES(0); | ||
233 | INSERT INTO t3 VALUES('0.0'); INSERT INTO t4 VALUES(0.0); | ||
234 | SELECT DISTINCT * FROM t3; SELECT DISTINCT * FROM t4; | ||
235 | </pre></blockquote> | ||
236 | |||
237 | <p> | ||
238 | The SELECT statement on the left returns a single row since '0' and '0.0' | ||
239 | are treated as numbers and are therefore indistinct. But the SELECT | ||
240 | statement on the right returns two rows since 0 and 0.0 are treated | ||
241 | a strings which are different.</p> | ||
242 | } | ||
243 | footer $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 @@ | |||
1 | set rcsid {$Id: different.tcl,v 1.8 2006/12/18 14:12:21 drh Exp $} | ||
2 | source common.tcl | ||
3 | header {Distinctive Features Of SQLite} | ||
4 | puts { | ||
5 | <p> | ||
6 | This page highlights some of the characteristics of SQLite that are | ||
7 | unusual and which make SQLite different from many other SQL | ||
8 | database engines. | ||
9 | </p> | ||
10 | } | ||
11 | proc 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 | |||
17 | feature 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 | |||
36 | feature 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 | |||
65 | feature 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 | |||
82 | feature 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 | |||
98 | feature 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 | |||
122 | feature 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 | |||
144 | feature 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 | |||
151 | feature 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 | |||
182 | feature 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 | |||
207 | feature 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 | |||
224 | footer $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 | # | ||
4 | set rcsid {$Id: docs.tcl,v 1.14 2006/01/30 16:20:30 drh Exp $} | ||
5 | source common.tcl | ||
6 | header {SQLite Documentation} | ||
7 | puts { | ||
8 | <h2>Available Documentation</h2> | ||
9 | <table width="100%" cellpadding="5"> | ||
10 | } | ||
11 | |||
12 | proc doc {name url desc} { | ||
13 | puts {<tr><td valign="top" align="right">} | ||
14 | regsub -all { +} $name {\ } 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 | |||
22 | doc {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 | |||
28 | doc {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 | |||
33 | doc {SQLite In 5 Minutes Or Less} {quickstart.html} { | ||
34 | A very quick introduction to programming with SQLite. | ||
35 | } | ||
36 | |||
37 | doc {SQL Syntax} {lang.html} { | ||
38 | This document describes the SQL language that is understood by | ||
39 | SQLite. | ||
40 | } | ||
41 | doc {Version 3 C/C++ API<br>Reference} {capi3ref.html} { | ||
42 | This document describes each API function separately. | ||
43 | } | ||
44 | doc {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 | } | ||
49 | doc {Tcl API} {tclsqlite.html} { | ||
50 | A description of the TCL interface bindings for SQLite. | ||
51 | } | ||
52 | |||
53 | doc {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 | } | ||
58 | doc {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 | |||
63 | doc {Pragma commands} {pragma.html} { | ||
64 | This document describes SQLite performance tuning options and other | ||
65 | special purpose database commands. | ||
66 | } | ||
67 | doc {SQLite Version 3} {version3.html} { | ||
68 | A summary of of the changes between SQLite version 2.8 and SQLite version 3.0. | ||
69 | } | ||
70 | doc {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 | } | ||
74 | doc {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 | |||
81 | doc {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 | |||
86 | doc {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 | |||
92 | doc {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 | |||
98 | doc {Copyright} {copyright.html} { | ||
99 | SQLite is in the public domain. This document describes what that means | ||
100 | and the implications for contributors. | ||
101 | } | ||
102 | |||
103 | doc {Unsupported SQL} {omitted.html} { | ||
104 | This page describes features of SQL that SQLite does not support. | ||
105 | } | ||
106 | |||
107 | doc {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 | |||
113 | doc {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 | |||
118 | doc {Release History} {changes.html} { | ||
119 | A chronology of SQLite releases going back to version 1.0.0 | ||
120 | } | ||
121 | |||
122 | |||
123 | doc {Speed Comparison} {speed.html} { | ||
124 | The speed of version 2.7.6 of SQLite is compared against PostgreSQL and | ||
125 | MySQL. | ||
126 | } | ||
127 | |||
128 | doc {Architecture} {arch.html} { | ||
129 | An architectural overview of the SQLite library, useful for those who want | ||
130 | to hack the code. | ||
131 | } | ||
132 | |||
133 | doc {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 | |||
140 | doc {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 | |||
147 | doc {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 | |||
153 | doc {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 | |||
158 | puts {</table>} | ||
159 | footer $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 | # | ||
4 | set rcsid {$Id: download.tcl,v 1.27 2007/05/08 18:30:36 drh Exp $} | ||
5 | source common.tcl | ||
6 | header {SQLite Download Page} | ||
7 | |||
8 | puts { | ||
9 | <h2>SQLite Download Page</h1> | ||
10 | <table width="100%" cellpadding="5"> | ||
11 | } | ||
12 | |||
13 | proc 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 | } | ||
39 | cd doc | ||
40 | |||
41 | proc Heading {title} { | ||
42 | puts "<tr><td colspan=4><big><b>$title</b></big></td></tr>" | ||
43 | } | ||
44 | |||
45 | Heading {Precompiled Binaries for Linux} | ||
46 | |||
47 | Product 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 | |||
53 | Product 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 | |||
59 | Product 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 | |||
66 | Product sqlite-V3.so.gz { | ||
67 | A precompiled shared-library for Linux without the TCL bindings. | ||
68 | } | ||
69 | |||
70 | Product 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 | |||
76 | Product 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 | |||
82 | Product sqlite-devel-V3.i386.rpm { | ||
83 | RPM containing documentation, header files, and static library for | ||
84 | SQLite version VERSION. | ||
85 | } | ||
86 | Product 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 | |||
91 | Product sqlite*_analyzer-V3.bin.gz { | ||
92 | An analysis program for database files compatible with SQLite | ||
93 | version VERSION and later. | ||
94 | } | ||
95 | |||
96 | Heading {Precompiled Binaries For Windows} | ||
97 | |||
98 | Product 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 | } | ||
102 | Product 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 | } | ||
108 | Product 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 | |||
113 | Product 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 | |||
119 | Product 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 | |||
125 | Product sqlite*_analyzer-V3.zip { | ||
126 | An analysis program for database files compatible with SQLite version | ||
127 | VERSION and later. | ||
128 | } | ||
129 | |||
130 | |||
131 | Heading {Source Code} | ||
132 | |||
133 | Product {sqlite-V3.tar.gz} { | ||
134 | A tarball of the complete source tree for SQLite version VERSION | ||
135 | including all of the documentation. | ||
136 | } | ||
137 | |||
138 | Product {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 | |||
146 | Product {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 | |||
153 | Product {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 | |||
159 | Product {sqlite-V3.src.rpm} { | ||
160 | An RPM containing complete source code for SQLite version VERSION | ||
161 | } | ||
162 | |||
163 | Heading {Cross-Platform Binaries} | ||
164 | |||
165 | Product {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 | |||
171 | Heading {Historical Binaries And Source Code} | ||
172 | |||
173 | Product sqlite-V2.bin.gz { | ||
174 | A command-line program for accessing and modifying | ||
175 | SQLite version 2.* databases on Linux-x86. | ||
176 | } | ||
177 | Product sqlite-V2.zip { | ||
178 | A command-line program for accessing and modifying | ||
179 | SQLite version 2.* databases on win32. | ||
180 | } | ||
181 | |||
182 | Product sqlite*_analyzer-V2.bin.gz { | ||
183 | An analysis program for version 2.* database files on Linux-x86 | ||
184 | } | ||
185 | Product sqlite*_analyzer-V2.zip { | ||
186 | An analysis program for version 2.* database files on win32. | ||
187 | } | ||
188 | Product {sqlite-source-V2.zip} { | ||
189 | This ZIP archive contains C source code for the SQLite library | ||
190 | version VERSION. | ||
191 | } | ||
192 | |||
193 | |||
194 | |||
195 | |||
196 | puts { | ||
197 | </table> | ||
198 | |||
199 | <a name="cvs"> | ||
200 | <h3>Direct Access To The Sources Via Anonymous CVS</h3> | ||
201 | |||
202 | <p> | ||
203 | All SQLite source code is maintained in a | ||
204 | <a href="http://www.cvshome.org/">CVS</a> repository that is | ||
205 | available for read-only access by anyone. You can | ||
206 | interactively view the | ||
207 | repository contents and download individual files | ||
208 | by visiting | ||
209 | <a href="http://www.sqlite.org/cvstrac/dir?d=sqlite"> | ||
210 | http://www.sqlite.org/cvstrac/dir?d=sqlite</a>. | ||
211 | To access the repository directly, use the following | ||
212 | commands: | ||
213 | </p> | ||
214 | |||
215 | <blockquote><pre> | ||
216 | cvs -d :pserver:anonymous@www.sqlite.org:/sqlite login | ||
217 | cvs -d :pserver:anonymous@www.sqlite.org:/sqlite checkout sqlite | ||
218 | </pre></blockquote> | ||
219 | |||
220 | <p> | ||
221 | When the first command prompts you for a password, enter "anonymous". | ||
222 | </p> | ||
223 | |||
224 | <p> | ||
225 | To access the SQLite version 2.8 sources, begin by getting the 3.0 | ||
226 | tree as described above. Then update to the "version_2" branch | ||
227 | as follows: | ||
228 | </p> | ||
229 | |||
230 | <blockquote><pre> | ||
231 | cvs update -r version_2 | ||
232 | </pre></blockquote> | ||
233 | |||
234 | } | ||
235 | |||
236 | footer $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 | # | ||
4 | set rcsid {$Id: dynload.tcl,v 1.1 2001/02/11 16:58:22 drh Exp $} | ||
5 | |||
6 | puts {<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> | ||
12 | How To Build A Dynamically Loaded Tcl Extension | ||
13 | </h1>} | ||
14 | puts {<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> | ||
19 | To compile the SQLite Tcl extension into a dynamically loaded module | ||
20 | I 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 | ||
28 | I followed the directions and did a standard build in the bld | ||
29 | directory)</p></li> | ||
30 | |||
31 | <li><p> | ||
32 | Now do the following in the bld directory | ||
33 | <blockquote><pre> | ||
34 | gcc -shared -I. -lgdbm ../sqlite/src/tclsqlite.c libsqlite.a -o sqlite.so | ||
35 | </pre></blockquote></p></li> | ||
36 | |||
37 | <li><p> | ||
38 | This should produce the file sqlite.so in the bld directory</p></li> | ||
39 | |||
40 | <li><p> | ||
41 | Create a pkgIndex.tcl file that contains this line | ||
42 | |||
43 | <blockquote><pre> | ||
44 | package ifneeded sqlite 1.0 [list load [file join $dir sqlite.so]] | ||
45 | </pre></blockquote></p></li> | ||
46 | |||
47 | <li><p> | ||
48 | To use this put sqlite.so and pkgIndex.tcl in the same directory</p></li> | ||
49 | |||
50 | <li><p> | ||
51 | From that directory start wish</p></li> | ||
52 | |||
53 | <li><p> | ||
54 | Execute the following tcl command (tells tcl where to fine loadable | ||
55 | modules) | ||
56 | <blockquote><pre> | ||
57 | lappend auto_path [exec pwd] | ||
58 | </pre></blockquote></p></li> | ||
59 | |||
60 | <li><p> | ||
61 | Load the package | ||
62 | <blockquote><pre> | ||
63 | package require sqlite | ||
64 | </pre></blockquote></p></li> | ||
65 | |||
66 | <li><p> | ||
67 | Have 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 | # | ||
4 | set rcsid {$Id: faq.tcl,v 1.40 2007/09/04 01:58:27 drh Exp $} | ||
5 | source common.tcl | ||
6 | header {SQLite Frequently Asked Questions</title>} | ||
7 | |||
8 | set cnt 1 | ||
9 | proc 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 | |||
17 | faq { | ||
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> | ||
33 | CREATE 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> | ||
40 | INSERT INTO t1 VALUES(NULL,123); | ||
41 | </pre></blockquote> | ||
42 | <p>is logically equivalent to saying:</p> | ||
43 | <blockquote><pre> | ||
44 | INSERT 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 | |||
64 | faq { | ||
65 | What datatypes does SQLite support? | ||
66 | } { | ||
67 | <p>See <a href="datatype3.html">http://www.sqlite.org/datatype3.html</a>.</p> | ||
68 | } | ||
69 | |||
70 | faq { | ||
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 | |||
96 | faq { | ||
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 | |||
110 | faq { | ||
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 | |||
162 | faq { | ||
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 | |||
199 | faq { | ||
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> | ||
214 | CREATE 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> | ||
226 | SELECT name FROM sqlite_master | ||
227 | WHERE type='table' | ||
228 | ORDER 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> | ||
249 | SELECT name FROM | ||
250 | (SELECT * FROM sqlite_master UNION ALL | ||
251 | SELECT * FROM sqlite_temp_master) | ||
252 | WHERE type='table' | ||
253 | ORDER BY name | ||
254 | </pre></blockquote> | ||
255 | } | ||
256 | |||
257 | faq { | ||
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 | |||
264 | faq { | ||
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 | |||
273 | faq { | ||
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 | |||
280 | faq { | ||
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> | ||
299 | BEGIN TRANSACTION; | ||
300 | CREATE TEMPORARY TABLE t1_backup(a,b); | ||
301 | INSERT INTO t1_backup SELECT a,b FROM t1; | ||
302 | DROP TABLE t1; | ||
303 | CREATE TABLE t1(a,b); | ||
304 | INSERT INTO t1 SELECT a,b FROM t1_backup; | ||
305 | DROP TABLE t1_backup; | ||
306 | COMMIT; | ||
307 | </pre></blockquote> | ||
308 | } | ||
309 | |||
310 | faq { | ||
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 | |||
334 | faq { | ||
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 | |||
342 | faq { | ||
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 | |||
356 | faq {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 | |||
418 | faq {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 | |||
442 | puts {<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>} | ||
450 | puts {<OL>} | ||
451 | for {set i 1} {$i<$cnt} {incr i} { | ||
452 | puts "<li><a href=\"#q$i\">[lindex $faq($i) 0]</a></li>" | ||
453 | } | ||
454 | puts {</OL>} | ||
455 | |||
456 | for {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 | |||
462 | puts {</OL>} | ||
463 | footer $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 | # | ||
4 | set rcsid {$Id: fileformat.tcl,v 1.13 2004/10/10 17:24:55 drh Exp $} | ||
5 | source common.tcl | ||
6 | header {SQLite Database File Format (Version 2)} | ||
7 | puts { | ||
8 | <h2>SQLite 2.X Database File Format</h2> | ||
9 | |||
10 | <p> | ||
11 | This document describes the disk file format for SQLite versions 2.1 | ||
12 | through 2.8. SQLite version 3.0 and following uses a very different | ||
13 | format which is described separately. | ||
14 | </p> | ||
15 | |||
16 | <h3>1.0 Layers</h3> | ||
17 | |||
18 | <p> | ||
19 | SQLite is implemented in layers. | ||
20 | (See the <a href="arch.html">architecture description</a>.) | ||
21 | The format of database files is determined by three different | ||
22 | layers 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> | ||
32 | We will describe each layer beginning with the bottom (pager) | ||
33 | layer and working upwards. | ||
34 | </p> | ||
35 | |||
36 | <h3>2.0 The Pager Layer</h3> | ||
37 | |||
38 | <p> | ||
39 | An SQLite database consists of | ||
40 | "pages" of data. Each page is 1024 bytes in size. | ||
41 | Pages are numbered beginning with 1. | ||
42 | A page number of 0 is used to indicate "no such page" in the | ||
43 | B-Tree and Schema layers. | ||
44 | </p> | ||
45 | |||
46 | <p> | ||
47 | The pager layer is responsible for implementing transactions | ||
48 | with atomic commit and rollback. It does this using a separate | ||
49 | journal file. Whenever a new transaction is started, a journal | ||
50 | file is created that records the original state of the database. | ||
51 | If the program terminates before completing the transaction, the next | ||
52 | process to open the database can use the journal file to restore | ||
53 | the database to its original state. | ||
54 | </p> | ||
55 | |||
56 | <p> | ||
57 | The journal file is located in the same directory as the database | ||
58 | file and has the same name as the database file but with the | ||
59 | characters "<tt>-journal</tt>" appended. | ||
60 | </p> | ||
61 | |||
62 | <p> | ||
63 | The pager layer does not impose any content restrictions on the | ||
64 | main database file. As far as the pager is concerned, each page | ||
65 | contains 1024 bytes of arbitrary data. But there is structure to | ||
66 | the journal file. | ||
67 | </p> | ||
68 | |||
69 | <p> | ||
70 | A journal file begins with 8 bytes as follows: | ||
71 | 0xd9, 0xd5, 0x05, 0xf9, 0x20, 0xa1, 0x63, and 0xd6. | ||
72 | Processes that are attempting to rollback a journal use these 8 bytes | ||
73 | as a sanity check to make sure the file they think is a journal really | ||
74 | is a valid journal. Prior version of SQLite used different journal | ||
75 | file formats. The magic numbers for these prior formats are different | ||
76 | so that if a new version of the library attempts to rollback a journal | ||
77 | created by an earlier version, it can detect that the journal uses | ||
78 | an obsolete format and make the necessary adjustments. This article | ||
79 | describes only the newest journal format - supported as of version | ||
80 | 2.8.0. | ||
81 | </p> | ||
82 | |||
83 | <p> | ||
84 | Following the 8 byte prefix is a three 4-byte integers that tell us | ||
85 | the number of pages that have been committed to the journal, | ||
86 | a magic number used for | ||
87 | sanity checking each page, and the | ||
88 | original size of the main database file before the transaction was | ||
89 | started. The number of committed pages is used to limit how far | ||
90 | into the journal to read. The use of the checksum magic number is | ||
91 | described below. | ||
92 | The original size of the database is used to restore the database | ||
93 | file back to its original size. | ||
94 | The size is expressed in pages (1024 bytes per page). | ||
95 | </p> | ||
96 | |||
97 | <p> | ||
98 | All three integers in the journal header and all other multi-byte | ||
99 | numbers used in the journal file are big-endian. | ||
100 | That means that the most significant byte | ||
101 | occurs first. That way, a journal file that is | ||
102 | originally created on one machine can be rolled back by another | ||
103 | machine that uses a different byte order. So, for example, a | ||
104 | transaction that failed to complete on your big-endian SparcStation | ||
105 | can still be rolled back on your little-endian Linux box. | ||
106 | </p> | ||
107 | |||
108 | <p> | ||
109 | After the 8-byte prefix and the three 4-byte integers, the | ||
110 | journal file consists of zero or more page records. Each page | ||
111 | record is a 4-byte (big-endian) page number followed by 1024 bytes | ||
112 | of data and a 4-byte checksum. | ||
113 | The data is the original content of the database page | ||
114 | before the transaction was started. So to roll back the transaction, | ||
115 | the data is simply written into the corresponding page of the | ||
116 | main database file. Pages can appear in the journal in any order, | ||
117 | but they are guaranteed to appear only once. All page numbers will be | ||
118 | between 1 and the maximum specified by the page size integer that | ||
119 | appeared at the beginning of the journal. | ||
120 | </p> | ||
121 | |||
122 | <p> | ||
123 | The so-called checksum at the end of each record is not really a | ||
124 | checksum - it is the sum of the page number and the magic number which | ||
125 | was the second integer in the journal header. The purpose of this | ||
126 | value is to try to detect journal corruption that might have occurred | ||
127 | because of a power loss or OS crash that occurred which the journal | ||
128 | file was being written to disk. It could have been the case that the | ||
129 | meta-data for the journal file, specifically the size of the file, had | ||
130 | been written to the disk so that when the machine reboots it appears that | ||
131 | file is large enough to hold the current record. But even though the | ||
132 | file size has changed, the data for the file might not have made it to | ||
133 | the disk surface at the time of the OS crash or power loss. This means | ||
134 | that after reboot, the end of the journal file will contain quasi-random | ||
135 | garbage data. The checksum is an attempt to detect such corruption. If | ||
136 | the checksum does not match, that page of the journal is not rolled back. | ||
137 | </p> | ||
138 | |||
139 | <p> | ||
140 | Here 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 The B-Tree Layer</h3> | ||
158 | |||
159 | <p> | ||
160 | The B-Tree layer builds on top of the pager layer to implement | ||
161 | one or more separate b-trees all in the same disk file. The | ||
162 | algorithms used are taken from Knuth's <i>The Art Of Computer | ||
163 | Programming.</i></p> | ||
164 | |||
165 | <p> | ||
166 | Page 1 of a database contains a header string used for sanity | ||
167 | checking, a few 32-bit words of configuration data, and a pointer | ||
168 | to the beginning of a list of unused pages in the database. | ||
169 | All other pages in the | ||
170 | database are either pages of a b-tree, overflow pages, or unused | ||
171 | pages on the freelist. | ||
172 | </p> | ||
173 | |||
174 | <p> | ||
175 | Each b-tree page contains zero or more database entries. | ||
176 | Each entry has an unique key of one or more bytes and data of | ||
177 | zero or more bytes. | ||
178 | Both the key and data are arbitrary byte sequences. The combination | ||
179 | of key and data are collectively known as "payload". The current | ||
180 | implementation limits the amount of payload in a single entry to | ||
181 | 1048576 bytes. This limit can be raised to 16777216 by adjusting | ||
182 | a single #define in the source code and recompiling. But most entries | ||
183 | contain less than a hundred bytes of payload so a megabyte limit seems | ||
184 | more than enough. | ||
185 | </p> | ||
186 | |||
187 | <p> | ||
188 | Up to 238 bytes of payload for an entry can be held directly on | ||
189 | a b-tree page. Any additional payload is contained on a linked list | ||
190 | of overflow pages. This limit on the amount of payload held directly | ||
191 | on b-tree pages guarantees that each b-tree page can hold at least | ||
192 | 4 entries. In practice, most entries are smaller than 238 bytes and | ||
193 | thus most pages can hold more than 4 entries. | ||
194 | </p> | ||
195 | |||
196 | <p> | ||
197 | A single database file can hold any number of separate, independent b-trees. | ||
198 | Each b-tree is identified by its root page, which never changes. | ||
199 | Child pages of the b-tree may change as entries are added and removed | ||
200 | and pages split and combine. But the root page always stays the same. | ||
201 | The b-tree itself does not record which pages are root pages and which | ||
202 | are not. That information is handled entirely at the schema layer. | ||
203 | </p> | ||
204 | |||
205 | <h4>3.1 B-Tree Page 1 Details</h4> | ||
206 | |||
207 | <p> | ||
208 | Page 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> | ||
216 | If you count the number of characters in the string above, you will | ||
217 | see that there are only 47. A '\000' terminator byte is added to | ||
218 | bring the total to 48. | ||
219 | </p> | ||
220 | |||
221 | <p> | ||
222 | A frequent question is why the string says version 2.1 when (as | ||
223 | of this writing) we are up to version 2.7.0 of SQLite and any | ||
224 | change to the second digit of the version is suppose to represent | ||
225 | a database format change. The answer to this is that the B-tree | ||
226 | layer has not changed any since version 2.1. There have been | ||
227 | database format changes since version 2.1 but those changes have | ||
228 | all been in the schema layer. Because the format of the b-tree | ||
229 | layer is unchanged since version 2.1.0, the header string still | ||
230 | says version 2.1. | ||
231 | </p> | ||
232 | |||
233 | <p> | ||
234 | After the format string is a 4-byte integer used to determine the | ||
235 | byte-order of the database. The integer has a value of | ||
236 | 0xdae37528. If this number is expressed as 0xda, 0xe3, 0x75, 0x28, then | ||
237 | the database is in a big-endian format and all 16 and 32-bit integers | ||
238 | elsewhere in the b-tree layer are also big-endian. If the number is | ||
239 | expressed as 0x28, 0x75, 0xe3, and 0xda, then the database is in a | ||
240 | little-endian format and all other multi-byte numbers in the b-tree | ||
241 | layer are also little-endian. | ||
242 | Prior to version 2.6.3, the SQLite engine was only able to read databases | ||
243 | that used the same byte order as the processor they were running on. | ||
244 | But beginning with 2.6.3, SQLite can read or write databases in any | ||
245 | byte order. | ||
246 | </p> | ||
247 | |||
248 | <p> | ||
249 | After the byte-order code are six 4-byte integers. Each integer is in the | ||
250 | byte order determined by the byte-order code. The first integer is the | ||
251 | page number for the first page of the freelist. If there are no unused | ||
252 | pages in the database, then this integer is 0. The second integer is | ||
253 | the number of unused pages in the database. The last 4 integers are | ||
254 | not used by the b-tree layer. These are the so-called "meta" values that | ||
255 | are passed up to the schema layer | ||
256 | and used there for configuration and format version information. | ||
257 | All bytes of page 1 past beyond the meta-value integers are unused | ||
258 | and are initialized to zero. | ||
259 | </p> | ||
260 | |||
261 | <p> | ||
262 | Here 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 Structure Of A Single B-Tree Page</h4> | ||
275 | |||
276 | <p> | ||
277 | Conceptually, a b-tree page contains N database entries and N+1 pointers | ||
278 | to 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> | ||
297 | The entries are arranged in increasing order. That is, the key to | ||
298 | Entry 0 is less than the key to Entry 1, and the key to Entry 1 is | ||
299 | less than the key of Entry 2, and so forth. The pointers point to | ||
300 | pages containing additional entries that have keys in between the | ||
301 | entries on either side. So Ptr 0 points to another b-tree page that | ||
302 | contains entries that all have keys less than Key 0, and Ptr 1 | ||
303 | points to a b-tree pages where all entries have keys greater than Key 0 | ||
304 | but less than Key 1, and so forth. | ||
305 | </p> | ||
306 | |||
307 | <p> | ||
308 | Each b-tree page in SQLite consists of a header, zero or more "cells" | ||
309 | each holding a single entry and pointer, and zero or more "free blocks" | ||
310 | that represent unused space on the page. | ||
311 | </p> | ||
312 | |||
313 | <p> | ||
314 | The header on a b-tree page is the first 8 bytes of the page. | ||
315 | The header contains the value | ||
316 | of the right-most pointer (Ptr N) and the byte offset into the page | ||
317 | of the first cell and the first free block. The pointer is a 32-bit | ||
318 | value 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> | ||
342 | The 1016 bytes of a b-tree page that come after the header contain | ||
343 | cells and freeblocks. All 1016 bytes are covered by either a cell | ||
344 | or a freeblock. | ||
345 | </p> | ||
346 | |||
347 | <p> | ||
348 | The cells are connected in a linked list. Cell 0 contains Ptr 0 and | ||
349 | Entry 0. Bytes 4 and 5 of the header point to Cell 0. Cell 0 then | ||
350 | points to Cell 1 which contains Ptr 1 and Entry 1. And so forth. | ||
351 | Cells vary in size. Every cell has a 12-byte header and at least 4 | ||
352 | bytes of payload space. Space is allocated to payload in increments | ||
353 | of 4 bytes. Thus the minimum size of a cell is 16 bytes and up to | ||
354 | 63 cells can fit on a single page. The size of a cell is always a multiple | ||
355 | of 4 bytes. | ||
356 | A cell can have up to 238 bytes of payload space. If | ||
357 | the payload is more than 238 bytes, then an additional 4 byte page | ||
358 | number is appended to the cell which is the page number of the first | ||
359 | overflow page containing the additional payload. The maximum size | ||
360 | of a cell is thus 254 bytes, meaning that a least 4 cells can fit into | ||
361 | the 1016 bytes of space available on a b-tree page. | ||
362 | An average cell is usually around 52 to 100 bytes in size with about | ||
363 | 10 or 20 cells to a page. | ||
364 | </p> | ||
365 | |||
366 | <p> | ||
367 | The 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> | ||
405 | The first four bytes are the pointer. The size of the key is a 24-bit | ||
406 | where the upper 8 bits are taken from byte 8 and the lower 16 bits are | ||
407 | taken from bytes 4 and 5 (or bytes 5 and 4 on little-endian machines.) | ||
408 | The size of the data is another 24-bit value where the upper 8 bits | ||
409 | are taken from byte 9 and the lower 16 bits are taken from bytes 10 and | ||
410 | 11 or 11 and 10, depending on the byte order. Bytes 6 and 7 are the | ||
411 | offset to the next cell in the linked list of all cells on the current | ||
412 | page. This offset is 0 for the last cell on the page. | ||
413 | </p> | ||
414 | |||
415 | <p> | ||
416 | The payload itself can be any number of bytes between 1 and 1048576. | ||
417 | But space to hold the payload is allocated in 4-byte chunks up to | ||
418 | 238 bytes. If the entry contains more than 238 bytes of payload, then | ||
419 | additional payload data is stored on a linked list of overflow pages. | ||
420 | A 4 byte page number is appended to the cell that contains the first | ||
421 | page of this linked list. | ||
422 | </p> | ||
423 | |||
424 | <p> | ||
425 | Each overflow page begins with a 4-byte value which is the | ||
426 | page number of the next overflow page in the list. This value is | ||
427 | 0 for the last page in the list. The remaining | ||
428 | 1020 bytes of the overflow page are available for storing payload. | ||
429 | Note that a full page is allocated regardless of the number of overflow | ||
430 | bytes stored. Thus, if the total payload for an entry is 239 bytes, | ||
431 | the first 238 are stored in the cell and the overflow page stores just | ||
432 | one byte. | ||
433 | </p> | ||
434 | |||
435 | <p> | ||
436 | The 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> | ||
456 | All space on a b-tree page which is not used by the header or by cells | ||
457 | is filled by freeblocks. Freeblocks, like cells, are variable in size. | ||
458 | The size of a freeblock is at least 4 bytes and is always a multiple of | ||
459 | 4 bytes. | ||
460 | The first 4 bytes contain a header and the remaining bytes | ||
461 | are 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> | ||
482 | Freeblocks are stored in a linked list in increasing order. That is | ||
483 | to say, the first freeblock occurs at a lower index into the page than | ||
484 | the second free block, and so forth. The first 2 bytes of the header | ||
485 | are an integer which is the total number of bytes in the freeblock. | ||
486 | The second 2 bytes are the index into the page of the next freeblock | ||
487 | in the list. The last freeblock has a Next value of 0. | ||
488 | </p> | ||
489 | |||
490 | <p> | ||
491 | When a new b-tree is created in a database, the root page of the b-tree | ||
492 | consist of a header and a single 1016 byte freeblock. As entries are | ||
493 | added, space is carved off of that freeblock and used to make cells. | ||
494 | When b-tree entries are deleted, the space used by their cells is converted | ||
495 | into freeblocks. Adjacent freeblocks are merged, but the page can still | ||
496 | become fragmented. The b-tree code will occasionally try to defragment | ||
497 | the page by moving all cells to the beginning and constructing a single | ||
498 | freeblock at the end to take up all remaining space. | ||
499 | </p> | ||
500 | |||
501 | <h4>3.3 The B-Tree Free Page List</h4> | ||
502 | |||
503 | <p> | ||
504 | When information is removed from an SQLite database such that one or | ||
505 | more pages are no longer needed, those pages are added to a list of | ||
506 | free pages so that they can be reused later when new information is | ||
507 | added. This subsection describes the structure of this freelist. | ||
508 | </p> | ||
509 | |||
510 | <p> | ||
511 | The 32-bit integer beginning at byte-offset 52 in page 1 of the database | ||
512 | contains the address of the first page in a linked list of free pages. | ||
513 | If there are no free pages available, this integer has a value of 0. | ||
514 | The 32-bit integer at byte-offset 56 in page 1 contains the number of | ||
515 | free pages on the freelist. | ||
516 | </p> | ||
517 | |||
518 | <p> | ||
519 | The freelist contains a trunk and many branches. The trunk of | ||
520 | the freelist is composed of overflow pages. That is to say, each page | ||
521 | contains a single 32-bit integer at byte offset 0 which | ||
522 | is the page number of the next page on the freelist trunk. | ||
523 | The payload area | ||
524 | of each trunk page is used to record pointers to branch pages. | ||
525 | The first 32-bit integer in the payload area of a trunk page | ||
526 | is the number of branch pages to follow (between 0 and 254) | ||
527 | and each subsequent 32-bit integer is a page number for a branch page. | ||
528 | The 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> | ||
553 | It is important to note that only the pages on the trunk of the freelist | ||
554 | contain pointers to other pages. The branch pages contain no | ||
555 | data whatsoever. The fact that the branch pages are completely | ||
556 | blank allows for an important optimization in the paging layer. When | ||
557 | a branch page is removed from the freelist to be reused, it is not | ||
558 | necessary to write the original content of that page into the rollback | ||
559 | journal. The branch page contained no data to begin with, so there is | ||
560 | no need to restore the page in the event of a rollback. Similarly, | ||
561 | when a page is not longer needed and is added to the freelist as a branch | ||
562 | page, it is not necessary to write the content of that page | ||
563 | into the database file. | ||
564 | Again, the page contains no real data so it is not necessary to record the | ||
565 | content of that page. By reducing the amount of disk I/O required, | ||
566 | these two optimizations allow some database operations | ||
567 | to go four to six times faster than they would otherwise. | ||
568 | </p> | ||
569 | |||
570 | <h3>4.0 The Schema Layer</h3> | ||
571 | |||
572 | <p> | ||
573 | The schema layer implements an SQL database on top of one or more | ||
574 | b-trees and keeps track of the root page numbers for all b-trees. | ||
575 | Where the b-tree layer provides only unformatted data storage with | ||
576 | a unique key, the schema layer allows each entry to contain multiple | ||
577 | columns. The schema layer also allows indices and non-unique key values. | ||
578 | </p> | ||
579 | |||
580 | <p> | ||
581 | The schema layer implements two separate data storage abstractions: | ||
582 | tables and indices. Each table and each index uses its own b-tree | ||
583 | but they use the b-tree capabilities in different ways. For a table, | ||
584 | the b-tree key is a unique 4-byte integer and the b-tree data is the | ||
585 | content of the table row, encoded so that columns can be separately | ||
586 | extracted. For indices, the b-tree key varies in size depending on the | ||
587 | size of the fields being indexed and the b-tree data is empty. | ||
588 | </p> | ||
589 | |||
590 | <h4>4.1 SQL Table Implementation Details</h4> | ||
591 | |||
592 | <p>Each row of an SQL table is stored in a single b-tree entry. | ||
593 | The b-tree key is a 4-byte big-endian integer that is the ROWID | ||
594 | or INTEGER PRIMARY KEY for that table row. | ||
595 | The key is stored in a big-endian format so | ||
596 | that 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 | ||
599 | the corresponding b-tree table. The content is encoded to allow | ||
600 | individual columns of the row to be extracted as necessary. Assuming | ||
601 | that the table has N columns, the content is encoded as N+1 offsets | ||
602 | followed 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> | ||
622 | The offsets can be either 8-bit, 16-bit, or 24-bit integers depending | ||
623 | on how much data is to be stored. If the total size of the content | ||
624 | is less than 256 bytes then 8-bit offsets are used. If the total size | ||
625 | of the b-tree data is less than 65536 then 16-bit offsets are used. | ||
626 | 24-bit offsets are used otherwise. Offsets are always little-endian, | ||
627 | which means that the least significant byte occurs first. | ||
628 | </p> | ||
629 | |||
630 | <p> | ||
631 | Data is stored as a nul-terminated string. Any empty string consists | ||
632 | of just the nul terminator. A NULL value is an empty string with no | ||
633 | nul-terminator. Thus a NULL value occupies zero bytes and an empty string | ||
634 | occupies 1 byte. | ||
635 | </p> | ||
636 | |||
637 | <p> | ||
638 | Column values are stored in the order that they appear in the CREATE TABLE | ||
639 | statement. The offsets at the beginning of the record contain the | ||
640 | byte index of the corresponding column value. Thus, Offset 0 contains | ||
641 | the byte index for Value 0, Offset 1 contains the byte offset | ||
642 | of Value 1, and so forth. The number of bytes in a column value can | ||
643 | always be found by subtracting offsets. This allows NULLs to be | ||
644 | recovered from the record unambiguously. | ||
645 | </p> | ||
646 | |||
647 | <p> | ||
648 | Most columns are stored in the b-tree data as described above. | ||
649 | The one exception is column that has type INTEGER PRIMARY KEY. | ||
650 | INTEGER PRIMARY KEY columns correspond to the 4-byte b-tree key. | ||
651 | When an SQL statement attempts to read the INTEGER PRIMARY KEY, | ||
652 | the 4-byte b-tree key is read rather than information out of the | ||
653 | b-tree data. But there is still an Offset associated with the | ||
654 | INTEGER PRIMARY KEY, just like any other column. But the Value | ||
655 | associated with that offset is always NULL. | ||
656 | </p> | ||
657 | |||
658 | <h4>4.2 SQL Index Implementation Details</h4> | ||
659 | |||
660 | <p> | ||
661 | SQL indices are implement using a b-tree in which the key is used | ||
662 | but the data is always empty. The purpose of an index is to map | ||
663 | one or more column values into the ROWID for the table entry that | ||
664 | contains those column values. | ||
665 | </p> | ||
666 | |||
667 | <p> | ||
668 | Each b-tree in an index consists of one or more column values followed | ||
669 | by a 4-byte ROWID. Each column value is nul-terminated (even NULL values) | ||
670 | and begins with a single character that indicates the datatype for that | ||
671 | column value. Only three datatypes are supported: NULL, Number, and | ||
672 | Text. NULL values are encoded as the character 'a' followed by the | ||
673 | nul terminator. Numbers are encoded as the character 'b' followed by | ||
674 | a string that has been crafted so that sorting the string using memcmp() | ||
675 | will sort the corresponding numbers in numerical order. (See the | ||
676 | sqliteRealToSortable() function in util.c of the SQLite sources for | ||
677 | additional information on this encoding.) Numbers are also nul-terminated. | ||
678 | Text values consists of the character 'c' followed by a copy of the | ||
679 | text string and a nul-terminator. These encoding rules result in | ||
680 | NULLs being sorted first, followed by numerical values in numerical | ||
681 | order, followed by text values in lexicographical order. | ||
682 | </p> | ||
683 | |||
684 | <h4>4.4 SQL Schema Storage And Root B-Tree Page Numbers</h4> | ||
685 | |||
686 | <p> | ||
687 | The 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. | ||
689 | This table contains the original CREATE TABLE, | ||
690 | CREATE INDEX, CREATE VIEW, and CREATE TRIGGER statements used to define | ||
691 | the database to begin with. Whenever an SQLite database is opened, | ||
692 | the sqlite_master table is scanned from beginning to end and | ||
693 | all the original CREATE statements are played back through the parser | ||
694 | in order to reconstruct an in-memory representation of the database | ||
695 | schema for use in subsequent command parsing. For each CREATE TABLE | ||
696 | and CREATE INDEX statement, the root page number for the corresponding | ||
697 | b-tree is also recorded in the sqlite_master table so that SQLite will | ||
698 | know where to look for the appropriate b-tree. | ||
699 | </p> | ||
700 | |||
701 | <p> | ||
702 | SQLite users can query the sqlite_master table just like any other table | ||
703 | in the database. But the sqlite_master table cannot be directly written. | ||
704 | The sqlite_master table is automatically updated in response to CREATE | ||
705 | and DROP statements but it cannot be changed using INSERT, UPDATE, or | ||
706 | DELETE statements as that would risk corrupting the database. | ||
707 | </p> | ||
708 | |||
709 | <p> | ||
710 | SQLite stores temporary tables and indices in a separate | ||
711 | file from the main database file. The temporary table database file | ||
712 | is the same structure as the main database file. The schema table | ||
713 | for the temporary tables is stored on page 2 just as in the main | ||
714 | database. But the schema table for the temporary database named | ||
715 | "sqlite_temp_master" instead of "sqlite_master". Other than the | ||
716 | name change, it works exactly the same. | ||
717 | </p> | ||
718 | |||
719 | <h4>4.4 Schema Version Numbering And Other Meta-Information</h4> | ||
720 | |||
721 | <p> | ||
722 | The nine 32-bit integers that are stored beginning at byte offset | ||
723 | 60 of Page 1 in the b-tree layer are passed up into the schema layer | ||
724 | and used for versioning and configuration information. The meaning | ||
725 | of the first four integers is shown below. The other five are currently | ||
726 | unused. | ||
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> | ||
737 | The first meta-value, the schema version number, is used to detect when | ||
738 | the schema of the database is changed by a CREATE or DROP statement. | ||
739 | Recall that when a database is first opened the sqlite_master table is | ||
740 | scanned and an internal representation of the tables, indices, views, | ||
741 | and triggers for the database is built in memory. This internal | ||
742 | representation is used for all subsequent SQL command parsing and | ||
743 | execution. But what if another process were to change the schema | ||
744 | by adding or removing a table, index, view, or trigger? If the original | ||
745 | process were to continue using the old schema, it could potentially | ||
746 | corrupt the database by writing to a table that no longer exists. | ||
747 | To avoid this problem, the schema version number is changed whenever | ||
748 | a CREATE or DROP statement is executed. Before each command is | ||
749 | executed, the current schema version number for the database file | ||
750 | is compared against the schema version number from when the sqlite_master | ||
751 | table was last read. If those numbers are different, the internal | ||
752 | schema representation is erased and the sqlite_master table is reread | ||
753 | to reconstruct the internal schema representation. | ||
754 | (Calls to sqlite_exec() generally return SQLITE_SCHEMA when this happens.) | ||
755 | </p> | ||
756 | |||
757 | <p> | ||
758 | The second meta-value is the schema format version number. This | ||
759 | number tells what version of the schema layer should be used to | ||
760 | interpret the file. There have been changes to the schema layer | ||
761 | over time and this number is used to detect when an older database | ||
762 | file is being processed by a newer version of the library. | ||
763 | As of this writing (SQLite version 2.7.0) the current format version | ||
764 | is "4". | ||
765 | </p> | ||
766 | |||
767 | <p> | ||
768 | The third meta-value is the recommended pager cache size as set | ||
769 | by the DEFAULT_CACHE_SIZE pragma. If the value is positive it | ||
770 | means that synchronous behavior is enable (via the DEFAULT_SYNCHRONOUS | ||
771 | pragma) and if negative it means that synchronous behavior is | ||
772 | disabled. | ||
773 | </p> | ||
774 | |||
775 | <p> | ||
776 | The fourth meta-value is safety level added in version 2.8.0. | ||
777 | A value of 1 corresponds to a SYNCHRONOUS setting of OFF. In other | ||
778 | words, SQLite does not pause to wait for journal data to reach the disk | ||
779 | surface before overwriting pages of the database. A value of 2 corresponds | ||
780 | to a SYNCHRONOUS setting of NORMAL. A value of 3 corresponds to a | ||
781 | SYNCHRONOUS setting of FULL. If the value is 0, that means it has not | ||
782 | been initialized so the default synchronous setting of NORMAL is used. | ||
783 | </p> | ||
784 | } | ||
785 | footer $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 | # | ||
4 | set rcsid {$Id: formatchng.tcl,v 1.20 2007/09/03 20:32:45 drh Exp $ } | ||
5 | source common.tcl | ||
6 | header {File Format Changes in SQLite} | ||
7 | puts { | ||
8 | <h2>File Format Changes in SQLite</h2> | ||
9 | |||
10 | <p> | ||
11 | Every effort is made to keep SQLite fully backwards compatible from | ||
12 | one release to the next. Rarely, however, some | ||
13 | enhancements or bug fixes may require a change to | ||
14 | the underlying file format. When this happens and you | ||
15 | must convert the contents of your | ||
16 | databases into a portable ASCII representation using the old version | ||
17 | of the library then reload the data using the new version of the | ||
18 | library. | ||
19 | </p> | ||
20 | |||
21 | <p> | ||
22 | You can tell if you should reload your databases by comparing the | ||
23 | version numbers of the old and new libraries. If the first digit | ||
24 | of the version number is different, then a reload of the database will | ||
25 | be required. If the second digit changes, newer versions of SQLite | ||
26 | will be able to read and write older database files, but older versions | ||
27 | of the library may have difficulty reading or writing newer database | ||
28 | files. | ||
29 | For example, upgrading from | ||
30 | version 2.8.14 to 3.0.0 requires a reload. Going from | ||
31 | version 3.0.8 to 3.1.0 is backwards compatible but not necessarily | ||
32 | forwards compatible. | ||
33 | </p> | ||
34 | |||
35 | <p> | ||
36 | The following table summarizes the SQLite file format changes that have | ||
37 | occurred 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> | ||
272 | To perform a database reload, have ready versions of the | ||
273 | <b>sqlite</b> command-line utility for both the old and new | ||
274 | version of SQLite. Call these two executables "<b>sqlite-old</b>" | ||
275 | and "<b>sqlite-new</b>". Suppose the name of your old database | ||
276 | is "<b>old.db</b>" and you want to create a new database with | ||
277 | the same information named "<b>new.db</b>". The command to do | ||
278 | this is as follows: | ||
279 | </p> | ||
280 | |||
281 | <blockquote> | ||
282 | sqlite-old old.db .dump | sqlite-new new.db | ||
283 | </blockquote> | ||
284 | } | ||
285 | footer $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 | ||
2 | source common.tcl | ||
3 | header {SQLite home page} | ||
4 | puts { | ||
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> | ||
14 | SQLite is a small | ||
15 | C library that implements a self-contained, embeddable, | ||
16 | zero-configuration | ||
17 | SQL database engine. | ||
18 | Features 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> | ||
55 | The SQLite distribution comes with a standalone command-line | ||
56 | access program (<a href="sqlite.html">sqlite</a>) that can | ||
57 | be used to administer an SQLite database and which serves as | ||
58 | an 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 | |||
67 | proc 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 | |||
74 | newsitem {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 | |||
84 | newsitem {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 | |||
98 | newsitem {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 | |||
112 | newsitem {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 | |||
122 | puts { | ||
123 | <p align="right"><a href="oldnews.html">Old news...</a></p> | ||
124 | </td></tr></table> | ||
125 | } | ||
126 | footer {$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 | # | ||
4 | set rcsid {$Id: lang.tcl,v 1.136 2007/10/03 20:15:28 drh Exp $} | ||
5 | source common.tcl | ||
6 | |||
7 | if {[llength $argv]>0} { | ||
8 | set outputdir [lindex $argv 0] | ||
9 | } else { | ||
10 | set outputdir "" | ||
11 | } | ||
12 | |||
13 | header {Query Language Understood by SQLite} | ||
14 | puts { | ||
15 | <h1 class="pdf_section">SQL As Understood By SQLite</h1> | ||
16 | |||
17 | <p>The SQLite library understands most of the standard SQL | ||
18 | language. But it does <a href="omitted.html">omit some features</a> | ||
19 | while at the same time | ||
20 | adding a few features of its own. This document attempts to | ||
21 | describe precisely what parts of the SQL language SQLite does | ||
22 | and does not support. A list of <a href="lang_keywords.html">keywords</a> is | ||
23 | also provided.</p> | ||
24 | |||
25 | <p>In all of the syntax diagrams that follow, literal text is shown in | ||
26 | bold blue. Non-terminal symbols are shown in italic red. Operators | ||
27 | that 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 | ||
30 | by SQLite. Many low-level productions are omitted. For detailed information | ||
31 | on the language that SQLite understands, refer to the source code and | ||
32 | the grammar file "parse.y".</p> | ||
33 | |||
34 | <div class="pdf_ignore"> | ||
35 | <p>SQLite implements the follow syntax:</p> | ||
36 | <p><ul> | ||
37 | } | ||
38 | |||
39 | proc 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 | |||
50 | foreach {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 | } | ||
85 | puts {</ul></p> | ||
86 | </div> | ||
87 | |||
88 | <p>Details on the implementation of each command are provided in | ||
89 | the sequel.</p> | ||
90 | } | ||
91 | |||
92 | proc Operator {name} { | ||
93 | return "<font color=\"#2c2cf0\"><big>$name</big></font>" | ||
94 | } | ||
95 | proc Nonterminal {name} { | ||
96 | return "<i><font color=\"#ff3434\">$name</font></i>" | ||
97 | } | ||
98 | proc Keyword {name} { | ||
99 | return "<font color=\"#2c2cf0\">$name</font>" | ||
100 | } | ||
101 | proc Example {text} { | ||
102 | puts "<blockquote><pre>$text</pre></blockquote>" | ||
103 | } | ||
104 | |||
105 | proc 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 | |||
142 | Section {ALTER TABLE} altertable | ||
143 | |||
144 | Syntax {sql-statement} { | ||
145 | ALTER TABLE [<database-name> .] <table-name> <alteration> | ||
146 | } {alteration} { | ||
147 | RENAME TO <new-table-name> | ||
148 | } {alteration} { | ||
149 | ADD [COLUMN] <column-def> | ||
150 | } | ||
151 | |||
152 | puts { | ||
153 | <p>SQLite's version of the ALTER TABLE command allows the user to | ||
154 | rename or add a new column to an existing table. It is not possible | ||
155 | to 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 | ||
160 | cannot be used to move a table between attached databases, only to rename | ||
161 | a table within the same database.</p> | ||
162 | |||
163 | <p>If the table being renamed has triggers or indices, then these remain | ||
164 | attached to the table after it has been renamed. However, if there are | ||
165 | any view definitions, or statements executed by triggers that refer to | ||
166 | the table being renamed, these are not automatically modified to use the new | ||
167 | table name. If this is required, the triggers or view definitions must be | ||
168 | dropped 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. | ||
172 | The 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 | ||
174 | statement, 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 | ||
184 | the amount of data in the table. The ALTER TABLE command runs as quickly | ||
185 | on 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 | ||
189 | be readable by SQLite version 3.1.3 and earlier until the database | ||
190 | is <a href="lang_vacuum.html">VACUUM</a>ed.</p> | ||
191 | } | ||
192 | |||
193 | Section {ANALYZE} analyze | ||
194 | |||
195 | Syntax {sql-statement} { | ||
196 | ANALYZE | ||
197 | } | ||
198 | Syntax {sql-statement} { | ||
199 | ANALYZE <database-name> | ||
200 | } | ||
201 | Syntax {sql-statement} { | ||
202 | ANALYZE [<database-name> .] <table-name> | ||
203 | } | ||
204 | |||
205 | puts { | ||
206 | <p>The ANALYZE command gathers statistics about indices and stores them | ||
207 | in a special tables in the database where the query optimizer can use | ||
208 | them to help make better index choices. | ||
209 | If no arguments are given, all indices in all attached databases are | ||
210 | analyzed. If a database name is given as the argument, all indices | ||
211 | in that one database are analyzed. If the argument is a table name, | ||
212 | then only indices associated with that one table are analyzed.</p> | ||
213 | |||
214 | <p>The initial implementation stores all statistics in a single | ||
215 | table named <b>sqlite_stat1</b>. Future enhancements may create | ||
216 | additional tables with the same name pattern except with the "1" | ||
217 | changed to a different digit. The <b>sqlite_stat1</b> table cannot | ||
218 | be <a href="#droptable">DROP</a>ped, | ||
219 | but all the content can be <a href="#delete">DELETE</a>d which has the | ||
220 | same effect.</p> | ||
221 | } | ||
222 | |||
223 | Section {ATTACH DATABASE} attach | ||
224 | |||
225 | Syntax {sql-statement} { | ||
226 | ATTACH [DATABASE] <database-filename> AS <database-name> | ||
227 | } | ||
228 | |||
229 | puts { | ||
230 | <p>The ATTACH DATABASE statement adds another database | ||
231 | file to the current database connection. If the filename contains | ||
232 | punctuation characters it must be quoted. The names 'main' and | ||
233 | 'temp' refer to the main database and the database used for | ||
234 | temporary tables. These cannot be detached. Attached databases | ||
235 | are removed using the <a href="#detach">DETACH DATABASE</a> | ||
236 | statement.</p> | ||
237 | |||
238 | <p>You can read from and write to an attached database and you | ||
239 | can modify the schema of the attached database. This is a new | ||
240 | feature of SQLite version 3.0. In SQLite 2.8, schema changes | ||
241 | to attached databases were not allowed.</p> | ||
242 | |||
243 | <p>You cannot create a new table with the same name as a table in | ||
244 | an attached database, but you can attach a database which contains | ||
245 | tables whose names are duplicates of tables in the main database. It is | ||
246 | also 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 | ||
250 | a duplicate table name in the main database, it doesn't require a | ||
251 | database name prefix. When a database is attached, all of its | ||
252 | tables which don't have duplicate names become the default table | ||
253 | of that name. Any tables of that name attached afterwards require the table | ||
254 | prefix. If the default table of a given name is detached, then | ||
255 | the last table of that name attached becomes the new default.</p> | ||
256 | |||
257 | <p> | ||
258 | Transactions involving multiple attached databases are atomic, | ||
259 | assuming that the main database is not ":memory:". If the main | ||
260 | database is ":memory:" then | ||
261 | transactions continue to be atomic within each individual | ||
262 | database file. But if the host computer crashes in the middle | ||
263 | of a COMMIT where two or more database files are updated, | ||
264 | some of those files might get the changes where others | ||
265 | might not. | ||
266 | Atomic commit of attached databases is a new feature of SQLite version 3.0. | ||
267 | In SQLite version 2.8, all commits to attached databases behaved as if | ||
268 | the main database were ":memory:". | ||
269 | </p> | ||
270 | |||
271 | <p>There is a compile-time limit of 10 attached database files.</p> | ||
272 | } | ||
273 | |||
274 | |||
275 | Section {BEGIN TRANSACTION} transaction | ||
276 | |||
277 | Syntax {sql-statement} { | ||
278 | BEGIN [ DEFERRED | IMMEDIATE | EXCLUSIVE ] [TRANSACTION [<name>]] | ||
279 | } | ||
280 | Syntax {sql-statement} { | ||
281 | END [TRANSACTION [<name>]] | ||
282 | } | ||
283 | Syntax {sql-statement} { | ||
284 | COMMIT [TRANSACTION [<name>]] | ||
285 | } | ||
286 | Syntax {sql-statement} { | ||
287 | ROLLBACK [TRANSACTION [<name>]] | ||
288 | } | ||
289 | |||
290 | puts { | ||
291 | |||
292 | <p> | ||
293 | No changes can be made to the database except within a transaction. | ||
294 | Any command that changes the database (basically, any SQL command | ||
295 | other than SELECT) will automatically start a transaction if | ||
296 | one is not already in effect. Automatically started transactions | ||
297 | are committed at the conclusion of the command. | ||
298 | </p> | ||
299 | |||
300 | <p> | ||
301 | Transactions can be started manually using the BEGIN | ||
302 | command. Such transactions usually persist until the next | ||
303 | COMMIT or ROLLBACK command. But a transaction will also | ||
304 | ROLLBACK if the database is closed or if an error occurs | ||
305 | and the ROLLBACK conflict resolution algorithm is specified. | ||
306 | See the documentation on the <a href="#conflict">ON CONFLICT</a> | ||
307 | clause for additional information about the ROLLBACK | ||
308 | conflict resolution algorithm. | ||
309 | </p> | ||
310 | |||
311 | <p> | ||
312 | END TRANSACTION is an alias for COMMIT. | ||
313 | </p> | ||
314 | |||
315 | <p>The optional transaction name is current ignored. SQLite | ||
316 | does not recognize nested transactions at this time. | ||
317 | However, future versions of SQLite may be enhanced to support nested | ||
318 | transactions and the transaction name would then become significant. | ||
319 | Application are advised not to use the transaction name in order | ||
320 | to avoid future compatibility problems.</p> | ||
321 | |||
322 | <p> | ||
323 | Transactions can be deferred, immediate, or exclusive. | ||
324 | The default transaction behavior is deferred. | ||
325 | Deferred means that no locks are acquired | ||
326 | on the database until the database is first accessed. Thus with a | ||
327 | deferred transaction, the BEGIN statement itself does nothing. Locks | ||
328 | are not acquired until the first read or write operation. The first read | ||
329 | operation against a database creates a SHARED lock and the first | ||
330 | write operation creates a RESERVED lock. Because the acquisition of | ||
331 | locks is deferred until they are needed, it is possible that another | ||
332 | thread or process could create a separate transaction and write to | ||
333 | the database after the BEGIN on the current thread has executed. | ||
334 | If the transaction is immediate, then RESERVED locks | ||
335 | are acquired on all databases as soon as the BEGIN command is | ||
336 | executed, without waiting for the | ||
337 | database to be used. After a BEGIN IMMEDIATE, you are guaranteed that | ||
338 | no other thread or process will be able to write to the database or | ||
339 | do a BEGIN IMMEDIATE or BEGIN EXCLUSIVE. Other processes can continue | ||
340 | to read from the database, however. An exclusive transaction causes | ||
341 | EXCLUSIVE locks to be acquired on all databases. After a BEGIN | ||
342 | EXCLUSIVE, you are guaranteed that no other thread or process will | ||
343 | be able to read or write the database until the transaction is | ||
344 | complete. | ||
345 | </p> | ||
346 | |||
347 | <p> | ||
348 | A description of the meaning of SHARED, RESERVED, and EXCLUSIVE locks | ||
349 | is available <a href="lockingv3.html">separately</a>. | ||
350 | </p> | ||
351 | |||
352 | <p> | ||
353 | The COMMIT command does not actually perform a commit until all | ||
354 | pending SQL commands finish. Thus if two or more SELECT statements | ||
355 | are in the middle of processing and a COMMIT is executed, the commit | ||
356 | will not actually occur until all SELECT statements finish. | ||
357 | </p> | ||
358 | |||
359 | <p> | ||
360 | An attempt to execute COMMIT might result in an SQLITE_BUSY return code. | ||
361 | This indicates that another thread or process had a read lock on the database | ||
362 | that prevented the database from being updated. When COMMIT fails in this | ||
363 | way, the transaction remains active and the COMMIT can be retried later | ||
364 | after 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 | ||
370 | transaction may or may not be rolled back automatically. The | ||
371 | errors 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> | ||
382 | For all of these errors, SQLite attempts to undo just the one statement | ||
383 | it was working on and leave changes from prior statements within the | ||
384 | same transaction intact and continue with the transaction. However, | ||
385 | depending on the statement being evaluated and the point at which the | ||
386 | error occurs, it might be necessary for SQLite to rollback and | ||
387 | cancel the transaction. An application can tell which | ||
388 | course of action SQLite took by using the | ||
389 | <a href="capi3ref.html#sqlite3_get_autocommit">sqlite3_get_autocommit()</a> | ||
390 | C-language interface.</p> | ||
391 | |||
392 | <p>It is recommended that applications respond to the errors | ||
393 | listed above by explicitly issuing a ROLLBACK command. If the | ||
394 | transaction has already been rolled back automatically | ||
395 | by the error response, then the ROLLBACK command will fail with an | ||
396 | error, but no harm is caused by this.</p> | ||
397 | |||
398 | <p>Future versions of SQLite may extend the list of errors which | ||
399 | might cause automatic transaction rollback. Future versions of | ||
400 | SQLite might change the error response. In particular, we may | ||
401 | choose to simplify the interface in future versions of SQLite by | ||
402 | causing the errors above to force an unconditional rollback.</p> | ||
403 | } | ||
404 | |||
405 | |||
406 | Section comment comment | ||
407 | |||
408 | Syntax {comment} {<SQL-comment> | <C-comment> | ||
409 | } {SQL-comment} {-- <single-line> | ||
410 | } {C-comment} {/STAR <multiple-lines> [STAR/] | ||
411 | } | ||
412 | |||
413 | puts { | ||
414 | <p> Comments aren't SQL commands, but can occur in SQL queries. They are | ||
415 | treated as whitespace by the parser. They can begin anywhere whitespace | ||
416 | can 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 | ||
422 | delimiter, they extend to the end of the input. This is not treated as | ||
423 | an error. A new SQL statement can begin on a line after a multiline | ||
424 | comment ends. C comments can be embedded anywhere whitespace can occur, | ||
425 | including inside expressions, and in the middle of other SQL statements. | ||
426 | C comments do not nest. SQL comments inside a C comment will be ignored. | ||
427 | </p> | ||
428 | } | ||
429 | |||
430 | |||
431 | Section COPY copy | ||
432 | |||
433 | Syntax {sql-statement} { | ||
434 | COPY [ OR <conflict-algorithm> ] [<database-name> .] <table-name> FROM <filename> | ||
435 | [ USING DELIMITERS <delim> ] | ||
436 | } | ||
437 | |||
438 | puts { | ||
439 | <p>The COPY command is available in SQLite version 2.8 and earlier. | ||
440 | The COPY command has been removed from SQLite version 3.0 due to | ||
441 | complications in trying to support it in a mixed UTF-8/16 environment. | ||
442 | In version 3.0, the <a href="sqlite.html">command-line shell</a> | ||
443 | contains a new command <b>.import</b> that can be used as a substitute | ||
444 | for COPY. | ||
445 | </p> | ||
446 | |||
447 | <p>The COPY command is an extension used to load large amounts of | ||
448 | data into a table. It is modeled after a similar command found | ||
449 | in PostgreSQL. In fact, the SQLite COPY command is specifically | ||
450 | designed to be able to read the output of the PostgreSQL dump | ||
451 | utility <b>pg_dump</b> so that data can be easily transferred from | ||
452 | PostgreSQL into SQLite.</p> | ||
453 | |||
454 | <p>The table-name is the name of an existing table which is to | ||
455 | be filled with data. The filename is a string or identifier that | ||
456 | names a file from which data will be read. The filename can be | ||
457 | the <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 | ||
460 | in the table. Columns are separated by tabs. If a tab occurs as | ||
461 | data within a column, then that tab is preceded by a baskslash "\" | ||
462 | character. A baskslash in the data appears as two backslashes in | ||
463 | a row. The optional USING DELIMITERS clause can specify a delimiter | ||
464 | other than tab.</p> | ||
465 | |||
466 | <p>If a column consists of the character "\N", that column is filled | ||
467 | with the value NULL.</p> | ||
468 | |||
469 | <p>The optional conflict-clause allows the specification of an alternative | ||
470 | constraint conflict resolution algorithm to use for this one command. | ||
471 | See 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 | ||
475 | by a line that contains only a baskslash and a dot:} | ||
476 | puts "\"[Operator \\.]\".</p>" | ||
477 | |||
478 | |||
479 | Section {CREATE INDEX} createindex | ||
480 | |||
481 | Syntax {sql-statement} { | ||
482 | CREATE [UNIQUE] INDEX [IF NOT EXISTS] [<database-name> .] <index-name> | ||
483 | ON <table-name> ( <column-name> [, <column-name>]* ) | ||
484 | } {column-name} { | ||
485 | <name> [ COLLATE <collation-name>] [ ASC | DESC ] | ||
486 | } | ||
487 | |||
488 | puts { | ||
489 | <p>The CREATE INDEX command consists of the keywords "CREATE INDEX" followed | ||
490 | by the name of the new index, the keyword "ON", the name of a previously | ||
491 | created table that is to be indexed, and a parenthesized list of names of | ||
492 | columns in the table that are used for the index key. | ||
493 | Each column name can be followed by one of the "ASC" or "DESC" keywords | ||
494 | to indicate sort order, but the sort order is ignored in the current | ||
495 | implementation. Sorting is always done in ascending order.</p> | ||
496 | |||
497 | <p>The COLLATE clause following each column name defines a collating | ||
498 | sequence used for text entires in that column. The default collating | ||
499 | sequence is the collating sequence defined for that column in the | ||
500 | CREATE TABLE statement. Or if no collating sequence is otherwise defined, | ||
501 | the built-in BINARY collating sequence is used.</p> | ||
502 | |||
503 | <p>There are no arbitrary limits on the number of indices that can be | ||
504 | attached 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 | ||
507 | index entries are not allowed. Any attempt to insert a duplicate entry | ||
508 | will result in an error.</p> | ||
509 | |||
510 | <p>The exact text | ||
511 | of each CREATE INDEX statement is stored in the <b>sqlite_master</b> | ||
512 | or <b>sqlite_temp_master</b> table, depending on whether the table | ||
513 | being indexed is temporary. Every time the database is opened, | ||
514 | all CREATE INDEX statements | ||
515 | are read from the <b>sqlite_master</b> table and used to regenerate | ||
516 | SQLite's internal representation of the index layout.</p> | ||
517 | |||
518 | <p>If the optional IF NOT EXISTS clause is present and another index | ||
519 | with 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> | ||
522 | command.</p> | ||
523 | } | ||
524 | |||
525 | |||
526 | Section {CREATE TABLE} {createtable} | ||
527 | |||
528 | Syntax {sql-command} { | ||
529 | CREATE [TEMP | TEMPORARY] TABLE [IF NOT EXISTS] [<database-name> .] <table-name> ( | ||
530 | <column-def> [, <column-def>]* | ||
531 | [, <constraint>]* | ||
532 | ) | ||
533 | } {sql-command} { | ||
534 | CREATE [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} { | ||
542 | NOT NULL [ <conflict-clause> ] | | ||
543 | PRIMARY KEY [<sort-order>] [ <conflict-clause> ] [AUTOINCREMENT] | | ||
544 | UNIQUE [ <conflict-clause> ] | | ||
545 | CHECK ( <expr> ) | | ||
546 | DEFAULT <value> | | ||
547 | COLLATE <collation-name> | ||
548 | } {constraint} { | ||
549 | PRIMARY KEY ( <column-list> ) [ <conflict-clause> ] | | ||
550 | UNIQUE ( <column-list> ) [ <conflict-clause> ] | | ||
551 | CHECK ( <expr> ) | ||
552 | } {conflict-clause} { | ||
553 | ON CONFLICT <conflict-algorithm> | ||
554 | } | ||
555 | |||
556 | puts { | ||
557 | <p>A CREATE TABLE statement is basically the keywords "CREATE TABLE" | ||
558 | followed by the name of a new table and a parenthesized list of column | ||
559 | definitions and constraints. The table name can be either an identifier | ||
560 | or a string. Tables names that begin with "<b>sqlite_</b>" are reserved | ||
561 | for use by the engine.</p> | ||
562 | |||
563 | <p>Each column definition is the name of the column followed by the | ||
564 | datatype for that column, then one or more optional column constraints. | ||
565 | The datatype for the column does not restrict what data may be put | ||
566 | in that column. | ||
567 | See <a href="datatype3.html">Datatypes In SQLite Version 3</a> for | ||
568 | additional information. | ||
569 | The UNIQUE constraint causes an index to be created on the specified | ||
570 | columns. This index must contain unique keys. | ||
571 | The COLLATE clause specifies what text <a href="datatype3.html#collation"> | ||
572 | collating function</a> to use when comparing text entries for the column. | ||
573 | The built-in BINARY collating function is used by default. | ||
574 | <p> | ||
575 | The DEFAULT constraint specifies a default value to use when doing an INSERT. | ||
576 | The value may be NULL, a string constant or a number. Starting with version | ||
577 | 3.1.0, the default value may also be one of the special case-independant | ||
578 | keywords CURRENT_TIME, CURRENT_DATE or CURRENT_TIMESTAMP. If the value is | ||
579 | NULL, a string constant or number, it is literally inserted into the column | ||
580 | whenever an INSERT statement that does not specify a value for the column is | ||
581 | executed. If the value is CURRENT_TIME, CURRENT_DATE or CURRENT_TIMESTAMP, then | ||
582 | the current UTC date and/or time is inserted into the columns. For | ||
583 | CURRENT_TIME, the format is HH:MM:SS. For CURRENT_DATE, YYYY-MM-DD. The format | ||
584 | for CURRENT_TIMESTAMP is "YYYY-MM-DD HH:MM:SS". | ||
585 | </p> | ||
586 | |||
587 | <p>Specifying a PRIMARY KEY normally just creates a UNIQUE index | ||
588 | on the corresponding columns. However, if primary key is on a single column | ||
589 | that has datatype INTEGER, then that column is used internally | ||
590 | as the actual key of the B-Tree for the table. This means that the column | ||
591 | may only hold unique integer values. (Except for this one case, | ||
592 | SQLite ignores the datatype specification of columns and allows | ||
593 | any kind of data to be put in a column regardless of its declared | ||
594 | datatype.) If a table does not have an INTEGER PRIMARY KEY column, | ||
595 | then the B-Tree key will be a automatically generated integer. | ||
596 | <a name="rowid"> The | ||
597 | B-Tree key for a row can always be accessed using one of the | ||
598 | special names "<b>ROWID</b>", "<b>OID</b>", or "<b>_ROWID_</b>". | ||
599 | This is true regardless of whether or not there is an INTEGER | ||
600 | PRIMARY KEY. An INTEGER PRIMARY KEY column can also include the | ||
601 | keyword AUTOINCREMENT. The AUTOINCREMENT keyword modified the way | ||
602 | that B-Tree keys are automatically generated. Additional detail | ||
603 | on 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. | ||
607 | Unfortunately, due to a long-standing coding oversight, this is not | ||
608 | the case in SQLite. SQLite allows NULL values | ||
609 | in a PRIMARY KEY column. We could change SQLite to conform to the | ||
610 | standard (and we might do so in the future), but by the time the | ||
611 | oversight was discovered, SQLite was in such wide use that we feared | ||
612 | breaking legacy code if we fixed the problem. So for now we have | ||
613 | chosen to contain allowing NULLs in PRIMARY KEY columns. | ||
614 | Developers should be aware, however, that we may change SQLite to | ||
615 | conform to the SQL standard in future and should design new programs | ||
616 | accordingly.</p> | ||
617 | |||
618 | <p>If the "TEMP" or "TEMPORARY" keyword occurs in between "CREATE" | ||
619 | and "TABLE" then the table that is created is only visible | ||
620 | within that same database connection | ||
621 | and is automatically deleted when | ||
622 | the database connection is closed. Any indices created on a temporary table | ||
623 | are also temporary. Temporary tables and indices are stored in a | ||
624 | separate file distinct from the main database file.</p> | ||
625 | |||
626 | <p> If a <database-name> is specified, then the table is created in | ||
627 | the named database. It is an error to specify both a <database-name> | ||
628 | and the TEMP keyword, unless the <database-name> is "temp". If no | ||
629 | database name is specified, and the TEMP keyword is not present, | ||
630 | the table is created in the main database.</p> | ||
631 | |||
632 | <p>The optional conflict-clause following each constraint | ||
633 | allows the specification of an alternative default | ||
634 | constraint conflict resolution algorithm for that constraint. | ||
635 | The default is abort ABORT. Different constraints within the same | ||
636 | table may have different default conflict resolution algorithms. | ||
637 | If an COPY, INSERT, or UPDATE command specifies a different conflict | ||
638 | resolution algorithm, then that algorithm is used in place of the | ||
639 | default algorithm specified in the CREATE TABLE statement. | ||
640 | See 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 | ||
644 | to version 3.3.0, CHECK constraints were parsed but not enforced.</p> | ||
645 | |||
646 | <p>There are no arbitrary limits on the number | ||
647 | of columns or on the number of constraints in a table. | ||
648 | The total amount of data in a single row is limited to about | ||
649 | 1 megabytes in version 2.8. In version 3.0 there is no arbitrary | ||
650 | limit on the amount of data in a row.</p> | ||
651 | |||
652 | |||
653 | <p>The CREATE TABLE AS form defines the table to be | ||
654 | the result set of a query. The names of the table columns are | ||
655 | the names of the columns in the result.</p> | ||
656 | |||
657 | <p>The exact text | ||
658 | of each CREATE TABLE statement is stored in the <b>sqlite_master</b> | ||
659 | table. Every time the database is opened, all CREATE TABLE statements | ||
660 | are read from the <b>sqlite_master</b> table and used to regenerate | ||
661 | SQLite's internal representation of the table layout. | ||
662 | If the original command was a CREATE TABLE AS then then an equivalent | ||
663 | CREATE TABLE statement is synthesized and store in <b>sqlite_master</b> | ||
664 | in place of the original command. | ||
665 | The 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 | ||
670 | with 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> | ||
673 | statement. </p> | ||
674 | } | ||
675 | |||
676 | |||
677 | Section {CREATE TRIGGER} createtrigger | ||
678 | |||
679 | Syntax {sql-statement} { | ||
680 | CREATE [TEMP | TEMPORARY] TRIGGER [IF NOT EXISTS] <trigger-name> [ BEFORE | AFTER ] | ||
681 | <database-event> ON [<database-name> .] <table-name> | ||
682 | <trigger-action> | ||
683 | } | ||
684 | |||
685 | Syntax {sql-statement} { | ||
686 | CREATE [TEMP | TEMPORARY] TRIGGER [IF NOT EXISTS] <trigger-name> INSTEAD OF | ||
687 | <database-event> ON [<database-name> .] <view-name> | ||
688 | <trigger-action> | ||
689 | } | ||
690 | |||
691 | Syntax {database-event} { | ||
692 | DELETE | | ||
693 | INSERT | | ||
694 | UPDATE | | ||
695 | UPDATE OF <column-list> | ||
696 | } | ||
697 | |||
698 | Syntax {trigger-action} { | ||
699 | [ FOR EACH ROW ] [ WHEN <expression> ] | ||
700 | BEGIN | ||
701 | <trigger-step> ; [ <trigger-step> ; ]* | ||
702 | END | ||
703 | } | ||
704 | |||
705 | Syntax {trigger-step} { | ||
706 | <update-statement> | <insert-statement> | | ||
707 | <delete-statement> | <select-statement> | ||
708 | } | ||
709 | |||
710 | puts { | ||
711 | <p>The CREATE TRIGGER statement is used to add triggers to the | ||
712 | database schema. Triggers are database operations (the <i>trigger-action</i>) | ||
713 | that 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 | ||
717 | particular database table occurs, or whenever an UPDATE of one or more | ||
718 | specified columns of a table are updated.</p> | ||
719 | |||
720 | <p>At this time SQLite supports only FOR EACH ROW triggers, not FOR EACH | ||
721 | STATEMENT triggers. Hence explicitly specifying FOR EACH ROW is optional. FOR | ||
722 | EACH ROW implies that the SQL statements specified as <i>trigger-steps</i> | ||
723 | may be executed (depending on the WHEN clause) for each database row being | ||
724 | inserted, 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 | ||
727 | the 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 | ||
730 | is 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> | ||
752 | will be executed relative to the insertion, modification or removal of the | ||
753 | associated 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 | ||
757 | the statement causing the trigger to fire, then this conflict handling | ||
758 | policy is used instead.</p> | ||
759 | |||
760 | <p>Triggers are automatically dropped when the table that they are | ||
761 | associated with is dropped.</p> | ||
762 | |||
763 | <p>Triggers may be created on views, as well as ordinary tables, by specifying | ||
764 | INSTEAD OF in the CREATE TRIGGER statement. If one or more ON INSERT, ON DELETE | ||
765 | or ON UPDATE triggers are defined on a view, then it is not an error to execute | ||
766 | an INSERT, DELETE or UPDATE statement on the view, respectively. Thereafter, | ||
767 | executing 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 | ||
774 | that order records are stored in the "orders" table, the following trigger | ||
775 | ensures that all associated orders are redirected when a customer changes | ||
776 | his or her address:</p> | ||
777 | } | ||
778 | Example { | ||
779 | CREATE 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 | } | ||
784 | puts { | ||
785 | <p>With this trigger installed, executing the statement:</p> | ||
786 | } | ||
787 | |||
788 | Example { | ||
789 | UPDATE customers SET address = '1 Main St.' WHERE name = 'Jack Jones'; | ||
790 | } | ||
791 | puts { | ||
792 | <p>causes the following to be automatically executed:</p> | ||
793 | } | ||
794 | Example { | ||
795 | UPDATE orders SET address = '1 Main St.' WHERE customer_name = 'Jack Jones'; | ||
796 | } | ||
797 | |||
798 | puts { | ||
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 | |||
807 | puts { | ||
808 | <p>A special SQL function RAISE() may be used within a trigger-program, with the following syntax</p> | ||
809 | } | ||
810 | Syntax {raise-function} { | ||
811 | RAISE ( ABORT, <error-message> ) | | ||
812 | RAISE ( FAIL, <error-message> ) | | ||
813 | RAISE ( ROLLBACK, <error-message> ) | | ||
814 | RAISE ( IGNORE ) | ||
815 | } | ||
816 | puts { | ||
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, | ||
821 | the 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> | ||
829 | statement.</p> | ||
830 | } | ||
831 | |||
832 | |||
833 | Section {CREATE VIEW} {createview} | ||
834 | |||
835 | Syntax {sql-command} { | ||
836 | CREATE [TEMP | TEMPORARY] VIEW [IF NOT EXISTS] [<database-name>.] <view-name> AS <select-statement> | ||
837 | } | ||
838 | |||
839 | puts { | ||
840 | <p>The CREATE VIEW command assigns a name to a pre-packaged | ||
841 | <a href="#select">SELECT</a> | ||
842 | statement. Once the view is created, it can be used in the FROM clause | ||
843 | of another SELECT in place of a table name. | ||
844 | </p> | ||
845 | |||
846 | <p>If the "TEMP" or "TEMPORARY" keyword occurs in between "CREATE" | ||
847 | and "VIEW" then the view that is created is only visible to the | ||
848 | process that opened the database and is automatically deleted when | ||
849 | the database is closed.</p> | ||
850 | |||
851 | <p> If a <database-name> is specified, then the view is created in | ||
852 | the named database. It is an error to specify both a <database-name> | ||
853 | and the TEMP keyword, unless the <database-name> is "temp". If no | ||
854 | database name is specified, and the TEMP keyword is not present, | ||
855 | the table is created in the main database.</p> | ||
856 | |||
857 | <p>You cannot COPY, DELETE, INSERT or UPDATE a view. Views are read-only | ||
858 | in SQLite. However, in many cases you can use a <a href="#createtrigger"> | ||
859 | TRIGGER</a> on the view to accomplish the same thing. Views are removed | ||
860 | with the <a href="#dropview">DROP VIEW</a> | ||
861 | command.</p> | ||
862 | } | ||
863 | |||
864 | Section {CREATE VIRTUAL TABLE} {createvtab} | ||
865 | |||
866 | Syntax {sql-command} { | ||
867 | CREATE VIRTUAL TABLE [<database-name> .] <table-name> USING <module-name> [( <arguments> )] | ||
868 | } | ||
869 | |||
870 | puts { | ||
871 | <p>A virtual table is an interface to an external storage or computation | ||
872 | engine that appears to be a table but does not actually store information | ||
873 | in the database file.</p> | ||
874 | |||
875 | <p>In general, you can do anything with a virtual table that can be done | ||
876 | with an ordinary table, except that you cannot create triggers on a | ||
877 | virtual table. Some virtual table implementations might impose additional | ||
878 | restrictions. For example, many virtual tables are read-only.</p> | ||
879 | |||
880 | <p>The <module-name> is the name of an object that implements | ||
881 | the virtual table. The <module-name> must be registered with | ||
882 | the SQLite database connection using | ||
883 | <a href="capi3ref.html#sqlite3_create_module">sqlite3_create_module</a> | ||
884 | prior to issuing the CREATE VIRTUAL TABLE statement. | ||
885 | The module takes zero or more comma-separated arguments. | ||
886 | The arguments can be just about any text as long as it has balanced | ||
887 | parentheses. The argument syntax is sufficiently general that the | ||
888 | arguments can be made to appear as column definitions in a traditional | ||
889 | <a href="#createtable">CREATE TABLE</a> statement. | ||
890 | SQLite passes the module arguments directly | ||
891 | to the module without any interpretation. It is the responsibility | ||
892 | of 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 | ||
896 | DROP VIRTUAL TABLE statement.</p> | ||
897 | } | ||
898 | |||
899 | Section DELETE delete | ||
900 | |||
901 | Syntax {sql-statement} { | ||
902 | DELETE FROM [<database-name> .] <table-name> [WHERE <expr>] | ||
903 | } | ||
904 | |||
905 | puts { | ||
906 | <p>The DELETE command is used to remove records from a table. | ||
907 | The command consists of the "DELETE FROM" keywords followed by | ||
908 | the 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. | ||
912 | If a WHERE clause is supplied, then only those rows that match | ||
913 | the expression are removed.</p> | ||
914 | } | ||
915 | |||
916 | |||
917 | Section {DETACH DATABASE} detach | ||
918 | |||
919 | Syntax {sql-command} { | ||
920 | DETACH [DATABASE] <database-name> | ||
921 | } | ||
922 | |||
923 | puts { | ||
924 | <p>This statement detaches an additional database connection previously | ||
925 | attached using the <a href="#attach">ATTACH DATABASE</a> statement. It | ||
926 | is possible to have the same database file attached multiple times using | ||
927 | different names, and detaching one connection to a file will leave the | ||
928 | others intact.</p> | ||
929 | |||
930 | <p>This statement will fail if SQLite is in the middle of a transaction.</p> | ||
931 | } | ||
932 | |||
933 | |||
934 | Section {DROP INDEX} dropindex | ||
935 | |||
936 | Syntax {sql-command} { | ||
937 | DROP INDEX [IF EXISTS] [<database-name> .] <index-name> | ||
938 | } | ||
939 | |||
940 | puts { | ||
941 | <p>The DROP INDEX statement removes an index added | ||
942 | with the <a href="#createindex"> | ||
943 | CREATE INDEX</a> statement. The index named is completely removed from | ||
944 | the disk. The only way to recover the index is to reenter the | ||
945 | appropriate CREATE INDEX command.</p> | ||
946 | |||
947 | <p>The DROP INDEX statement does not reduce the size of the database | ||
948 | file in the default mode. | ||
949 | Empty space in the database is retained for later INSERTs. To | ||
950 | remove free space in the database, use the <a href="#vacuum">VACUUM</a> | ||
951 | command. If AUTOVACUUM mode is enabled for a database then space | ||
952 | will be freed automatically by DROP INDEX.</p> | ||
953 | } | ||
954 | |||
955 | |||
956 | Section {DROP TABLE} droptable | ||
957 | |||
958 | Syntax {sql-command} { | ||
959 | DROP TABLE [IF EXISTS] [<database-name>.] <table-name> | ||
960 | } | ||
961 | |||
962 | puts { | ||
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 | ||
965 | table name. It is completely removed from the database schema and the | ||
966 | disk file. The table can not be recovered. All indices associated | ||
967 | with the table are also deleted.</p> | ||
968 | |||
969 | <p>The DROP TABLE statement does not reduce the size of the database | ||
970 | file in the default mode. Empty space in the database is retained for | ||
971 | later INSERTs. To | ||
972 | remove free space in the database, use the <a href="#vacuum">VACUUM</a> | ||
973 | command. If AUTOVACUUM mode is enabled for a database then space | ||
974 | will be freed automatically by DROP TABLE.</p> | ||
975 | |||
976 | <p>The optional IF EXISTS clause suppresses the error that would normally | ||
977 | result if the table does not exist.</p> | ||
978 | } | ||
979 | |||
980 | |||
981 | Section {DROP TRIGGER} droptrigger | ||
982 | Syntax {sql-statement} { | ||
983 | DROP TRIGGER [IF EXISTS] [<database-name> .] <trigger-name> | ||
984 | } | ||
985 | puts { | ||
986 | <p>The DROP TRIGGER statement removes a trigger created by the | ||
987 | <a href="#createtrigger">CREATE TRIGGER</a> statement. The trigger is | ||
988 | deleted from the database schema. Note that triggers are automatically | ||
989 | dropped when the associated table is dropped.</p> | ||
990 | } | ||
991 | |||
992 | |||
993 | Section {DROP VIEW} dropview | ||
994 | |||
995 | Syntax {sql-command} { | ||
996 | DROP VIEW [IF EXISTS] <view-name> | ||
997 | } | ||
998 | |||
999 | puts { | ||
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 | ||
1002 | view name. It is removed from the database schema, but no actual data | ||
1003 | in the underlying base tables is modified.</p> | ||
1004 | } | ||
1005 | |||
1006 | |||
1007 | Section EXPLAIN explain | ||
1008 | |||
1009 | Syntax {sql-statement} { | ||
1010 | EXPLAIN <sql-statement> | ||
1011 | } | ||
1012 | |||
1013 | puts { | ||
1014 | <p>The EXPLAIN command modifier is a non-standard extension. The | ||
1015 | idea comes from a similar command found in PostgreSQL, but the operation | ||
1016 | is completely different.</p> | ||
1017 | |||
1018 | <p>If the EXPLAIN keyword appears before any other SQLite SQL command | ||
1019 | then instead of actually executing the command, the SQLite library will | ||
1020 | report back the sequence of virtual machine instructions it would have | ||
1021 | used to execute the command had the EXPLAIN keyword not been present. | ||
1022 | For additional information about virtual machine instructions see | ||
1023 | the <a href="arch.html">architecture description</a> or the documentation | ||
1024 | on <a href="opcode.html">available opcodes</a> for the virtual machine.</p> | ||
1025 | } | ||
1026 | |||
1027 | |||
1028 | Section expression expr | ||
1029 | |||
1030 | Syntax {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> ) | | ||
1048 | CASE [<expr>] LP WHEN <expr> THEN <expr> RPPLUS [ELSE <expr>] END | | ||
1049 | CAST ( <expr> AS <type> ) | | ||
1050 | <expr> COLLATE <collation-name> | ||
1051 | } {like-op} { | ||
1052 | LIKE | GLOB | REGEXP | MATCH | ||
1053 | } | ||
1054 | |||
1055 | puts { | ||
1056 | <p>This section is different from the others. Most other sections of | ||
1057 | this document talks about a particular SQL command. This section does | ||
1058 | not talk about a standalone command but about "expressions" which are | ||
1059 | subcomponents of most other commands.</p> | ||
1060 | |||
1061 | <p>SQLite understands the following binary operators, in order from | ||
1062 | highest to lowest precedence:</p> | ||
1063 | |||
1064 | <blockquote><pre> | ||
1065 | <font color="#2c2cf0"><big>|| | ||
1066 | * / % | ||
1067 | + - | ||
1068 | << >> & | | ||
1069 | < <= > >= | ||
1070 | = == != <> </big>IN | ||
1071 | AND | ||
1072 | OR</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 | ||
1082 | operator. The COLLATE operator has the highest precedence. | ||
1083 | It always binds more tightly than any prefix unary operator or | ||
1084 | any binary operator.</p> | ||
1085 | |||
1086 | <p>The unary operator [Operator +] is a no-op. It can be applied | ||
1087 | to strings, numbers, or blobs and it always gives as its result the | ||
1088 | value of the operand.</p> | ||
1089 | |||
1090 | <p>Note that there are two variations of the equals and not equals | ||
1091 | operators. Equals can be either} | ||
1092 | puts "[Operator =] or [Operator ==]. | ||
1093 | The non-equals operator can be either | ||
1094 | [Operator !=] or [Operator {<>}]. | ||
1095 | The [Operator ||] operator is \"concatenate\" - it joins together | ||
1096 | the two strings of its operands. | ||
1097 | The operator [Operator %] outputs the remainder of its left | ||
1098 | operand modulo its right operand.</p> | ||
1099 | |||
1100 | <p>The result of any binary operator is a numeric value, except | ||
1101 | for the [Operator ||] concatenation operator which gives a string | ||
1102 | result.</p>" | ||
1103 | |||
1104 | puts { | ||
1105 | |||
1106 | <a name="literal_value"></a> | ||
1107 | <p> | ||
1108 | A literal value is an integer number or a floating point number. | ||
1109 | Scientific notation is supported. The "." character is always used | ||
1110 | as the decimal point even if the locale setting specifies "," for | ||
1111 | this role - the use of "," for the decimal point would result in | ||
1112 | syntactic ambiguity. A string constant is formed by enclosing the | ||
1113 | string in single quotes ('). A single quote within the string can | ||
1114 | be encoded by putting two single quotes in a row - as in Pascal. | ||
1115 | C-style escapes using the backslash character are not supported because | ||
1116 | they are not standard SQL. | ||
1117 | BLOB literals are string literals containing hexadecimal data and | ||
1118 | preceded by a single "x" or "X" character. For example:</p> | ||
1119 | |||
1120 | <blockquote><pre> | ||
1121 | X'53514C697465' | ||
1122 | </pre></blockquote> | ||
1123 | |||
1124 | <p> | ||
1125 | A literal value can also be the token "NULL". | ||
1126 | </p> | ||
1127 | |||
1128 | <p> | ||
1129 | A parameter specifies a placeholder in the expression for a literal | ||
1130 | value that is filled in at runtime using the | ||
1131 | <a href="capi3ref.html#sqlite3_bind_int">sqlite3_bind</a> API. | ||
1132 | Parameters 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 | ||
1140 | NNN-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 | ||
1145 | the 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 | ||
1150 | parameter with the name AAAA. Named parameters are also numbered. | ||
1151 | The number assigned is the next unused number. To avoid confusion, | ||
1152 | it 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 | ||
1161 | parameter with the name AAAA. The identifier name in this case can include | ||
1162 | one or more occurances of "::" and a suffix enclosed in "(...)" containing | ||
1163 | any text at all. This syntax is the form of a variable name in the Tcl | ||
1164 | programming 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 | ||
1171 | as NULL.</p> | ||
1172 | |||
1173 | <a name="like"></a> | ||
1174 | <p>The LIKE operator does a pattern matching comparison. The operand | ||
1175 | to the right contains the pattern, the left hand operand contains the | ||
1176 | string to match against the pattern. | ||
1177 | } | ||
1178 | puts "A percent symbol [Operator %] in the pattern matches any | ||
1179 | sequence of zero or more characters in the string. An underscore | ||
1180 | [Operator _] in the pattern matches any single character in the | ||
1181 | string. Any other character matches itself or it's lower/upper case | ||
1182 | equivalent (i.e. case-insensitive matching). (A bug: SQLite only | ||
1183 | understands upper/lower case for 7-bit Latin characters. Hence the | ||
1184 | LIKE operator is case sensitive for 8-bit iso8859 characters or UTF-8 | ||
1185 | characters. For example, the expression <b>'a' LIKE 'A'</b> | ||
1186 | is TRUE but <b>'æ' LIKE 'Æ'</b> is FALSE.).</p>" | ||
1187 | |||
1188 | puts { | ||
1189 | <p>If the optional ESCAPE clause is present, then the expression | ||
1190 | following the ESCAPE keyword must evaluate to a string consisting of | ||
1191 | a single character. This character may be used in the LIKE pattern | ||
1192 | to include literal percent or underscore characters. The escape | ||
1193 | character followed by a percent symbol, underscore or itself matches a | ||
1194 | literal percent symbol, underscore or escape character in the string, | ||
1195 | respectively. The infix LIKE operator is implemented by calling the | ||
1196 | user function <a href="#likeFunc"> like(<i>X</i>,<i>Y</i>)</a>.</p> | ||
1197 | } | ||
1198 | |||
1199 | puts { | ||
1200 | The LIKE operator is not case sensitive and will match upper case | ||
1201 | characters on one side against lower case characters on the other. | ||
1202 | (A bug: SQLite only understands upper/lower case for 7-bit Latin | ||
1203 | characters. Hence the LIKE operator is case sensitive for 8-bit | ||
1204 | iso8859 characters or UTF-8 characters. For example, the expression | ||
1205 | <b>'a' LIKE 'A'</b> is TRUE but | ||
1206 | <b>'æ' LIKE 'Æ'</b> is FALSE.).</p> | ||
1207 | |||
1208 | <p>The infix LIKE | ||
1209 | operator is implemented by calling the user function <a href="#likeFunc"> | ||
1210 | like(<i>X</i>,<i>Y</i>)</a>. If an ESCAPE clause is present, it adds | ||
1211 | a third parameter to the function call. If the functionality of LIKE can be | ||
1212 | overridden by defining an alternative implementation of the | ||
1213 | like() SQL function.</p> | ||
1214 | </p> | ||
1215 | |||
1216 | <a name="glob"></a> | ||
1217 | <p>The GLOB operator is similar to LIKE but uses the Unix | ||
1218 | file globbing syntax for its wildcards. Also, GLOB is case | ||
1219 | sensitive, unlike LIKE. Both GLOB and LIKE may be preceded by | ||
1220 | the NOT keyword to invert the sense of the test. The infix GLOB | ||
1221 | operator is implemented by calling the user function <a href="#globFunc"> | ||
1222 | glob(<i>X</i>,<i>Y</i>)</a> and can be modified by overriding | ||
1223 | that function.</p> | ||
1224 | |||
1225 | <a name="regexp"></a> | ||
1226 | <p>The REGEXP operator is a special syntax for the regexp() | ||
1227 | user function. No regexp() user function is defined by default | ||
1228 | and so use of the REGEXP operator will normally result in an | ||
1229 | error message. If a user-defined function named "regexp" | ||
1230 | is added at run-time, that function will be called in order | ||
1231 | to implement the REGEXP operator.</p> | ||
1232 | |||
1233 | <a name="match"></a> | ||
1234 | <p>The MATCH operator is a special syntax for the match() | ||
1235 | user function. The default match() function implementation | ||
1236 | raises and exception and is not really useful for anything. | ||
1237 | But extensions can override the match() function with more | ||
1238 | helpful logic.</p> | ||
1239 | |||
1240 | <p>A column name can be any of the names defined in the CREATE TABLE | ||
1241 | statement or one of the following special identifiers: "<b>ROWID</b>", | ||
1242 | "<b>OID</b>", or "<b>_ROWID_</b>". | ||
1243 | These special identifiers all describe the | ||
1244 | unique integer key (the "row key") associated with every | ||
1245 | row of every table. | ||
1246 | The special identifiers only refer to the row key if the CREATE TABLE | ||
1247 | statement does not define a real column with the same name. Row keys | ||
1248 | act like read-only columns. A row key can be used anywhere a regular | ||
1249 | column can be used, except that you cannot change the value | ||
1250 | of 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 | ||
1254 | right-hand operand of the IN operator, as a scalar quantity, or | ||
1255 | as the operand of an EXISTS operator. | ||
1256 | As a scalar quantity or the operand of an IN operator, | ||
1257 | the SELECT should have only a single column in its | ||
1258 | result. Compound SELECTs (connected with keywords like UNION or | ||
1259 | EXCEPT) are allowed. | ||
1260 | With the EXISTS operator, the columns in the result set of the SELECT are | ||
1261 | ignored and the expression returns TRUE if one or more rows exist | ||
1262 | and FALSE if the result set is empty. | ||
1263 | If no terms in the SELECT expression refer to value in the containing | ||
1264 | query, then the expression is evaluated once prior to any other | ||
1265 | processing and the result is reused as necessary. If the SELECT expression | ||
1266 | does contain variables from the outer query, then the SELECT is reevaluated | ||
1267 | every time it is needed.</p> | ||
1268 | |||
1269 | <p>When a SELECT is the right operand of the IN operator, the IN | ||
1270 | operator returns TRUE if the result of the left operand is any of | ||
1271 | the values generated by the select. The IN operator may be preceded | ||
1272 | by 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 | ||
1275 | operand of an IN operator, then the first row of the result of the | ||
1276 | SELECT becomes the value used in the expression. If the SELECT yields | ||
1277 | more than one result row, all rows after the first are ignored. If | ||
1278 | the 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 | ||
1281 | type specified by <type>. | ||
1282 | <type> can be any non-empty type name that is valid | ||
1283 | for the type in a column definition of a CREATE TABLE statement.</p> | ||
1284 | |||
1285 | <p>Both simple and aggregate functions are supported. A simple | ||
1286 | function can be used in any expression. Simple functions return | ||
1287 | a result immediately based on their inputs. Aggregate functions | ||
1288 | may only be used in a SELECT statement. Aggregate functions compute | ||
1289 | their 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 | ||
1295 | functions may be written in C and added to the database engine using | ||
1296 | the <a href="capi3ref.html#cfunc">sqlite3_create_function()</a> | ||
1297 | API.</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 | ||
1308 | all arguments are NULL then NULL is returned. There must be at least | ||
1309 | 2 arguments.</td> | ||
1310 | </tr> | ||
1311 | |||
1312 | <tr> | ||
1313 | <td valign="top" align="right"> | ||
1314 | <a name="globFunc"></a> | ||
1315 | glob(<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> | ||
1319 | interface can | ||
1320 | be used to override this function and thereby change the operation | ||
1321 | of 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 | ||
1327 | both 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"> | ||
1334 | hex(<i>X</i>)</td> | ||
1335 | <td valign="top">The argument is interpreted as a BLOB. The result | ||
1336 | is 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> | ||
1342 | of the last row insert from this | ||
1343 | connection to the database. This is the same value that would be returned | ||
1344 | from 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. | ||
1350 | If SQLite is configured to support UTF-8, then the number of UTF-8 | ||
1351 | characters is returned, not the number of bytes.</td> | ||
1352 | </tr> | ||
1353 | |||
1354 | <tr> | ||
1355 | <td valign="top" align="right"> | ||
1356 | <a name="likeFunc"></a> | ||
1357 | like(<i>X</i>,<i>Y</i>)<br> | ||
1358 | like(<i>X</i>,<i>Y</i>,<i>Z</i>)</td> | ||
1359 | <td valign="top"> | ||
1360 | This function is used to implement the "<b>X LIKE Y [ESCAPE Z]</b>" | ||
1361 | syntax of SQL. If the optional ESCAPE clause is present, then the | ||
1362 | user-function is invoked with three arguments. Otherwise, it is | ||
1363 | invoked with two arguments only. The | ||
1364 | <a href="capi3ref.html#sqlite3_create_function"> | ||
1365 | sqlite_create_function()</a> interface can be used to override this | ||
1366 | function and thereby change the operation of the <a | ||
1367 | href= "#like">LIKE</a> operator. When doing this, it may be important | ||
1368 | to override both the two and three argument versions of the like() | ||
1369 | function. Otherwise, different code may be called to implement the | ||
1370 | LIKE operator depending on whether or not an ESCAPE clause was | ||
1371 | specified.</td> | ||
1372 | </tr> | ||
1373 | |||
1374 | <tr> | ||
1375 | <td valign="top" align="right">load_extension(<i>X</i>)<br> | ||
1376 | load_extension(<i>X</i>,<i>Y</i>)</td> | ||
1377 | <td valign="top">Load SQLite extensions out of the shared library | ||
1378 | file named <i>X</i> using the entry point <i>Y</i>. The result | ||
1379 | is a NULL. If <i>Y</i> is omitted then the default entry point | ||
1380 | of <b>sqlite3_extension_init</b> is used. This function raises | ||
1381 | an exception if the extension fails to load or initialize correctly. | ||
1382 | |||
1383 | <p>This function will fail if the extension attempts to modify | ||
1384 | or delete a SQL function or collating sequence. The | ||
1385 | extension can add new functions or collating sequences, but cannot | ||
1386 | modify or delete existing functions or collating sequences because | ||
1387 | those functions and/or collating sequences might be used elsewhere | ||
1388 | in the currently running SQL statement. To load an extension that | ||
1389 | changes or deletes functions or collating sequences, use the | ||
1390 | <a href="capi3ref.html#sqlite3_load_extension">sqlite3_load_extension()</a> | ||
1391 | C-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 | ||
1397 | converted to lower case. The C library <b>tolower()</b> routine is used | ||
1398 | for the conversion, which means that this function might not | ||
1399 | work correctly on UTF-8 characters.</td> | ||
1400 | </tr> | ||
1401 | |||
1402 | <tr> | ||
1403 | <td valign="top" align="right"> | ||
1404 | <a name="ltrimFunc"> | ||
1405 | ltrim(<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 | ||
1407 | characters that appear in <i>Y</i> from the left side of <i>X</i>. | ||
1408 | If 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 | ||
1415 | may be strings in addition to numbers. The maximum value is determined | ||
1416 | by the usual sort order. Note that <b>max()</b> is a simple function when | ||
1417 | it has 2 or more arguments but converts to an aggregate function if given | ||
1418 | only 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 | ||
1424 | may be strings in addition to numbers. The minimum value is determined | ||
1425 | by the usual sort order. Note that <b>min()</b> is a simple function when | ||
1426 | it has 2 or more arguments but converts to an aggregate function if given | ||
1427 | only 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, | ||
1433 | otherwise 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 | ||
1439 | its argument suitable for inclusion into another SQL statement. | ||
1440 | Strings are surrounded by single-quotes with escapes on interior quotes | ||
1441 | as needed. BLOBs are encoded as hexadecimal literals. | ||
1442 | The current implementation of VACUUM uses this function. The function | ||
1443 | is 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 | ||
1450 | between -9223372036854775808 and +9223372036854775807.</td> | ||
1451 | </tr> | ||
1452 | |||
1453 | <tr> | ||
1454 | <td valign="top" align="right"> | ||
1455 | <a name="replaceFunc"> | ||
1456 | replace(<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 | ||
1458 | every occurrance of string <i>Y</i> in string <i>X</i>. The BINARY | ||
1459 | collating sequence is used for comparisons.</td> | ||
1460 | </tr> | ||
1461 | |||
1462 | <tr> | ||
1463 | <td valign="top" align="right"> | ||
1464 | <a name="randomblobFunc"> | ||
1465 | randomblob(<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 | ||
1473 | right of the decimal point. If the <i>Y</i> argument is omitted, 0 is | ||
1474 | assumed.</td> | ||
1475 | </tr> | ||
1476 | |||
1477 | <tr> | ||
1478 | <td valign="top" align="right"> | ||
1479 | <a name="rtrimFunc"> | ||
1480 | rtrim(<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 | ||
1482 | characters that appear in <i>Y</i> from the right side of <i>X</i>. | ||
1483 | If 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>. | ||
1489 | The string "?000" is returned if the argument is NULL. | ||
1490 | This function is omitted from SQLite by default. | ||
1491 | It is only available the -DSQLITE_SOUNDEX=1 compiler option | ||
1492 | is 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 | ||
1498 | that 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 | ||
1504 | with the <i>Y</i>-th character and which is <i>Z</i> characters long. | ||
1505 | The left-most character of <i>X</i> is number 1. If <i>Y</i> is negative | ||
1506 | the the first character of the substring is found by counting from the | ||
1507 | right rather than the left. If <i>X</i> is string | ||
1508 | then 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"> | ||
1515 | trim(<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 | ||
1517 | characters that appear in <i>Y</i> from both ends of <i>X</i>. | ||
1518 | If 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 | ||
1525 | return values are "null", "integer", "real", "text", and "blob". | ||
1526 | SQLite's type handling is | ||
1527 | explained 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 | ||
1533 | upper-case letters. The implementation of this function uses the C library | ||
1534 | routine <b>toupper()</b> which means it may not work correctly on | ||
1535 | UTF-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"> | ||
1541 | Return a BLOB consisting of N bytes of 0x00. SQLite | ||
1542 | manages these zeroblobs very efficiently. Zeroblobs can be used to | ||
1543 | reserve 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"> | ||
1553 | SQLite Wiki</a>.</p> | ||
1554 | |||
1555 | <a name="aggregatefunctions"></a> | ||
1556 | <b>Aggregate Functions</b> | ||
1557 | |||
1558 | <p> | ||
1559 | The aggregate functions shown below are available by default. Additional | ||
1560 | aggregate functions written in C may be added using the | ||
1561 | <a href="capi3ref.html#sqlite3_create_function">sqlite3_create_function()</a> | ||
1562 | API.</p> | ||
1563 | |||
1564 | <p> | ||
1565 | In any aggregate function that takes a single argument, that argument | ||
1566 | can be preceeded by the keyword DISTINCT. In such cases, duplicate | ||
1567 | elements are filtered before being passed into the aggregate function. | ||
1568 | For example, the function "count(distinct X)" will return the number | ||
1569 | of distinct values of column X instead of the total number of non-null | ||
1570 | values 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 | ||
1577 | group. String and BLOB values that do not look like numbers are | ||
1578 | interpreted as 0. | ||
1579 | The result of avg() is always a floating point value even if all | ||
1580 | inputs 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 | ||
1586 | that <i>X</i> is not NULL in a group. The second form (with no argument) | ||
1587 | returns 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. | ||
1593 | The 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. | ||
1599 | The usual sort order is used to determine the minimum. NULL is only returned | ||
1600 | if 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 | |||
1630 | Section INSERT insert | ||
1631 | |||
1632 | Syntax {sql-statement} { | ||
1633 | INSERT [OR <conflict-algorithm>] INTO [<database-name> .] <table-name> [(<column-list>)] VALUES(<value-list>) | | ||
1634 | INSERT [OR <conflict-algorithm>] INTO [<database-name> .] <table-name> [(<column-list>)] <select-statement> | ||
1635 | } | ||
1636 | |||
1637 | puts { | ||
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. | ||
1640 | If no column-list is specified then the number of values must | ||
1641 | be the same as the number of columns in the table. If a column-list | ||
1642 | is specified, then the number of values must match the number of | ||
1643 | specified columns. Columns of the table that do not appear in the | ||
1644 | column list are filled with the default value, or with NULL if no | ||
1645 | default value is specified. | ||
1646 | </p> | ||
1647 | |||
1648 | <p>The second form of the INSERT statement takes it data from a | ||
1649 | SELECT statement. The number of columns in the result of the | ||
1650 | SELECT must exactly match the number of columns in the table if | ||
1651 | no column list is specified, or it must match the number of columns | ||
1652 | name in the column list. A new entry is made in the table | ||
1653 | for every row of the SELECT result. The SELECT may be simple | ||
1654 | or compound.</p> | ||
1655 | |||
1656 | <p>The optional conflict-clause allows the specification of an alternative | ||
1657 | constraint conflict resolution algorithm to use during this one command. | ||
1658 | See the section titled | ||
1659 | <a href="#conflict">ON CONFLICT</a> for additional information. | ||
1660 | For compatibility with MySQL, the parser allows the use of the | ||
1661 | single keyword <a href="#replace">REPLACE</a> as an alias for "INSERT OR REPLACE". | ||
1662 | </p> | ||
1663 | } | ||
1664 | |||
1665 | |||
1666 | Section {ON CONFLICT clause} conflict | ||
1667 | |||
1668 | Syntax {conflict-clause} { | ||
1669 | ON CONFLICT <conflict-algorithm> | ||
1670 | } {conflict-algorithm} { | ||
1671 | ROLLBACK | ABORT | FAIL | IGNORE | REPLACE | ||
1672 | } | ||
1673 | |||
1674 | puts { | ||
1675 | <p>The ON CONFLICT clause is not a separate SQL command. It is a | ||
1676 | non-standard clause that can appear in many other SQL commands. | ||
1677 | It is given its own section in this document because it is not | ||
1678 | part 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 | ||
1681 | the CREATE TABLE command. For the INSERT and | ||
1682 | UPDATE commands, the keywords "ON CONFLICT" are replaced by "OR", to make | ||
1683 | the syntax seem more natural. For example, instead of | ||
1684 | "INSERT ON CONFLICT IGNORE" we have "INSERT OR IGNORE". | ||
1685 | The keywords change but the meaning of the clause is the same | ||
1686 | either way.</p> | ||
1687 | |||
1688 | <p>The ON CONFLICT clause specifies an algorithm used to resolve | ||
1689 | constraint conflicts. There are five choices: ROLLBACK, ABORT, | ||
1690 | FAIL, IGNORE, and REPLACE. The default algorithm is ABORT. This | ||
1691 | is what they mean:</p> | ||
1692 | |||
1693 | <dl> | ||
1694 | <dt><b>ROLLBACK</b></dt> | ||
1695 | <dd><p>When a constraint violation occurs, an immediate ROLLBACK | ||
1696 | occurs, thus ending the current transaction, and the command aborts | ||
1697 | with a return code of SQLITE_CONSTRAINT. If no transaction is | ||
1698 | active (other than the implied transaction that is created on every | ||
1699 | command) 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 | ||
1703 | any prior changes it might have made and aborts with a return code | ||
1704 | of SQLITE_CONSTRAINT. But no ROLLBACK is executed so changes | ||
1705 | from prior commands within the same transaction | ||
1706 | are 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 | ||
1710 | return code SQLITE_CONSTRAINT. But any changes to the database that | ||
1711 | the command made prior to encountering the constraint violation | ||
1712 | are preserved and are not backed out. For example, if an UPDATE | ||
1713 | statement encountered a constraint violation on the 100th row that | ||
1714 | it attempts to update, then the first 99 row changes are preserved | ||
1715 | but 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 | ||
1719 | the constraint violation is not inserted or changed. But the command | ||
1720 | continues executing normally. Other rows before and after the row that | ||
1721 | contained the constraint violation continue to be inserted or updated | ||
1722 | normally. 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 | ||
1726 | that are causing the constraint violation are removed prior to inserting | ||
1727 | or updating the current row. Thus the insert or update always occurs. | ||
1728 | The command continues executing normally. No error is returned. | ||
1729 | If a NOT NULL constraint violation occurs, the NULL value is replaced | ||
1730 | by the default value for that column. If the column has no default | ||
1731 | value, then the ABORT algorithm is used. If a CHECK constraint violation | ||
1732 | occurs then the IGNORE algorithm is used.</p> | ||
1733 | |||
1734 | <p>When this conflict resolution strategy deletes rows in order to | ||
1735 | satisfy a constraint, it does not invoke delete triggers on those | ||
1736 | rows. 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 | ||
1740 | overrides any algorithm specified in a CREATE TABLE. | ||
1741 | If no algorithm is specified anywhere, the ABORT algorithm is used.</p> | ||
1742 | } | ||
1743 | |||
1744 | Section REINDEX reindex | ||
1745 | |||
1746 | Syntax {sql-statement} { | ||
1747 | REINDEX <collation name> | ||
1748 | } | ||
1749 | Syntax {sql-statement} { | ||
1750 | REINDEX [<database-name> .] <table/index-name> | ||
1751 | } | ||
1752 | |||
1753 | puts { | ||
1754 | <p>The REINDEX command is used to delete and recreate indices from scratch. | ||
1755 | This 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 | ||
1759 | named collation sequence are recreated. In the second form, if | ||
1760 | <i>[database-name.]table/index-name</i> identifies a table, then all indices | ||
1761 | associated with the table are rebuilt. If an index is identified, then only | ||
1762 | this 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 | ||
1766 | index and a collation sequence of the specified name, then indices associated | ||
1767 | with the collation sequence only are reconstructed. This ambiguity may be | ||
1768 | dispelled by always specifying a <i>database-name</i> when reindexing a | ||
1769 | specific table or index. | ||
1770 | } | ||
1771 | |||
1772 | Section REPLACE replace | ||
1773 | |||
1774 | Syntax {sql-statement} { | ||
1775 | REPLACE INTO [<database-name> .] <table-name> [( <column-list> )] VALUES ( <value-list> ) | | ||
1776 | REPLACE INTO [<database-name> .] <table-name> [( <column-list> )] <select-statement> | ||
1777 | } | ||
1778 | |||
1779 | puts { | ||
1780 | <p>The REPLACE command is an alias for the "INSERT OR REPLACE" variant | ||
1781 | of the <a href="#insert">INSERT</a> command. This alias is provided for | ||
1782 | compatibility with MySQL. See the | ||
1783 | <a href="#insert">INSERT</a> command documentation for additional | ||
1784 | information.</p> | ||
1785 | } | ||
1786 | |||
1787 | |||
1788 | Section SELECT select | ||
1789 | |||
1790 | Syntax {sql-statement} { | ||
1791 | SELECT [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} { | ||
1801 | STAR | <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} { | ||
1816 | UNION | UNION ALL | INTERSECT | EXCEPT | ||
1817 | } | ||
1818 | |||
1819 | puts { | ||
1820 | <p>The SELECT statement is used to query the database. The | ||
1821 | result of a SELECT is zero or more rows of data where each row | ||
1822 | has a fixed number of columns. The number of columns in the | ||
1823 | result is specified by the expression list in between the | ||
1824 | SELECT and FROM keywords. Any arbitrary expression can be used | ||
1825 | as a result. If a result expression is } | ||
1826 | puts "[Operator *] then all columns of all tables are substituted" | ||
1827 | puts {for that one expression. If the expression is the name of} | ||
1828 | puts "a table followed by [Operator .*] then the result is all columns" | ||
1829 | puts {in that one table.</p> | ||
1830 | |||
1831 | <p>The DISTINCT keyword causes a subset of result rows to be returned, | ||
1832 | in which each result row is different. NULL values are not treated as | ||
1833 | distinct from each other. The default behavior is that all result rows | ||
1834 | be 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 | ||
1837 | the FROM keyword. If multiple tables names are separated by commas, | ||
1838 | then the query is against the cross join of the various tables. | ||
1839 | The full SQL-92 join syntax can also be used to specify joins. | ||
1840 | A sub-query | ||
1841 | in parentheses may be substituted for any table name in the FROM clause. | ||
1842 | The entire FROM clause may be omitted, in which case the result is a | ||
1843 | single 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 | ||
1847 | which the query operates.</p> | ||
1848 | |||
1849 | <p>The GROUP BY clauses causes one or more rows of the result to | ||
1850 | be combined into a single row of output. This is especially useful | ||
1851 | when the result contains aggregate functions. The expressions in | ||
1852 | the GROUP BY clause do <em>not</em> have to be expressions that | ||
1853 | appear in the result. The HAVING clause is similar to WHERE except | ||
1854 | that HAVING applies after grouping has occurred. The HAVING expression | ||
1855 | may 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. | ||
1858 | The argument to ORDER BY is a list of expressions that are used as the | ||
1859 | key for the sort. The expressions do not have to be part of the | ||
1860 | result for a simple SELECT, but in a compound SELECT each sort | ||
1861 | expression must exactly match one of the result columns. Each | ||
1862 | sort expression may be optionally followed by a COLLATE keyword and | ||
1863 | the name of a collating function used for ordering text and/or | ||
1864 | keywords ASC or DESC to specify the sort order.</p> | ||
1865 | |||
1866 | <p>The LIMIT clause places an upper bound on the number of rows | ||
1867 | returned in the result. A negative LIMIT indicates no upper bound. | ||
1868 | The optional OFFSET following LIMIT specifies how many | ||
1869 | rows to skip at the beginning of the result set. | ||
1870 | In a compound query, the LIMIT clause may only appear on the | ||
1871 | final SELECT statement. | ||
1872 | The limit is applied to the entire query not | ||
1873 | to the individual SELECT statement to which it is attached. | ||
1874 | Note that if the OFFSET keyword is used in the LIMIT clause, then the | ||
1875 | limit is the first number and the offset is the second number. If a | ||
1876 | comma is used instead of the OFFSET keyword, then the offset is the | ||
1877 | first number and the limit is the second number. This seeming | ||
1878 | contradition is intentional - it maximizes compatibility with legacy | ||
1879 | SQL database systems. | ||
1880 | </p> | ||
1881 | |||
1882 | <p>A compound SELECT is formed from two or more simple SELECTs connected | ||
1883 | by one of the operators UNION, UNION ALL, INTERSECT, or EXCEPT. In | ||
1884 | a compound SELECT, all the constituent SELECTs must specify the | ||
1885 | same number of result columns. There may be only a single ORDER BY | ||
1886 | clause at the end of the compound SELECT. The UNION and UNION ALL | ||
1887 | operators combine the results of the SELECTs to the right and left into | ||
1888 | a single big table. The difference is that in UNION all result rows | ||
1889 | are distinct where in UNION ALL there may be duplicates. | ||
1890 | The INTERSECT operator takes the intersection of the results of the | ||
1891 | left and right SELECTs. EXCEPT takes the result of left SELECT after | ||
1892 | removing the results of the right SELECT. When three or more SELECTs | ||
1893 | are connected into a compound, they group from left to right.</p> | ||
1894 | } | ||
1895 | |||
1896 | |||
1897 | Section UPDATE update | ||
1898 | |||
1899 | Syntax {sql-statement} { | ||
1900 | UPDATE [ OR <conflict-algorithm> ] [<database-name> .] <table-name> | ||
1901 | SET <assignment> [, <assignment>]* | ||
1902 | [WHERE <expr>] | ||
1903 | } {assignment} { | ||
1904 | <column-name> = <expr> | ||
1905 | } | ||
1906 | |||
1907 | puts { | ||
1908 | <p>The UPDATE statement is used to change the value of columns in | ||
1909 | selected rows of a table. Each assignment in an UPDATE specifies | ||
1910 | a column name to the left of the equals sign and an arbitrary expression | ||
1911 | to the right. The expressions may use the values of other columns. | ||
1912 | All expressions are evaluated before any assignments are made. | ||
1913 | A 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 | ||
1916 | constraint conflict resolution algorithm to use during this one command. | ||
1917 | See the section titled | ||
1918 | <a href="#conflict">ON CONFLICT</a> for additional information.</p> | ||
1919 | } | ||
1920 | |||
1921 | |||
1922 | Section VACUUM vacuum | ||
1923 | |||
1924 | Syntax {sql-statement} { | ||
1925 | VACUUM [<index-or-table-name>] | ||
1926 | } | ||
1927 | |||
1928 | puts { | ||
1929 | <p>The VACUUM command is an SQLite extension modeled after a similar | ||
1930 | command found in PostgreSQL. If VACUUM is invoked with the name of a | ||
1931 | table or index then it is suppose to clean up the named table or index. | ||
1932 | In 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> | ||
1936 | VACUUM became a no-op when the GDBM backend was removed from | ||
1937 | SQLITE in version 2.0.0. | ||
1938 | VACUUM was reimplemented in version 2.8.1. | ||
1939 | The index or table name argument is now ignored. | ||
1940 | </p> | ||
1941 | |||
1942 | <p>When an object (table, index, or trigger) is dropped from the | ||
1943 | database, it leaves behind empty space. This makes the database | ||
1944 | file larger than it needs to be, but can speed up inserts. In time | ||
1945 | inserts and deletes can leave the database file structure fragmented, | ||
1946 | which slows down disk access to the database contents. | ||
1947 | |||
1948 | The VACUUM command cleans | ||
1949 | the main database by copying its contents to a temporary database file and | ||
1950 | reloading the original database file from the copy. This eliminates | ||
1951 | free pages, aligns table data to be contiguous, and otherwise cleans | ||
1952 | up 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 | ||
1956 | not have an explicit INTEGER PRIMARY KEY.</p> | ||
1957 | |||
1958 | <p>VACUUM only works on the main database. | ||
1959 | It is not possible to VACUUM an attached database file.</p> | ||
1960 | |||
1961 | <p>The VACUUM command will fail if there is an active transaction. | ||
1962 | The 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 | ||
1965 | is auto-vacuum mode, enabled using the | ||
1966 | <a href="pragma.html#pragma_auto_vacuum">auto_vacuum pragma</a>. | ||
1967 | When auto-vacuum is enabled for a database, large deletes cause | ||
1968 | the size of the database file to shrink. However, auto-vacuum | ||
1969 | also causes excess fragmentation of the database file. And auto-vacuum | ||
1970 | does not compact partially filled pages of the database as VACUUM | ||
1971 | does. | ||
1972 | </p> | ||
1973 | } | ||
1974 | |||
1975 | # A list of keywords. A asterisk occurs after the keyword if it is on | ||
1976 | # the fallback list. | ||
1977 | # | ||
1978 | set 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 | |||
2096 | puts {<DIV class="pdf_section">} | ||
2097 | Section {SQLite Keywords} keywords | ||
2098 | puts {</DIV>} | ||
2099 | |||
2100 | puts { | ||
2101 | <p>The SQL standard specifies a huge number of keywords which may not | ||
2102 | be used as the names of tables, indices, columns, databases, user-defined | ||
2103 | functions, collations, virtual table modules, or any other named object. | ||
2104 | The list of keywords is so long that few people can remember them all. | ||
2105 | For most SQL code, your safest bet is to never use any English language | ||
2106 | word 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 | ||
2109 | are 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. | ||
2132 | To help you avoid them, SQLite allows many keywords to be used unquoted | ||
2133 | as the names of databases, tables, indices, triggers, views, columns, | ||
2134 | user-defined functions, collations, attached databases, and virtual | ||
2135 | function modules. | ||
2136 | In the list of keywords that follows, those that can be used as identifiers | ||
2137 | are shown in an italic font. Keywords that must be quoted in order to be | ||
2138 | used as identifiers are shown in bold.</p> | ||
2139 | |||
2140 | <p> | ||
2141 | SQLite adds new keywords from time to time when it take on new features. | ||
2142 | So to prevent your code from being broken by future enhancements, you should | ||
2143 | normally quote any indentifier that is an English language word, even if | ||
2144 | you do not have to. | ||
2145 | </p> | ||
2146 | |||
2147 | <p> | ||
2148 | The 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 | |||
2157 | set n [llength $keyword_list] | ||
2158 | set nCol 5 | ||
2159 | set nRow [expr {($n+$nCol-1)/$nCol}] | ||
2160 | set i 0 | ||
2161 | foreach 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 | |||
2177 | puts { | ||
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 | ||
2183 | system objects. They can be used as an identifier for a different | ||
2184 | type 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 | |||
2198 | puts {<DIV class="pdf_ignore">} | ||
2199 | footer $rcsid | ||
2200 | if {[string length $outputdir]} { | ||
2201 | footer $rcsid | ||
2202 | } | ||
2203 | puts {</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 | # | ||
4 | set rcsid {$Id: limits.tcl,v 1.5 2007/08/09 00:00:26 drh Exp $} | ||
5 | source common.tcl | ||
6 | header {Implementation Limits For SQLite} | ||
7 | puts { | ||
8 | <h2>Limits In SQLite</h2> | ||
9 | |||
10 | <p> | ||
11 | "Limits" in the context of this article means sizes or | ||
12 | quantities that can not be exceeded. We are concerned | ||
13 | with things like the maximum number of bytes in a | ||
14 | BLOB or the maximum number of columns in a table. | ||
15 | </p> | ||
16 | |||
17 | <p> | ||
18 | SQLite was originally designed with a policy of avoiding | ||
19 | arbitrary limits. | ||
20 | Of course, every program that runs on a machine with finite | ||
21 | memory and disk space has limits of some kind. But in SQLite, | ||
22 | those limits | ||
23 | were not well defined. The policy was that if it would fit | ||
24 | in memory and you could count it with a 32-bit integer, then | ||
25 | it should work. | ||
26 | </p> | ||
27 | |||
28 | <p> | ||
29 | Unfortunately, the no-limits policy has been shown to create | ||
30 | problems. Because the upper bounds were not well | ||
31 | defined, they were not tested, and bugs (including possible | ||
32 | security exploits) were often found when pushing SQLite to | ||
33 | extremes. For this reason, newer versions of SQLite have | ||
34 | well-defined limits and those limits are tested as part of | ||
35 | the test suite. | ||
36 | </p> | ||
37 | |||
38 | <p> | ||
39 | This article defines what the limits of SQLite are and how they | ||
40 | can be customized for specific applications. The default settings | ||
41 | for limits are normally quite large and adequate for almost every | ||
42 | application. Some applications may what to increase a limit here | ||
43 | or there, but we expect such needs to be rare. More commonly, | ||
44 | an application might want to recompile SQLite with much lower | ||
45 | limits to avoid excess resource utilization in the event of | ||
46 | bug in higher-level SQL statement generators or to help thwart | ||
47 | attackers who inject malicious SQL statements. | ||
48 | </p> | ||
49 | } | ||
50 | proc limititem {title text} { | ||
51 | puts "<li><p><b>$title</b></p>\n$text</li>" | ||
52 | } | ||
53 | puts { | ||
54 | <ol> | ||
55 | } | ||
56 | |||
57 | limititem {Maximum length of a string or BLOB} { | ||
58 | <p> | ||
59 | The maximum number of bytes in a string or BLOB in SQLite is defined | ||
60 | by the preprocessor macro SQLITE_MAX_LENGTH. The default value | ||
61 | of this macro is 1 billion (1 thousand million or 1,000,000,000). | ||
62 | You can raise or lower this value at compile-time using a command-line | ||
63 | option like this: | ||
64 | </p> | ||
65 | |||
66 | <blockquote>-DSQLITE_MAX_LENGTH=123456789</blockquote> | ||
67 | |||
68 | <p> | ||
69 | The current implementation will only support a string or BLOB | ||
70 | length up to 2<small><sup>31</sup></small>-1 or 2147483647. And | ||
71 | some built-in functions such as hex() might fail well before that | ||
72 | point. In security-sensitive applications it is best not to | ||
73 | try to increase the maximum string and blob length. In fact, | ||
74 | you might do well to lower the maximum string and blob length | ||
75 | to something more in the range of a few million if that is | ||
76 | possible. | ||
77 | </p> | ||
78 | |||
79 | <p> | ||
80 | During part of SQLite's INSERT and SELECT processing, the complete | ||
81 | content of each row in the database is encoded as a single BLOB. | ||
82 | So the SQLITE_MAX_LENGTH parameter also determines the maximum | ||
83 | number of bytes in a row. | ||
84 | </p> | ||
85 | } | ||
86 | |||
87 | limititem {Maximum Number Of Columns} { | ||
88 | <p> | ||
89 | The SQLITE_MAX_COLUMN compile-time parameter is used to set an upper | ||
90 | bound 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> | ||
104 | The default setting for SQLITE_MAX_COLUMN is 2000. You can change it | ||
105 | at compile time to values as large as 32676. You might be able to | ||
106 | redefine this value to be as large as billions, though nobody has ever | ||
107 | tried doing that so we do not know if it will work. On the other hand, there | ||
108 | are people who will argue that a well-normalized database design | ||
109 | will never need a value larger than about 100. | ||
110 | </p> | ||
111 | |||
112 | <p> | ||
113 | In most applications, the number of columns is small - a few dozen. | ||
114 | There are places in the SQLite code generator that use algorithms | ||
115 | that are O(N²) where N is the number of columns. | ||
116 | So if you redefine SQLITE_MAX_COLUMN to be a | ||
117 | really huge number and you generate SQL that uses a large number of | ||
118 | columns, you may find that | ||
119 | <a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a> | ||
120 | runs slowly. | ||
121 | } | ||
122 | |||
123 | limititem {Maximum Length Of An SQL Statement} { | ||
124 | <p> | ||
125 | The maximum number of bytes in the text of an SQL statement is | ||
126 | limited to SQLITE_MAX_SQL_LENGTH which defaults to 1000000. You | ||
127 | can redefine this limit to be as large as the smaller of SQLITE_MAX_LENGTH | ||
128 | and 1073741824. | ||
129 | </p> | ||
130 | |||
131 | <p> | ||
132 | If an SQL statement is limited to be a million bytes in length, then | ||
133 | obviously you will not be able to insert multi-million byte strings | ||
134 | by embedding them as literals inside of INSERT statements. But | ||
135 | you should not do that anyway. Use host parameters | ||
136 | for your data. Prepare short SQL statements like this: | ||
137 | </p> | ||
138 | |||
139 | <blockquote> | ||
140 | INSERT INTO tab1 VALUES(?,?,?); | ||
141 | </blockquote> | ||
142 | |||
143 | <p> | ||
144 | Then use the | ||
145 | <a href="capi3ref.html#sqlite3_bind_text">sqlite3_bind_XXXX()</a> functions | ||
146 | to bind your large string values to the SQL statement. The use of binding | ||
147 | obviates the need to escape quote characters in the string, reducing the | ||
148 | risk of SQL injection attacks. It is also runs faster since the large | ||
149 | string does not need to be parsed or copied as much. | ||
150 | </p> | ||
151 | } | ||
152 | |||
153 | limititem {Maximum Number Of Tables In A Join} { | ||
154 | <p> | ||
155 | SQLite does not support joins containing more than 64 tables. | ||
156 | This limit arises from the fact that the SQLite code generator | ||
157 | uses bitmaps with one bit per join-table in the query optimizer. | ||
158 | </p> | ||
159 | } | ||
160 | |||
161 | limititem {Maximum Depth Of An Expression Tree} { | ||
162 | <p> | ||
163 | SQLite parses expressions into a tree for processing. During | ||
164 | code generation, SQLite walks this tree recursively. The depth | ||
165 | of expression trees is therefore limited in order to avoid | ||
166 | using too much stack space. | ||
167 | </p> | ||
168 | |||
169 | <p> | ||
170 | The SQLITE_MAX_EXPR_DEPTH parameter determines the maximum expression | ||
171 | tree depth. If the value is 0, then no limit is enforced. The | ||
172 | current implementation has a default value of 1000. | ||
173 | </p> | ||
174 | } | ||
175 | |||
176 | limititem {Maximum Number Of Arguments On A Function} { | ||
177 | <p> | ||
178 | The SQLITE_MAX_FUNCTION_ARG parameter determines the maximum number | ||
179 | of parameters that can be passed to an SQL function. The default value | ||
180 | of this limit is 100. We know of no | ||
181 | technical reason why SQLite would not work with functions that have | ||
182 | millions of parameters. However, we suspect that anybody who tries | ||
183 | to invoke a function with millions of parameters is really | ||
184 | trying to find security exploits in systems that use SQLite, | ||
185 | not do useful work, | ||
186 | and so for that reason we have set this parameter relatively low. | ||
187 | } | ||
188 | |||
189 | limititem {Maximum Number Of Terms In A Compound SELECT Statement} { | ||
190 | <p> | ||
191 | A compound SELECT statement is two or more SELECT statements connected | ||
192 | by operators UNION, UNION ALL, EXCEPT, or INTERSECT. We call each | ||
193 | individual SELECT statement within a compound SELECT a "term". | ||
194 | </p> | ||
195 | |||
196 | <p> | ||
197 | The code generator in SQLite processes compound SELECT statements using | ||
198 | a recursive algorithm. In order to limit the size of the stack, we | ||
199 | therefore limit the number of terms in a compound SELECT. The maximum | ||
200 | number of terms is SQLITE_MAX_COMPOUND_SELECT which defaults to 500. | ||
201 | We think this is a generous allotment since in practice we almost | ||
202 | never see the number of terms in a compound select exceed single digits. | ||
203 | </p> | ||
204 | } | ||
205 | |||
206 | limititem {Maximum Length Of A LIKE Or GLOB Pattern} { | ||
207 | <p> | ||
208 | The pattern matching algorithm used in the default LIKE and GLOB | ||
209 | implementation of SQLite can exhibit O(N²) performance (where | ||
210 | N is the number of characters in the pattern) for certain pathological | ||
211 | cases. To avoid denial-of-service attacks from miscreants who are able | ||
212 | to specify their own LIKE or GLOB patterns, the length of the LIKE | ||
213 | or GLOB pattern is limited to SQLITE_MAX_LIKE_PATTERN_LENGTH bytes. | ||
214 | The default value of this limit is 50000. A modern workstation can | ||
215 | evaluate even a pathological LIKE or GLOB pattern of 50000 bytes | ||
216 | relatively quickly. The denial of service problem only comes into | ||
217 | play when the pattern length gets into millions of bytes. Nevertheless, | ||
218 | since most useful LIKE or GLOB patterns are at most a few dozen bytes | ||
219 | in length, paranoid application developers may want to reduce this | ||
220 | parameter to something in the range of a few hundred if they know that | ||
221 | external users are able to generate arbitrary patterns. | ||
222 | </p> | ||
223 | } | ||
224 | |||
225 | limititem {Maximum Number Of Host Parameters In A Single SQL Statement} { | ||
226 | <p> | ||
227 | A host parameter is a place-holder in an SQL statement that is filled | ||
228 | in using one of the | ||
229 | <a href="capi3ref.html#sqlite3_bind_blob">sqlite3_bind_XXXX()</a> interfaces. | ||
230 | Many SQL programmers are familiar with using a question mark ("?") as a | ||
231 | host parameter. SQLite also supports named host parameters prefaced | ||
232 | by ":", "$", or "@" and numbered host parameters of the form "?123". | ||
233 | </p> | ||
234 | |||
235 | <p> | ||
236 | Each host parameter in an SQLite statement is assigned a number. The | ||
237 | numbers normally begin with 1 and increase by one with each new | ||
238 | parameter. However, when the "?123" form is used, the host parameter | ||
239 | number is the number that follows the question mark. | ||
240 | </p> | ||
241 | |||
242 | <p> | ||
243 | The maximum value of a host parameter number is SQLITE_MAX_VARIABLE_NUMBER. | ||
244 | This setting defaults to 999. | ||
245 | </p> | ||
246 | } | ||
247 | |||
248 | limititem {Maximum Number Of Attached Databases} { | ||
249 | <p> | ||
250 | The <a href="lang_attach.html">ATTACH</a> statement is an SQLite extension | ||
251 | that allows two or more databases to be associated to the same database | ||
252 | connection and to operate as if they were a single database. The number | ||
253 | of simulataneously attached databases is limited to SQLITE_MAX_ATTACHED | ||
254 | which is set to 10 by default. | ||
255 | The code generator in SQLite uses bitmaps | ||
256 | to keep track of attached databases. That means that the number of | ||
257 | attached databases cannot be increased above 30 on a 32-bit machine | ||
258 | or 62 on a 64-bit machine. | ||
259 | } | ||
260 | |||
261 | limititem {Maximum Database Page Size} { | ||
262 | <p> | ||
263 | An SQLite database file is organized as pages. The size of each | ||
264 | page is a power of 2 between 512 and SQLITE_MAX_PAGE_SIZE. | ||
265 | The default value for SQLITE_MAX_PAGE_SIZE is 32768. The current | ||
266 | implementation will not support a larger value. | ||
267 | </p> | ||
268 | |||
269 | <p> | ||
270 | It used to be the case that SQLite would allocate some stack | ||
271 | structures whose size was proportional to the maximum page size. | ||
272 | For this reason, SQLite would sometimes be compiled with a smaller | ||
273 | maximum page size on embedded devices with limited stack memory. But | ||
274 | more recent versions of SQLite put these large structures on the | ||
275 | heap, not on the stack, so reducing the maximum page size is no | ||
276 | longer necessary on embedded devices. | ||
277 | </p> | ||
278 | } | ||
279 | |||
280 | limititem {Maximum Number Of Pages In A Database File} { | ||
281 | <p> | ||
282 | SQLite is able to limit the size of a database file to prevent | ||
283 | the database file from growing too large and consuming too much | ||
284 | disk or flash space. | ||
285 | The SQLITE_MAX_PAGE_COUNT parameter, which is normally set to | ||
286 | 1073741823, is the maximum number of pages allowed in a single | ||
287 | database file. An attempt to insert new data that would cause | ||
288 | the database file to grow larger than this will return | ||
289 | SQLITE_FULL. | ||
290 | </p> | ||
291 | |||
292 | <p> | ||
293 | The <a href="pragma.html#pragma_max_page_count"> | ||
294 | max_page_count PRAGMA</a> can be used to raise or lower this | ||
295 | limit at run-time. | ||
296 | </p> | ||
297 | |||
298 | <p> | ||
299 | Note that the transaction processing in SQLite requires two bits | ||
300 | of heap memory for every page in the database file. For databases | ||
301 | of a few megabytes in size, this amounts to only a few hundred | ||
302 | bytes of heap memory. But for gigabyte-sized databases the amount | ||
303 | of heap memory required is getting into the kilobyte range and | ||
304 | for terabyte-sized databases, megabytes of heap memory must be | ||
305 | allocated and zeroed at each transaction. SQLite will | ||
306 | support very large databases in theory, but the current implementation | ||
307 | is optimized for the common SQLite use cases of embedded devices | ||
308 | and persistent stores for desktop applications. In other words, | ||
309 | SQLite is designed for use with databases sized in kilobytes or | ||
310 | megabytes not gigabytes. If you are building an application to | ||
311 | work with databases that are hundreds of gigabytes or more | ||
312 | in size, then you should perhaps consider using a different database | ||
313 | engine that is explicitly designed for such large data sets. | ||
314 | </p> | ||
315 | } | ||
316 | |||
317 | puts {</ol>} | ||
318 | footer $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 | # | ||
4 | set rcsid {$Id: } | ||
5 | source common.tcl | ||
6 | header {File Locking And Concurrency In SQLite Version 3} | ||
7 | |||
8 | proc 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 | } | ||
25 | set pnum(1) 0 | ||
26 | set pnum(2) 0 | ||
27 | set pnum(3) 0 | ||
28 | set pnum(4) 0 | ||
29 | set pnum(5) 0 | ||
30 | set pnum(6) 0 | ||
31 | set pnum(7) 0 | ||
32 | set pnum(8) 0 | ||
33 | |||
34 | HEADING 1 {File Locking And Concurrency In SQLite Version 3} | ||
35 | |||
36 | puts { | ||
37 | <p>Version 3 of SQLite introduces a more complex locking and journaling | ||
38 | mechanism designed to improve concurrency and reduce the writer starvation | ||
39 | problem. The new mechanism also allows atomic commits of transactions | ||
40 | involving multiple database files. | ||
41 | This document describes the new locking mechanism. | ||
42 | The intended audience is programmers who want to understand and/or modify | ||
43 | the pager code and reviewers working to verify the design | ||
44 | of SQLite version 3. | ||
45 | </p> | ||
46 | } | ||
47 | |||
48 | HEADING 1 {Overview} overview | ||
49 | |||
50 | puts { | ||
51 | <p> | ||
52 | Locking and concurrency control are handled by the the | ||
53 | <a href="http://www.sqlite.org/cvstrac/getfile/sqlite/src/pager.c"> | ||
54 | pager module</a>. | ||
55 | The pager module is responsible for making SQLite "ACID" (Atomic, | ||
56 | Consistent, Isolated, and Durable). The pager module makes sure changes | ||
57 | happen all at once, that either all changes occur or none of them do, | ||
58 | that two or more processes do not try to access the database | ||
59 | in incompatible ways at the same time, and that once changes have been | ||
60 | written they persist until explicitly deleted. The pager also provides | ||
61 | an memory cache of some of the contents of the disk file.</p> | ||
62 | |||
63 | <p>The pager is unconcerned | ||
64 | with the details of B-Trees, text encodings, indices, and so forth. | ||
65 | From the point of view of the pager the database consists of | ||
66 | a single file of uniform-sized blocks. Each block is called a | ||
67 | "page" and is usually 1024 bytes in size. The pages are numbered | ||
68 | beginning 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 | ||
70 | other encoding details are handled by higher layers of the library. | ||
71 | The pager communicates with the operating system using one of several | ||
72 | modules | ||
73 | (Examples: | ||
74 | <a href="http://www.sqlite.org/cvstrac/getfile/sqlite/src/os_unix.c"> | ||
75 | os_unix.c</a>, | ||
76 | <a href="http://www.sqlite.org/cvstrac/getfile/sqlite/src/os_win.c"> | ||
77 | os_win.c</a>) | ||
78 | that provides a uniform abstraction for operating system services. | ||
79 | </p> | ||
80 | |||
81 | <p>The pager module effectively controls access for separate threads, or | ||
82 | separate processes, or both. Throughout this document whenever the | ||
83 | word "process" is written you may substitute the word "thread" without | ||
84 | changing the truth of the statement.</p> | ||
85 | } | ||
86 | |||
87 | HEADING 1 {Locking} locking | ||
88 | |||
89 | puts { | ||
90 | <p> | ||
91 | From the point of view of a single process, a database file | ||
92 | can 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"> | ||
99 | No locks are held on the database. The database may be neither read nor | ||
100 | written. Any internally cached data is considered suspect and subject to | ||
101 | verification against the database file before being used. Other | ||
102 | processes can read or write the database as their own locking states | ||
103 | permit. This is the default state. | ||
104 | </td></tr> | ||
105 | |||
106 | <tr><td valign="top">SHARED</td> | ||
107 | <td valign="top"> | ||
108 | The database may be read but not written. Any number of | ||
109 | processes can hold SHARED locks at the same time, hence there can be | ||
110 | many simultaneous readers. But no other thread or process is allowed | ||
111 | to 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"> | ||
116 | A RESERVED lock means that the process is planning on writing to the | ||
117 | database file at some point in the future but that it is currently just | ||
118 | reading from the file. Only a single RESERVED lock may be active at one | ||
119 | time, though multiple SHARED locks can coexist with a single RESERVED lock. | ||
120 | RESERVED differs from PENDING in that new SHARED locks can be acquired | ||
121 | while there is a RESERVED lock. | ||
122 | </td></tr> | ||
123 | |||
124 | <tr><td valign="top">PENDING</td> | ||
125 | <td valign="top"> | ||
126 | A PENDING lock means that the process holding the lock wants to write | ||
127 | to the database as soon as possible and is just waiting on all current | ||
128 | SHARED locks to clear so that it can get an EXCLUSIVE lock. No new | ||
129 | SHARED locks are permitted against the database if | ||
130 | a PENDING lock is active, though existing SHARED locks are allowed to | ||
131 | continue. | ||
132 | </td></tr> | ||
133 | |||
134 | <tr><td valign="top">EXCLUSIVE</td> | ||
135 | <td valign="top"> | ||
136 | An EXCLUSIVE lock is needed in order to write to the database file. | ||
137 | Only one EXCLUSIVE lock is allowed on the file and no other locks of | ||
138 | any kind are allowed to coexist with an EXCLUSIVE lock. In order to | ||
139 | maximize concurrency, SQLite works to minimize the amount of time that | ||
140 | EXCLUSIVE locks are held. | ||
141 | </td></tr> | ||
142 | </table> | ||
143 | </p> | ||
144 | |||
145 | <p> | ||
146 | The operating system interface layer understands and tracks all five | ||
147 | locking states described above. | ||
148 | The pager module only tracks four of the five locking states. | ||
149 | A PENDING lock is always just a temporary | ||
150 | stepping stone on the path to an EXCLUSIVE lock and so the pager module | ||
151 | does not track PENDING locks. | ||
152 | </p> | ||
153 | } | ||
154 | |||
155 | HEADING 1 {The Rollback Journal} rollback | ||
156 | |||
157 | puts { | ||
158 | <p>Any time a process wants to make a changes to a database file, it | ||
159 | first records enough information in the <em>rollback journal</em> to | ||
160 | restore the database file back to its initial condition. Thus, before | ||
161 | altering any page of the database, the original contents of that page | ||
162 | must be written into the journal. The journal also records the initial | ||
163 | size of the database so that if the database file grows it can be truncated | ||
164 | back 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 | ||
167 | the 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. | ||
171 | But there is also a separate aggregate journal | ||
172 | called the <em>master journal</em>. | ||
173 | The master journal does not contain page data used for rolling back | ||
174 | changes. Instead the master journal contains the names of the | ||
175 | individual file journals for each of the ATTACHed databases. Each of | ||
176 | the individual file journals also contain the name of the master journal. | ||
177 | If there are no ATTACHed databases (or if none of the ATTACHed database | ||
178 | is participating in the current transaction) no master journal is | ||
179 | created and the normal rollback journal contains an empty string | ||
180 | in the place normally reserved for recording the name of the master | ||
181 | journal.</p> | ||
182 | |||
183 | <p>A individual file journal is said to be <em>hot</em> | ||
184 | if it needs to be rolled back | ||
185 | in order to restore the integrity of its database. | ||
186 | A hot journal is created when a process is in the middle of a database | ||
187 | update and a program or operating system crash or power failure prevents | ||
188 | the update from completing. | ||
189 | Hot journals are an exception condition. | ||
190 | Hot journals exist to recover from crashes and power failures. | ||
191 | If everything is working correctly | ||
192 | (that is, if there are no crashes or power failures) | ||
193 | you will never get a hot journal. | ||
194 | </p> | ||
195 | |||
196 | <p> | ||
197 | If no master journal is involved, then | ||
198 | a journal is hot if it exists and its corresponding database file | ||
199 | does not have a RESERVED lock. | ||
200 | If a master journal is named in the file journal, then the file journal | ||
201 | is hot if its master journal exists and there is no RESERVED | ||
202 | lock on the corresponding database file. | ||
203 | It is important to understand when a journal is hot so the | ||
204 | preceding 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 | |||
219 | HEADING 2 {Dealing with hot journals} hot_journals | ||
220 | |||
221 | puts { | ||
222 | <p> | ||
223 | Before reading from a a database file, SQLite always checks to see if that | ||
224 | database file has a hot journal. If the file does have a hot journal, then | ||
225 | the journal is rolled back before the file is read. In this way, we ensure | ||
226 | that 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 | ||
230 | the 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 | ||
259 | read from the database file. Once all reading has completed, the | ||
260 | SHARED lock is dropped.</p> | ||
261 | } | ||
262 | |||
263 | HEADING 2 {Deleting stale master journals} stale_master_journals | ||
264 | |||
265 | puts { | ||
266 | <p>A stale master journal is a master journal that is no longer being | ||
267 | used for anything. There is no requirement that stale master journals | ||
268 | be 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 | ||
271 | to it. To figure out if a master journal is stale, we first read the | ||
272 | master journal to obtain the names of all of its file journals. Then | ||
273 | we check each of those file journals. If any of the file journals named | ||
274 | in the master journal exists and points back to the master journal, then | ||
275 | the master journal is not stale. If all file journals are either missing | ||
276 | or refer to other master journals or no master journal at all, then the | ||
277 | master journal we are testing is stale and can be safely deleted.</p> | ||
278 | } | ||
279 | |||
280 | HEADING 1 {Writing to a database file} writing | ||
281 | |||
282 | puts { | ||
283 | <p>To write to a database, a process must first acquire a SHARED lock | ||
284 | as described above (possibly rolling back incomplete changes if there | ||
285 | is a hot journal). | ||
286 | After a SHARED lock is obtained, a RESERVED lock must be acquired. | ||
287 | The RESERVED lock signals that the process intends to write to the | ||
288 | database at some point in the future. Only one process at a time | ||
289 | can hold a RESERVED lock. But other processes can continue to read | ||
290 | the 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 | ||
294 | lock, it must mean that another process already has a RESERVED lock. | ||
295 | In 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 | ||
298 | creates a rollback journal. The header of the journal is initialized | ||
299 | with the original size of the database file. Space in the journal header | ||
300 | is also reserved for a master journal name, though the master journal | ||
301 | name is initially empty.</p> | ||
302 | |||
303 | <p>Before making changes to any page of the database, the process writes | ||
304 | the original content of that page into the rollback journal. Changes | ||
305 | to pages are held in memory at first and are not written to the disk. | ||
306 | The original database file remains unaltered, which means that other | ||
307 | processes can continue to read the database.</p> | ||
308 | |||
309 | <p>Eventually, the writing process will want to update the database | ||
310 | file, either because its memory cache has filled up or because it is | ||
311 | ready to commit its changes. Before this happens, the writer must | ||
312 | make sure no other process is reading the database and that the rollback | ||
313 | journal data is safely on the disk surface so that it can be used to | ||
314 | rollback incomplete changes in the event of a power failure. | ||
315 | The 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> | ||
331 | If the reason for writing to the database file is because the memory | ||
332 | cache was full, then the writer will not commit right away. Instead, | ||
333 | the writer might continue to make changes to other pages. Before | ||
334 | subsequent changes are written to the database file, the rollback | ||
335 | journal must be flushed to disk again. Note also that the EXCLUSIVE | ||
336 | lock that the writer obtained in order to write to the database initially | ||
337 | must be held until all changes are committed. That means that no other | ||
338 | processes are able to access the database from the | ||
339 | time the memory cache first spills to disk until the transaction | ||
340 | commits. | ||
341 | </p> | ||
342 | |||
343 | <p> | ||
344 | When a writer is ready to commit its changes, it executes the following | ||
345 | steps: | ||
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 | ||
367 | processes can begin reading the database again. In the current implementation, | ||
368 | the RESERVED lock is also released, but that is not essential. Future | ||
369 | versions of SQLite might provide a "CHECKPOINT" SQL command that will | ||
370 | commit all changes made so far within a transaction but retain the | ||
371 | RESERVED lock so that additional changes can be made without given | ||
372 | any other process an opportunity to write.</p> | ||
373 | |||
374 | <p>If a transaction involves multiple databases, then a more complex | ||
375 | commit 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 | |||
407 | HEADING 2 {Writer starvation} writer_starvation | ||
408 | |||
409 | puts { | ||
410 | <p>In SQLite version 2, if many processes are reading from the database, | ||
411 | it might be the case that there is never a time when there are | ||
412 | no active readers. And if there is always at least one read lock on the | ||
413 | database, no process would ever be able to make changes to the database | ||
414 | because it would be impossible to acquire a write lock. This situation | ||
415 | is called <em>writer starvation</em>.</p> | ||
416 | |||
417 | <p>SQLite version 3 seeks to avoid writer starvation through the use of | ||
418 | the PENDING lock. The PENDING lock allows existing readers to continue | ||
419 | but prevents new readers from connecting to the database. So when a | ||
420 | process wants to write a busy database, it can set a PENDING lock which | ||
421 | will prevent new readers from coming in. Assuming existing readers do | ||
422 | eventually complete, all SHARED locks will eventually clear and the | ||
423 | writer will be given a chance to make its changes.</p> | ||
424 | } | ||
425 | |||
426 | HEADING 1 {How To Corrupt Your Database Files} how_to_corrupt | ||
427 | |||
428 | puts { | ||
429 | <p>The pager module is robust but it is not completely failsafe. | ||
430 | It can be subverted. This section attempts to identify and explain | ||
431 | the risks.</p> | ||
432 | |||
433 | <p> | ||
434 | Clearly, a hardware or operating system fault that introduces incorrect data | ||
435 | into the middle of the database file or journal will cause problems. | ||
436 | Likewise, | ||
437 | if a rogue process opens a database file or journal and writes malformed | ||
438 | data into the middle of it, then the database will become corrupt. | ||
439 | There is not much that can be done about these kinds of problems | ||
440 | so they are given no further attention. | ||
441 | </p> | ||
442 | |||
443 | <p> | ||
444 | SQLite uses POSIX advisory locks to implement locking on Unix. On | ||
445 | windows it uses the LockFile(), LockFileEx(), and UnlockFile() system | ||
446 | calls. SQLite assumes that these system calls all work as advertised. If | ||
447 | that is not the case, then database corruption can result. One should | ||
448 | note that POSIX advisory locking is known to be buggy or even unimplemented | ||
449 | on many NFS implementations (including recent versions of Mac OS X) | ||
450 | and that there are reports of locking problems | ||
451 | for network filesystems under windows. Your best defense is to not | ||
452 | use SQLite for files on a network filesystem. | ||
453 | </p> | ||
454 | |||
455 | <p> | ||
456 | SQLite uses the fsync() system call to flush data to the disk under Unix and | ||
457 | it uses the FlushFileBuffers() to do the same under windows. Once again, | ||
458 | SQLite assumes that these operating system services function as advertised. | ||
459 | But it has been reported that fsync() and FlushFileBuffers() do not always | ||
460 | work correctly, especially with inexpensive IDE disks. Apparently some | ||
461 | manufactures of IDE disks have defective controller chips that report | ||
462 | that data has reached the disk surface when in fact the data is still | ||
463 | in volatile cache memory in the disk drive electronics. There are also | ||
464 | reports that windows sometimes chooses to ignore FlushFileBuffers() for | ||
465 | unspecified reasons. The author cannot verify any of these reports. | ||
466 | But if they are true, it means that database corruption is a possibility | ||
467 | following an unexpected power loss. These are hardware and/or operating | ||
468 | system bugs that SQLite is unable to defend against. | ||
469 | </p> | ||
470 | |||
471 | <p> | ||
472 | If a crash or power failure occurs and results in a hot journal but that | ||
473 | journal is deleted, the next process to open the database will not | ||
474 | know that it contains changes that need to be rolled back. The rollback | ||
475 | will not occur and the database will be left in an inconsistent state. | ||
476 | Rollback 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> | ||
493 | The last (fourth) bullet above merits additional comment. When SQLite creates | ||
494 | a journal file on Unix, it opens the directory that contains that file and | ||
495 | calls fsync() on the directory, in an effort to push the directory information | ||
496 | to disk. But suppose some other process is adding or removing unrelated | ||
497 | files to the directory that contains the database and journal at the the | ||
498 | moment of a power failure. The supposedly unrelated actions of this other | ||
499 | process might result in the journal file being dropped from the directory and | ||
500 | moved into "lost+found". This is an unlikely scenario, but it could happen. | ||
501 | The best defenses are to use a journaling filesystem or to keep the | ||
502 | database and journal in a directory by themselves. | ||
503 | </p> | ||
504 | |||
505 | <p> | ||
506 | For a commit involving multiple databases and a master journal, if the | ||
507 | various databases were on different disk volumes and a power failure occurs | ||
508 | during the commit, then when the machine comes back up the disks might | ||
509 | be remounted with different names. Or some disks might not be mounted | ||
510 | at all. When this happens the individual file journals and the master | ||
511 | journal might not be able to find each other. The worst outcome from | ||
512 | this scenario is that the commit ceases to be atomic. | ||
513 | Some databases might be rolled back and others might not. | ||
514 | All databases will continue to be self-consistent. | ||
515 | To defend against this problem, keep all databases | ||
516 | on the same disk volume and/or remount disks using exactly the same names | ||
517 | after a power failure. | ||
518 | </p> | ||
519 | } | ||
520 | |||
521 | HEADING 1 {Transaction Control At The SQL Level} transaction_control | ||
522 | |||
523 | puts { | ||
524 | <p> | ||
525 | The changes to locking and concurrency control in SQLite version 3 also | ||
526 | introduce some subtle changes in the way transactions work at the SQL | ||
527 | language level. | ||
528 | By default, SQLite version 3 operates in <em>autocommit</em> mode. | ||
529 | In autocommit mode, | ||
530 | all changes to the database are committed as soon as all operations associated | ||
531 | with the current database connection complete.</p> | ||
532 | |||
533 | <p>The SQL command "BEGIN TRANSACTION" (the TRANSACTION keyword | ||
534 | is optional) is used to take SQLite out of autocommit mode. | ||
535 | Note that the BEGIN command does not acquire any locks on the database. | ||
536 | After a BEGIN command, a SHARED lock will be acquired when the first | ||
537 | SELECT statement is executed. A RESERVED lock will be acquired when | ||
538 | the first INSERT, UPDATE, or DELETE statement is executed. No EXCLUSIVE | ||
539 | lock is acquired until either the memory cache fills up and must | ||
540 | be spilled to disk or until the transaction commits. In this way, | ||
541 | the system delays blocking read access to the file file until the | ||
542 | last possible moment. | ||
543 | </p> | ||
544 | |||
545 | <p>The SQL command "COMMIT" does not actually commit the changes to | ||
546 | disk. It just turns autocommit back on. Then, at the conclusion of | ||
547 | the command, the regular autocommit logic takes over and causes the | ||
548 | actual commit to disk to occur. | ||
549 | The SQL command "ROLLBACK" also operates by turning autocommit back on, | ||
550 | but it also sets a flag that tells the autocommit logic to rollback rather | ||
551 | than commit.</p> | ||
552 | |||
553 | <p>If the SQL COMMIT command turns autocommit on and the autocommit logic | ||
554 | then tries to commit change but fails because some other process is holding | ||
555 | a SHARED lock, then autocommit is turned back off automatically. This | ||
556 | allows the user to retry the COMMIT at a later time after the SHARED lock | ||
557 | has had an opportunity to clear.</p> | ||
558 | |||
559 | <p>If multiple commands are being executed against the same SQLite database | ||
560 | connection at the same time, the autocommit is deferred until the very | ||
561 | last command completes. For example, if a SELECT statement is being | ||
562 | executed, the execution of the command will pause as each row of the | ||
563 | result is returned. During this pause other INSERT, UPDATE, or DELETE | ||
564 | commands can be executed against other tables in the database. But none | ||
565 | of these changes will commit until the original SELECT statement finishes. | ||
566 | </p> | ||
567 | } | ||
568 | |||
569 | |||
570 | footer $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 | # | ||
4 | set rcsid {$Id: mingw.tcl,v 1.4 2003/03/30 18:58:58 drh Exp $} | ||
5 | |||
6 | puts {<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> | ||
12 | Notes On How To Build MinGW As A Cross-Compiler | ||
13 | </h1>} | ||
14 | puts "<p align=center> | ||
15 | (This page was last modified on [lrange $rcsid 3 4] UTC) | ||
16 | </p>" | ||
17 | |||
18 | puts { | ||
19 | <p><a href="http://www.mingw.org/">MinGW</a> or | ||
20 | <a href="http://www.mingw.org/">Minimalist GNU For Windows</a> | ||
21 | is a version of the popular GCC compiler that builds Win95/Win98/WinNT | ||
22 | binaries. See the website for details.</p> | ||
23 | |||
24 | <p>This page describes how you can build MinGW | ||
25 | from sources as a cross-compiler | ||
26 | running under Linux. Doing so will allow you to construct | ||
27 | WinNT binaries from the comfort and convenience of your | ||
28 | Unix desktop.</p> | ||
29 | } | ||
30 | |||
31 | proc 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 | |||
40 | puts { | ||
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 | ||
46 | compiler, and the MinGW runtime. Each are available separately. | ||
47 | As of this writing, Mumit Khan has collected everything you need | ||
48 | together in one FTP site: | ||
49 | } | ||
50 | set ftpsite \ | ||
51 | ftp://ftp.nanotech.wisc.edu/pub/khan/gnu-win32/mingw32/snapshots/gcc-2.95.2-1 | ||
52 | Link $ftpsite | ||
53 | puts { | ||
54 | The three files you will need are:</p> | ||
55 | <ul> | ||
56 | <li>} | ||
57 | Link $ftpsite binutils-19990818-1-src.tar.gz | ||
58 | puts </li><li> | ||
59 | Link $ftpsite gcc-2.95.2-1-src.tar.gz | ||
60 | puts </li><li> | ||
61 | Link $ftpsite mingw-20000203.zip | ||
62 | puts {</li> | ||
63 | </ul> | ||
64 | |||
65 | <p>Put all the downloads in a directory out of the way. The sequel | ||
66 | will assume all downloads are in a directory named | ||
67 | <b>~/mingw/download</b>.</p> | ||
68 | </li> | ||
69 | |||
70 | <li> | ||
71 | <p> | ||
72 | Create a directory in which to install the new compiler suite and make | ||
73 | the new directory writable. | ||
74 | Depending on what directory you choose, you might need to become | ||
75 | root. The example shell commands that follow | ||
76 | will assume the installation directory is | ||
77 | <b>/opt/mingw</b> and that your user ID is <b>drh</b>.</p> | ||
78 | <blockquote><pre> | ||
79 | su | ||
80 | mkdir /opt/mingw | ||
81 | chown drh /opt/mingw | ||
82 | exit | ||
83 | </pre></blockquote> | ||
84 | </li> | ||
85 | |||
86 | <li> | ||
87 | <p>Unpack the source tarballs into a separate directory.</p> | ||
88 | <blockquote><pre> | ||
89 | mkdir ~/mingw/src | ||
90 | cd ~/mingw/src | ||
91 | tar xzf ../download/binutils-*.tar.gz | ||
92 | tar xzf ../download/gcc-*.tar.gz | ||
93 | unzip ../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> | ||
100 | mkdir ~/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> | ||
107 | mkdir ~/mingw/bld/binutils | ||
108 | cd ~/mingw/bld/binutils | ||
109 | ../../src/binutils/configure --prefix=/opt/mingw --target=i386-mingw32 -v | ||
110 | make 2>&1 | tee make.out | ||
111 | make install 2>&1 | tee make-install.out | ||
112 | export 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 | ||
118 | before trying to build the compiler.</p> | ||
119 | <blockquote><pre> | ||
120 | mkdir /opt/mingw/i386-mingw32/include | ||
121 | cd ~/mingw/src/mingw-runtime*/mingw/include | ||
122 | cp -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> | ||
129 | mkdir ~/mingw/bld/gcc | ||
130 | cd ~/mingw/bld/gcc | ||
131 | ../../src/gcc-*/configure --prefix=/opt/mingw --target=i386-mingw32 -v | ||
132 | cd gcc | ||
133 | make installdirs | ||
134 | cd .. | ||
135 | make 2>&1 | tee make.out | ||
136 | make install | ||
137 | </pre></blockquote> | ||
138 | </li> | ||
139 | |||
140 | <li> | ||
141 | <p>Configure and build the MinGW runtime</p> | ||
142 | <blockquote><pre> | ||
143 | mkdir ~/mingw/bld/runtime | ||
144 | cd ~/mingw/bld/runtime | ||
145 | ../../src/mingw-runtime*/configure --prefix=/opt/mingw --target=i386-mingw32 -v | ||
146 | make install-target-w32api | ||
147 | make install | ||
148 | </pre></blockquote> | ||
149 | </li> | ||
150 | </ol> | ||
151 | |||
152 | <p>And you are done...</p> | ||
153 | } | ||
154 | puts { | ||
155 | <p><hr /></p> | ||
156 | <p><a href="index.html"><img src="/goback.jpg" border=0 /> | ||
157 | Back 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 | # | ||
6 | set rcsid {$Id: mkapidoc.tcl,v 1.2 2007/06/20 09:09:48 danielk1977 Exp $} | ||
7 | source common.tcl | ||
8 | header {C/C++ Interface For SQLite Version 3} | ||
9 | puts { | ||
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 | # | ||
16 | set title {} | ||
17 | set type {} | ||
18 | set body {} | ||
19 | set code {} | ||
20 | set phase 0 | ||
21 | set content {} | ||
22 | while {![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 | # | ||
75 | proc 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 | # | ||
97 | set objlist {} | ||
98 | foreach 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 | } | ||
107 | puts {<h2>Datatypes:</h2>} | ||
108 | output_list 3 $objlist | ||
109 | puts {<hr>} | ||
110 | |||
111 | # Do a table of contents for constants | ||
112 | # | ||
113 | set clist {} | ||
114 | foreach 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 | } | ||
123 | puts {<h2>Constants:</h2>} | ||
124 | set clist [lsort -index 1 $clist] | ||
125 | output_list 3 $clist | ||
126 | puts {<hr>} | ||
127 | |||
128 | |||
129 | # Do a table of contents for functions | ||
130 | # | ||
131 | set funclist {} | ||
132 | foreach 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 | } | ||
141 | puts {<h2>Functions:</h2>} | ||
142 | set funclist [lsort -index 1 $funclist] | ||
143 | output_list 3 $funclist | ||
144 | puts {<hr>} | ||
145 | |||
146 | # Resolve links | ||
147 | # | ||
148 | proc 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 | # | ||
162 | foreach 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 | # | ||
4 | set rcsid {$Id: nulls.tcl,v 1.8 2004/10/10 17:24:55 drh Exp $} | ||
5 | source common.tcl | ||
6 | header {NULL Handling in SQLite} | ||
7 | puts { | ||
8 | <h2>NULL Handling in SQLite Versus Other Database Engines</h2> | ||
9 | |||
10 | <p> | ||
11 | The goal is | ||
12 | to make SQLite handle NULLs in a standards-compliant way. | ||
13 | But the descriptions in the SQL standards on how to handle | ||
14 | NULLs seem ambiguous. | ||
15 | It is not clear from the standards documents exactly how NULLs should | ||
16 | be handled in all circumstances. | ||
17 | </p> | ||
18 | |||
19 | <p> | ||
20 | So instead of going by the standards documents, various popular | ||
21 | SQL engines were tested to see how they handle NULLs. The idea | ||
22 | was to make SQLite work like all the other engines. | ||
23 | A SQL test script was developed and run by volunteers on various | ||
24 | SQL RDBMSes and the results of those tests were used to deduce | ||
25 | how each engine processed NULL values. | ||
26 | The original tests were run in May of 2002. | ||
27 | A copy of the test script is found at the end of this document. | ||
28 | </p> | ||
29 | |||
30 | <p> | ||
31 | SQLite was originally coded in such a way that the answer to | ||
32 | all questions in the chart below would be "Yes". But the | ||
33 | experiments run on other SQL engines showed that none of them | ||
34 | worked this way. So SQLite was modified to work the same as | ||
35 | Oracle, PostgreSQL, and DB2. This involved making NULLs | ||
36 | indistinct for the purposes of the SELECT DISTINCT statement and | ||
37 | for the UNION operator in a SELECT. NULLs are still distinct | ||
38 | in a UNIQUE column. This seems somewhat arbitrary, but the desire | ||
39 | to be compatible with other engines outweighted that objection. | ||
40 | </p> | ||
41 | |||
42 | <p> | ||
43 | It is possible to make SQLite treat NULLs as distinct for the | ||
44 | purposes of the SELECT DISTINCT and UNION. To do so, one should | ||
45 | change 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> | ||
52 | Since this document was originally written some of the database engines | ||
53 | tested have been updated and users have been kind enough to send in | ||
54 | corrections to the chart below. The original data showed a wide variety | ||
55 | of behaviors, but over time the range of behaviors has converged toward | ||
56 | the PostgreSQL/Oracle model. The only significant difference | ||
57 | is that Informix and MS-SQL both threat NULLs as | ||
58 | indistinct in a UNIQUE column. | ||
59 | </p> | ||
60 | |||
61 | <p> | ||
62 | The fact that NULLs are distinct for UNIQUE columns but are indistinct for | ||
63 | SELECT DISTINCT and UNION continues to be puzzling. It seems that NULLs | ||
64 | should be either distinct everywhere or nowhere. And the SQL standards | ||
65 | documents suggest that NULLs should be distinct everywhere. Yet as of | ||
66 | this writing, no SQL engine tested treats NULLs as distinct in a SELECT | ||
67 | DISTINCT statement or in a UNION. | ||
68 | </p> | ||
69 | </blockquote> | ||
70 | |||
71 | |||
72 | <p> | ||
73 | The following table shows the results of the NULL handling experiments. | ||
74 | </p> | ||
75 | |||
76 | <table border=1 cellpadding=3 width="100%"> | ||
77 | <tr><th>  </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>  </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: </td> | ||
231 | <td>1. </td> | ||
232 | <td>Older versions of firebird omits all NULLs from SELECT DISTINCT | ||
233 | and from UNION.</td> | ||
234 | </tr> | ||
235 | <tr><td>2. </td> | ||
236 | <td>Test data unavailable.</td> | ||
237 | </tr> | ||
238 | <tr><td>3. </td> | ||
239 | <td>MySQL version 3.23.41 does not support UNION.</td> | ||
240 | </tr> | ||
241 | <tr><td>4. </td> | ||
242 | <td>DB2, SQL Anywhere, and Borland Interbase | ||
243 | do not allow NULLs in a UNIQUE column.</td> | ||
244 | </tr> | ||
245 | <tr><td>5. </td> | ||
246 | <td>Borland Interbase does not support CASE expressions.</td> | ||
247 | </tr> | ||
248 | </table> | ||
249 | <br clear="both"> | ||
250 | |||
251 | <p> </p> | ||
252 | <p> | ||
253 | The following script was used to gather information for the table | ||
254 | above. | ||
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 | ||
273 | create table t1(a int, b int, c int); | ||
274 | insert into t1 values(1,0,0); | ||
275 | insert into t1 values(2,0,1); | ||
276 | insert into t1 values(3,1,0); | ||
277 | insert into t1 values(4,1,1); | ||
278 | insert into t1 values(5,null,0); | ||
279 | insert into t1 values(6,null,1); | ||
280 | insert into t1 values(7,null,null); | ||
281 | |||
282 | -- Check to see what CASE does with NULLs in its test expressions | ||
283 | select a, case when b<>0 then 1 else 0 end from t1; | ||
284 | select a+10, case when not b<>0 then 1 else 0 end from t1; | ||
285 | select a+20, case when b<>0 and c<>0 then 1 else 0 end from t1; | ||
286 | select a+30, case when not (b<>0 and c<>0) then 1 else 0 end from t1; | ||
287 | select a+40, case when b<>0 or c<>0 then 1 else 0 end from t1; | ||
288 | select a+50, case when not (b<>0 or c<>0) then 1 else 0 end from t1; | ||
289 | select a+60, case b when c then 1 else 0 end from t1; | ||
290 | select a+70, case c when b then 1 else 0 end from t1; | ||
291 | |||
292 | -- What happens when you multiple a NULL by zero? | ||
293 | select a+80, b*0 from t1; | ||
294 | select a+90, b*c from t1; | ||
295 | |||
296 | -- What happens to NULL for other operators? | ||
297 | select a+100, b+c from t1; | ||
298 | |||
299 | -- Test the treatment of aggregate operators | ||
300 | select count(*), count(b), sum(b), avg(b), min(b), max(b) from t1; | ||
301 | |||
302 | -- Check the behavior of NULLs in WHERE clauses | ||
303 | select a+110 from t1 where b<10; | ||
304 | select a+120 from t1 where not b>10; | ||
305 | select a+130 from t1 where b<10 OR c=1; | ||
306 | select a+140 from t1 where b<10 AND c=1; | ||
307 | select a+150 from t1 where not (b<10 AND c=1); | ||
308 | select a+160 from t1 where not (c=1 AND b<10); | ||
309 | |||
310 | -- Check the behavior of NULLs in a DISTINCT query | ||
311 | select distinct b from t1; | ||
312 | |||
313 | -- Check the behavior of NULLs in a UNION query | ||
314 | select 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. | ||
318 | create table t2(a int, b int unique); | ||
319 | insert into t2 values(1,1); | ||
320 | insert into t2 values(2,null); | ||
321 | insert into t2 values(3,null); | ||
322 | select * from t2; | ||
323 | |||
324 | drop table t1; | ||
325 | drop table t2; | ||
326 | </pre> | ||
327 | } | ||
328 | |||
329 | footer $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 | ||
2 | source common.tcl | ||
3 | header {SQLite Older News} | ||
4 | |||
5 | proc 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 | |||
12 | newsitem {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 | |||
38 | newsitem {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 | |||
46 | newsitem {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 | |||
52 | newsitem {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 | |||
57 | newsitem {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 | |||
68 | newsitem {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 | |||
74 | newsitem {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 | |||
83 | newsitem {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 | |||
88 | newsitem {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 | |||
93 | newsitem {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 | |||
106 | newsitem {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 | |||
114 | newsitem {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 | |||
124 | newsitem {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 | |||
135 | newsitem {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 | |||
141 | newsitem {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 | |||
147 | newsitem {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 | |||
153 | newsitem {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 | |||
159 | newsitem {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 | |||
164 | newsitem {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 | |||
178 | newsitem {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 | |||
194 | newsitem {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 | |||
203 | newsitem {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 | |||
208 | newsitem {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 | |||
220 | newsitem {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 | |||
225 | newsitem {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 | |||
230 | newsitem {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 | |||
238 | newsitem {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 | |||
245 | newsitem {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 | |||
251 | newsitem {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 | |||
257 | newsitem {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 | |||
273 | newsitem {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 | |||
281 | newsitem {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 | |||
294 | newsitem {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 | |||
298 | newsitem {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 | |||
316 | newsitem {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 | |||
326 | newsitem {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 | |||
338 | newsitem {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 | |||
346 | newsitem {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 | |||
354 | newsitem {2004-Oct-10} {SQLite at the 11<sup><small>th</small></sup> | ||
355 | Annual 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 | |||
364 | newsitem {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 | |||
370 | newsitem {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 | |||
379 | newsitem {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 | |||
385 | newsitem {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 | |||
392 | newsitem {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 | |||
409 | newsitem {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 | |||
417 | newsitem {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 | |||
431 | newsitem {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 | |||
441 | newsitem {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 | |||
460 | newsitem {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 | |||
467 | newsitem {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 | |||
476 | newsitem {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 | } | ||
485 | footer {$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 | # | ||
4 | set rcsid {$Id: omitted.tcl,v 1.10 2005/11/03 00:41:18 drh Exp $} | ||
5 | source common.tcl | ||
6 | header {SQL Features That SQLite Does Not Implement} | ||
7 | puts { | ||
8 | <h2>SQL Features That SQLite Does Not Implement</h2> | ||
9 | |||
10 | <p> | ||
11 | Rather than try to list all the features of SQL92 that SQLite does | ||
12 | support, it is much easier to list those that it does not. | ||
13 | Unsupported features of SQL92 are shown below.</p> | ||
14 | |||
15 | <p> | ||
16 | The order of this list gives some hint as to when a feature might | ||
17 | be added to SQLite. Those features near the top of the list are | ||
18 | likely to be added in the near future. There are no immediate | ||
19 | plans to add features near the bottom of the list. | ||
20 | </p> | ||
21 | |||
22 | <table cellpadding="10"> | ||
23 | } | ||
24 | |||
25 | proc feature {name desc} { | ||
26 | puts "<tr><td valign=\"top\"><b><nobr>$name</nobr></b></td>" | ||
27 | puts "<td width=\"10\"> </th>" | ||
28 | puts "<td valign=\"top\">$desc</td></tr>" | ||
29 | } | ||
30 | |||
31 | feature {FOREIGN KEY constraints} { | ||
32 | FOREIGN KEY constraints are parsed but are not enforced. | ||
33 | } | ||
34 | |||
35 | feature {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 | |||
43 | feature {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 | |||
50 | feature {Nested transactions} { | ||
51 | The current implementation only allows a single active transaction. | ||
52 | } | ||
53 | |||
54 | feature {RIGHT and FULL OUTER JOIN} { | ||
55 | LEFT OUTER JOIN is implemented, but not RIGHT OUTER JOIN or | ||
56 | FULL OUTER JOIN. | ||
57 | } | ||
58 | |||
59 | feature {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 | |||
66 | feature {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 | |||
75 | puts { | ||
76 | </table> | ||
77 | |||
78 | <p> | ||
79 | If you find other SQL92 features that SQLite does not support, please | ||
80 | add them to the Wiki page at | ||
81 | <a href="http://www.sqlite.org/cvstrac/wiki?p=UnsupportedSql"> | ||
82 | http://www.sqlite.org/cvstrac/wiki?p=Unsupported</a> | ||
83 | </p> | ||
84 | } | ||
85 | footer $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 | # | ||
4 | set rcsid {$Id: opcode.tcl,v 1.15 2005/03/09 12:26:51 danielk1977 Exp $} | ||
5 | source common.tcl | ||
6 | header {SQLite Virtual Machine Opcodes} | ||
7 | puts { | ||
8 | <h2>SQLite Virtual Machine Opcodes</h2> | ||
9 | } | ||
10 | |||
11 | set fd [open [lindex $argv 0] r] | ||
12 | set file [read $fd [file size [lindex $argv 0]]] | ||
13 | close $fd | ||
14 | set current_op {} | ||
15 | foreach 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 {\>} txt | ||
25 | regsub -all {<} $txt {\<} 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 {\>} line | ||
40 | regsub -all {<} $line {\<} line | ||
41 | append Opcode($current_op:text) \n$line | ||
42 | } | ||
43 | } | ||
44 | unset file | ||
45 | |||
46 | puts { | ||
47 | <h3>Introduction</h3> | ||
48 | |||
49 | <p>In order to execute an SQL statement, the SQLite library first parses | ||
50 | the SQL, analyzes the statement, then generates a short program to execute | ||
51 | the statement. The program is generated for a "virtual machine" implemented | ||
52 | by the SQLite library. This document describes the operation of that | ||
53 | virtual machine.</p> | ||
54 | |||
55 | <p>This document is intended as a reference, not a tutorial. | ||
56 | A separate <a href="vdbe.html">Virtual Machine Tutorial</a> is | ||
57 | available. If you are looking for a narrative description | ||
58 | of how the virtual machine works, you should read the tutorial | ||
59 | and not this document. Once you have a basic idea of what the | ||
60 | virtual machine does, you can refer back to this document for | ||
61 | the details on a particular opcode. | ||
62 | Unfortunately, the virtual machine tutorial was written for | ||
63 | SQLite version 1.0. There are substantial changes in the virtual | ||
64 | machine 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 | ||
68 | file. All of the opcode definitions further down in this document are | ||
69 | contained in comments in the source file. In fact, the opcode table | ||
70 | in this document | ||
71 | was generated by scanning the <b>vdbe.c</b> source file | ||
72 | and extracting the necessary information from comments. So the | ||
73 | source code comments are really the canonical source of information | ||
74 | about 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 | ||
77 | up to three operands named P1, P2 and P3. P1 may be an arbitrary | ||
78 | integer. P2 must be a non-negative integer. P2 is always the | ||
79 | jump destination in any operation that might cause a jump. | ||
80 | P3 is a null-terminated | ||
81 | string or NULL. Some operators use all three operands. Some use | ||
82 | one or two. Some operators use none of the operands.<p> | ||
83 | |||
84 | <p>The virtual machine begins execution on instruction number 0. | ||
85 | Execution continues until (1) a Halt instruction is seen, or | ||
86 | (2) the program counter becomes one greater than the address of | ||
87 | last instruction, or (3) there is an execution error. | ||
88 | When the virtual machine halts, all memory | ||
89 | that it allocated is released and all database cursors it may | ||
90 | have had open are closed. If the execution stopped due to an | ||
91 | error, any pending transactions are terminated and changes made | ||
92 | to the database are rolled back.</p> | ||
93 | |||
94 | <p>The virtual machine also contains an operand stack of unlimited | ||
95 | depth. Many of the opcodes use operands from the stack. See the | ||
96 | individual opcode descriptions for details.</p> | ||
97 | |||
98 | <p>The virtual machine can have zero or more cursors. Each cursor | ||
99 | is a pointer into a single table or index within the database. | ||
100 | There can be multiple cursors pointing at the same index or table. | ||
101 | All cursors operate independently, even cursors pointing to the same | ||
102 | indices or tables. | ||
103 | The only way for the virtual machine to interact with a database | ||
104 | file is through a cursor. | ||
105 | Instructions in the virtual | ||
106 | machine 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. | ||
109 | All cursors are automatically | ||
110 | closed when the virtual machine terminates.</p> | ||
111 | |||
112 | <p>The virtual machine contains an arbitrary number of fixed memory | ||
113 | locations with addresses beginning at zero and growing upward. | ||
114 | Each memory location can hold an arbitrary string. The memory | ||
115 | cells are typically used to hold the result of a scalar SELECT | ||
116 | that is part of a larger expression.</p> | ||
117 | |||
118 | <p>The virtual machine contains a single sorter. | ||
119 | The sorter is able to accumulate records, sort those records, | ||
120 | then play the records back in sorted order. The sorter is used | ||
121 | to implement the ORDER BY clause of a SELECT statement.</p> | ||
122 | |||
123 | <p>The virtual machine contains a single "List". | ||
124 | The list stores a list of integers. The list is used to hold the | ||
125 | rowids for records of a database table that needs to be modified. | ||
126 | The WHERE clause of an UPDATE or DELETE statement scans through | ||
127 | the table and writes the rowid of every record to be modified | ||
128 | into the list. Then the list is played back and the table is modified | ||
129 | in a separate step.</p> | ||
130 | |||
131 | <p>The virtual machine can contain an arbitrary number of "Sets". | ||
132 | Each set holds an arbitrary number of strings. Sets are used to | ||
133 | implement the IN operator with a constant right-hand side.</p> | ||
134 | |||
135 | <p>The virtual machine can open a single external file for reading. | ||
136 | This 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. | ||
139 | An aggregator is a device used to implement the GROUP BY clause | ||
140 | of a SELECT. An aggregator has one or more slots that can hold | ||
141 | values being extracted by the select. The number of slots is the | ||
142 | same for all aggregators and is defined by the AggReset operation. | ||
143 | At any point in time a single aggregator is current or "has focus". | ||
144 | There are operations to read or write to memory slots of the aggregator | ||
145 | in focus. There are also operations to change the focus aggregator | ||
146 | and 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 | ||
151 | for the virtual machine. But if you precede the SQL statement with | ||
152 | the keyword "EXPLAIN" the virtual machine will not execute the | ||
153 | program. Instead, the instructions of the program will be returned | ||
154 | like a query result. This feature is useful for debugging and | ||
155 | for learning how the virtual machine operates.</p> | ||
156 | |||
157 | <p>You can use the <b>sqlite</b> command-line tool to see the | ||
158 | instructions generated by an SQL statement. The following is | ||
159 | an example:</p>} | ||
160 | |||
161 | proc Code {body} { | ||
162 | puts {<blockquote><tt>} | ||
163 | regsub -all {&} [string trim $body] {\&} body | ||
164 | regsub -all {>} $body {\>} body | ||
165 | regsub -all {<} $body {\<} body | ||
166 | regsub -all {\(\(\(} $body {<b>} body | ||
167 | regsub -all {\)\)\)} $body {</b>} body | ||
168 | regsub -all { } $body {\ } body | ||
169 | regsub -all \n $body <br>\n body | ||
170 | puts $body | ||
171 | puts {</tt></blockquote>} | ||
172 | } | ||
173 | |||
174 | Code { | ||
175 | $ (((sqlite ex1))) | ||
176 | sqlite> (((.explain))) | ||
177 | sqlite> (((explain delete from tbl1 where two<20;))) | ||
178 | addr opcode p1 p2 p3 | ||
179 | ---- ------------ ----- ----- ---------------------------------------- | ||
180 | 0 Transaction 0 0 | ||
181 | 1 VerifyCookie 219 0 | ||
182 | 2 ListOpen 0 0 | ||
183 | 3 Open 0 3 tbl1 | ||
184 | 4 Rewind 0 0 | ||
185 | 5 Next 0 12 | ||
186 | 6 Column 0 1 | ||
187 | 7 Integer 20 0 | ||
188 | 8 Ge 0 5 | ||
189 | 9 Recno 0 0 | ||
190 | 10 ListWrite 0 0 | ||
191 | 11 Goto 0 5 | ||
192 | 12 Close 0 0 | ||
193 | 13 ListRewind 0 0 | ||
194 | 14 OpenWrite 0 3 | ||
195 | 15 ListRead 0 19 | ||
196 | 16 MoveTo 0 0 | ||
197 | 17 Delete 0 0 | ||
198 | 18 Goto 0 15 | ||
199 | 19 ListClose 0 0 | ||
200 | 20 Commit 0 0 | ||
201 | } | ||
202 | |||
203 | puts { | ||
204 | <p>All you have to do is add the "EXPLAIN" keyword to the front of the | ||
205 | SQL statement. But if you use the ".explain" command to <b>sqlite</b> | ||
206 | first, it will set up the output mode to make the program more easily | ||
207 | viewable.</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 | ||
211 | can put the SQLite virtual machine in a mode where it will trace its | ||
212 | execution by writing messages to standard output. The non-standard | ||
213 | SQL "PRAGMA" comments can be used to turn tracing on and off. To | ||
214 | turn tracing on, enter: | ||
215 | </p> | ||
216 | |||
217 | <blockquote><pre> | ||
218 | PRAGMA vdbe_trace=on; | ||
219 | </pre></blockquote> | ||
220 | |||
221 | <p> | ||
222 | You can turn tracing back off by entering a similar statement but | ||
223 | changing the value "on" to "off".</p> | ||
224 | |||
225 | <h3>The Opcodes</h3> | ||
226 | } | ||
227 | |||
228 | puts "<p>There are currently [llength $OpcodeList] opcodes defined by | ||
229 | the virtual machine." | ||
230 | puts {All currently defined opcodes are described in the table below. | ||
231 | This table was generated automatically by scanning the source code | ||
232 | from the file <b>vdbe.c</b>.</p>} | ||
233 | |||
234 | puts { | ||
235 | <p><table cellspacing="1" border="1" cellpadding="10"> | ||
236 | <tr><th>Opcode Name</th><th>Description</th></tr>} | ||
237 | foreach 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 | } | ||
242 | puts {</table></p>} | ||
243 | footer $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 | # | ||
4 | set rcsid {$Id: optimizer.tcl,v 1.1 2005/08/30 22:44:06 drh Exp $} | ||
5 | source common.tcl | ||
6 | header {The SQLite Query Optimizer} | ||
7 | |||
8 | proc CODE {text} { | ||
9 | puts "<blockquote><pre>" | ||
10 | puts $text | ||
11 | puts "</pre></blockquote>" | ||
12 | } | ||
13 | proc IMAGE {name {caption {}}} { | ||
14 | puts "<center><img src=\"$name\">" | ||
15 | if {$caption!=""} { | ||
16 | puts "<br>$caption" | ||
17 | } | ||
18 | puts "</center>" | ||
19 | } | ||
20 | proc PARAGRAPH {text} { | ||
21 | puts "<p>$text</p>\n" | ||
22 | } | ||
23 | proc HEADING {level name} { | ||
24 | puts "<h$level>$name</h$level>" | ||
25 | } | ||
26 | |||
27 | HEADING 1 {The SQLite Query Optimizer} | ||
28 | |||
29 | PARAGRAPH { | ||
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 | |||
45 | HEADING 2 Background | ||
46 | |||
47 | PARAGRAPH { | ||
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 | |||
55 | PARAGRAPH { | ||
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 | |||
67 | PARAGRAPH { | ||
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 | |||
77 | HEADING 2 {Database Layout} | ||
78 | |||
79 | PARAGRAPH { | ||
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 | |||
91 | PARAGRAPH { | ||
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 | |||
99 | PARAGRAPH { | ||
100 | Consider the following block of SQL code: | ||
101 | } | ||
102 | |||
103 | CODE { | ||
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 | |||
116 | PARAGRAPH { | ||
117 | This code generates a new b-tree (named "ex1") containing 5 rows. | ||
118 | This table can be visualized as follows: | ||
119 | } | ||
120 | IMAGE table-ex1b2.gif | ||
121 | |||
122 | PARAGRAPH { | ||
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 | |||
130 | PARAGRAPH { | ||
131 | Now consider the following SQL query: | ||
132 | } | ||
133 | CODE { | ||
134 | SELECT y FROM ex1 WHERE x=456; | ||
135 | } | ||
136 | |||
137 | PARAGRAPH { | ||
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 | } | ||
146 | IMAGE fullscanb.gif | ||
147 | |||
148 | PARAGRAPH { | ||
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 | } | ||
158 | PARAGRAPH { | ||
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 | } | ||
163 | CODE { | ||
164 | SELECT y FROM ex1 WHERE rowid=2; | ||
165 | } | ||
166 | |||
167 | PARAGRAPH { | ||
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 | } | ||
175 | IMAGE direct1b.gif | ||
176 | |||
177 | PARAGRAPH { | ||
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 | } | ||
188 | PARAGRAPH { | ||
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 | } | ||
192 | PARAGRAPH { | ||
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 | } | ||
199 | PARAGRAPH { | ||
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 | } | ||
208 | IMAGE index-ex1-x-b.gif | ||
209 | |||
210 | PARAGRAPH { | ||
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 | } | ||
222 | PARAGRAPH { | ||
223 | Remember what the original query example looked like: | ||
224 | } | ||
225 | CODE { | ||
226 | SELECT y FROM ex1 WHERE x=456; | ||
227 | } | ||
228 | |||
229 | PARAGRAPH { | ||
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 | } | ||
238 | IMAGE indirect1b1.gif | ||
239 | |||
240 | PARAGRAPH { | ||
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 | |||
248 | HEADING 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 @@ | |||
1 | set rcsid {$Id: optimizing.tcl,v 1.1 2005/01/17 03:42:52 drh Exp $} | ||
2 | source common.tcl | ||
3 | header {Hints For Optimizing Queries In SQLite} | ||
4 | proc 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 | } | ||
10 | section 1 recompile {Recompile the library for optimal performance} | ||
11 | section 2 avoidtrans {Minimize the number of transactions} | ||
12 | section 3 usebind {Use sqlite3_bind to insert large chunks of data} | ||
13 | section 4 useindices {Use appropriate indices} | ||
14 | section 5 recordjoin {Reorder the tables in a join} | ||
15 | footer $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 | # | ||
4 | set rcsid {$Id: optoverview.tcl,v 1.5 2005/11/24 13:15:34 drh Exp $} | ||
5 | source common.tcl | ||
6 | header {The SQLite Query Optimizer Overview} | ||
7 | |||
8 | proc CODE {text} { | ||
9 | puts "<blockquote><pre>" | ||
10 | puts $text | ||
11 | puts "</pre></blockquote>" | ||
12 | } | ||
13 | proc SYNTAX {text} { | ||
14 | puts "<blockquote><pre>" | ||
15 | set t2 [string map {& & < < > >} $text] | ||
16 | regsub -all "/(\[^\n/\]+)/" $t2 {</b><i>\1</i><b>} t3 | ||
17 | puts "<b>$t3</b>" | ||
18 | puts "</pre></blockquote>" | ||
19 | } | ||
20 | proc IMAGE {name {caption {}}} { | ||
21 | puts "<center><img src=\"$name\">" | ||
22 | if {$caption!=""} { | ||
23 | puts "<br>$caption" | ||
24 | } | ||
25 | puts "</center>" | ||
26 | } | ||
27 | proc 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 | } | ||
32 | set level(0) 0 | ||
33 | set level(1) 0 | ||
34 | proc 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 | |||
57 | HEADING 0 {The SQLite Query Optimizer Overview} | ||
58 | |||
59 | PARAGRAPH { | ||
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 | |||
66 | HEADING 1 {WHERE clause analysis} where_clause | ||
67 | |||
68 | PARAGRAPH { | ||
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 | } | ||
72 | PARAGRAPH { | ||
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 | |||
83 | PARAGRAPH { | ||
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 | |||
90 | PARAGRAPH { | ||
91 | To be usable by an index a term must be of one of the following | ||
92 | forms: | ||
93 | } | ||
94 | SYNTAX { | ||
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 | } | ||
108 | PARAGRAPH { | ||
109 | If an index is created using a statement like this: | ||
110 | } | ||
111 | CODE { | ||
112 | CREATE INDEX idx_ex1 ON ex1(a,b,c,d,e,...,y,z); | ||
113 | } | ||
114 | PARAGRAPH { | ||
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 | } | ||
123 | PARAGRAPH { | ||
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 | } | ||
135 | CODE { | ||
136 | ... WHERE a=5 AND b IN (1,2,3) AND c>12 AND d='hello' | ||
137 | } | ||
138 | PARAGRAPH { | ||
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 | |||
144 | HEADING 1 {The BETWEEN optimization} between_opt | ||
145 | |||
146 | PARAGRAPH { | ||
147 | If a term of the WHERE clause is of the following form: | ||
148 | } | ||
149 | SYNTAX { | ||
150 | /expr1/ BETWEEN /expr2/ AND /expr3/ | ||
151 | } | ||
152 | PARAGRAPH { | ||
153 | Then two virtual terms are added as follows: | ||
154 | } | ||
155 | SYNTAX { | ||
156 | /expr1/ >= /expr2/ AND /expr1/ <= /expr3/ | ||
157 | } | ||
158 | PARAGRAPH { | ||
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 | |||
172 | HEADING 1 {The OR optimization} or_opt | ||
173 | |||
174 | PARAGRAPH { | ||
175 | If a term consists of multiple subterms containing a common column | ||
176 | name and separated by OR, like this: | ||
177 | } | ||
178 | SYNTAX { | ||
179 | /column/ = /expr1/ OR /column/ = /expr2/ OR /column/ = /expr3/ OR ... | ||
180 | } | ||
181 | PARAGRAPH { | ||
182 | Then the term is rewritten as follows: | ||
183 | } | ||
184 | SYNTAX { | ||
185 | /column/ IN (/expr1/,/expr2/,/expr3/,/expr4/,...) | ||
186 | } | ||
187 | PARAGRAPH { | ||
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 | |||
195 | HEADING 1 {The LIKE optimization} like_opt | ||
196 | |||
197 | PARAGRAPH { | ||
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 | } | ||
202 | PARAGRAPH { | ||
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 | } | ||
219 | PARAGRAPH { | ||
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 | } | ||
225 | CODE { | ||
226 | 'a' LIKE 'A' | ||
227 | } | ||
228 | PARAGRAPH { | ||
229 | By turned on the case_sensitive_like pragma as follows: | ||
230 | } | ||
231 | CODE { | ||
232 | PRAGMA case_sensitive_like=ON; | ||
233 | } | ||
234 | PARAGRAPH { | ||
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 | } | ||
243 | PARAGRAPH { | ||
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 | } | ||
249 | PARAGRAPH { | ||
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 | } | ||
260 | PARAGRAPH { | ||
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 | } | ||
265 | PARAGRAPH { | ||
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 | } | ||
272 | PARAGRAPH { | ||
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 | } | ||
283 | SYNTAX { | ||
284 | /column/ >= /x/ AND /column/ < /y/ | ||
285 | } | ||
286 | PARAGRAPH { | ||
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 | } | ||
295 | SYNTAX { | ||
296 | /column/ LIKE /x/% | ||
297 | /column/ GLOB /x/* | ||
298 | } | ||
299 | PARAGRAPH { | ||
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 | |||
305 | HEADING 1 {Joins} joins | ||
306 | |||
307 | PARAGRAPH { | ||
308 | The current implementation of | ||
309 | SQLite uses only loop joins. That is to say, joins are implemented as | ||
310 | nested loops. | ||
311 | } | ||
312 | PARAGRAPH { | ||
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 | } | ||
319 | PARAGRAPH { | ||
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 | } | ||
326 | PARAGRAPH { | ||
327 | When selecting the order of tables in a join, SQLite uses a greedy | ||
328 | algorithm that runs in polynomial time. | ||
329 | } | ||
330 | PARAGRAPH { | ||
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 | } | ||
338 | PARAGRAPH { | ||
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 | |||
347 | HEADING 1 {Choosing between multiple indices} multi_index | ||
348 | |||
349 | PARAGRAPH { | ||
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 | } | ||
355 | CODE { | ||
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 | } | ||
361 | PARAGRAPH { | ||
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 | } | ||
368 | PARAGRAPH { | ||
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 | } | ||
373 | PARAGRAPH { | ||
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 | } | ||
386 | PARAGRAPH { | ||
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 | } | ||
395 | PARAGRAPH { | ||
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 | } | ||
403 | CODE { | ||
404 | SELECT z FROM ex2 WHERE +x=5 AND y=6; | ||
405 | } | ||
406 | PARAGRAPH { | ||
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 | |||
411 | HEADING 1 {Avoidance of table lookups} index_only | ||
412 | |||
413 | PARAGRAPH { | ||
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 | |||
426 | HEADING 1 {ORDER BY optimizations} order_by | ||
427 | |||
428 | PARAGRAPH { | ||
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 | |||
438 | HEADING 1 {Subquery flattening} flattening | ||
439 | |||
440 | PARAGRAPH { | ||
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 | } | ||
448 | PARAGRAPH { | ||
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 | } | ||
456 | CODE { | ||
457 | SELECT a FROM (SELECT x+y AS a FROM t1 WHERE z<100) WHERE a>5 | ||
458 | } | ||
459 | PARAGRAPH { | ||
460 | Would be rewritten using query flattening as: | ||
461 | } | ||
462 | CODE { | ||
463 | SELECT x+y AS a FROM t1 WHERE z<100 AND a>5 | ||
464 | } | ||
465 | PARAGRAPH { | ||
466 | There is a long list of conditions that must all be met in order for | ||
467 | query flattening to occur. | ||
468 | } | ||
469 | PARAGRAPH { | ||
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 | } | ||
491 | PARAGRAPH { | ||
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 | } | ||
495 | PARAGRAPH { | ||
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 | |||
500 | HEADING 1 {The MIN/MAX optimization} minmax | ||
501 | |||
502 | PARAGRAPH { | ||
503 | Queries of the following forms will be optimized to run in logarithmic | ||
504 | time assuming appropriate indices exist: | ||
505 | } | ||
506 | CODE { | ||
507 | SELECT MIN(x) FROM table; | ||
508 | SELECT MAX(x) FROM table; | ||
509 | } | ||
510 | PARAGRAPH { | ||
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 | # | ||
4 | set rcsid {$Id: pragma.tcl,v 1.28 2007/08/28 08:19:49 danielk1977 Exp $} | ||
5 | source common.tcl | ||
6 | header {Pragma statements supported by SQLite} | ||
7 | |||
8 | proc 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 | |||
16 | puts { | ||
17 | <p>The <a href="#syntax">PRAGMA command</a> is a special command used to | ||
18 | modify the operation of the SQLite library or to query the library for | ||
19 | internal (non-table) data. The PRAGMA command is issued using the same | ||
20 | interface as other SQLite commands (e.g. SELECT, INSERT) but is | ||
21 | different 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 | |||
52 | Section {PRAGMA command syntax} syntax | ||
53 | |||
54 | Syntax {sql-statement} { | ||
55 | PRAGMA <name> [= <value>] | | ||
56 | PRAGMA <function>(<arg>) | ||
57 | } | ||
58 | |||
59 | puts { | ||
60 | <p>The pragmas that take an integer <b><i>value</i></b> also accept | ||
61 | symbolic names. The strings "<b>on</b>", "<b>true</b>", and "<b>yes</b>" | ||
62 | are equivalent to <b>1</b>. The strings "<b>off</b>", "<b>false</b>", | ||
63 | and "<b>no</b>" are equivalent to <b>0</b>. These strings are case- | ||
64 | insensitive, and do not require quotes. An unrecognized string will be | ||
65 | treated as <b>1</b>, and will not generate an error. When the <i>value</i> | ||
66 | is returned it is as an integer.</p> | ||
67 | } | ||
68 | |||
69 | Section {Pragmas to modify library operation} modify | ||
70 | |||
71 | puts { | ||
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 | <table-name/alias><column-name> if the SELECT statement joins | ||
222 | two or | ||
223 | more tables together, or simply <column-name> if the SELECT | ||
224 | statement queries a single table. When the full-column-names flag | ||
225 | is set, such columns are always named <table-name/alias> | ||
226 | <column-name> 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> | ||
311 | PRAGMA <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 | <table-name/alias>lt;column-name> if the SELECT statement | ||
370 | joins two or more tables together, or simply <column-name> if | ||
371 | the SELECT statement queries a single table. When the short-column-names | ||
372 | flag is set, such columns are always named <column-name> | ||
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 | |||
506 | Section {Pragmas to query the database schema} schema | ||
507 | |||
508 | puts { | ||
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 | |||
555 | Section {Pragmas to query/modify version values} version | ||
556 | |||
557 | puts { | ||
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 | |||
589 | Section {Pragmas to debug the library} debug | ||
590 | |||
591 | puts { | ||
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 | # | ||
4 | set rcsid {$Id: quickstart.tcl,v 1.8 2006/06/13 11:27:22 drh Exp $} | ||
5 | source common.tcl | ||
6 | header {SQLite In 5 Minutes Or Less} | ||
7 | puts { | ||
8 | <p>Here is what you do to start experimenting with SQLite without having | ||
9 | to 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 | ||
15 | of the sources and compile them yourself. Visit | ||
16 | the <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 | ||
23 | create a new database named "test.db". (You can use a different name if | ||
24 | you like.)</p></li> | ||
25 | <li><p>Enter SQL commands at the prompt to create and populate the | ||
26 | new 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 | ||
34 | the TCL interface to SQLite. The program executes the SQL statements | ||
35 | given as the second argument on the database defined by the first | ||
36 | argument. The commands to watch for are the <b>sqlite3</b> command | ||
37 | on line 7 which opens an SQLite database and creates | ||
38 | a new TCL command named "<b>db</b>" to access that database, the | ||
39 | invocation of the <b>db</b> command on line 8 to execute | ||
40 | SQL commands against the database, and the closing of the database connection | ||
41 | on the last line of the script.</p> | ||
42 | |||
43 | <blockquote><pre> | ||
44 | #!/usr/bin/tclsh | ||
45 | if {$argc!=2} { | ||
46 | puts stderr "Usage: %s DATABASE SQL-STATEMENT" | ||
47 | exit 1 | ||
48 | } | ||
49 | load /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 | ||
62 | the C/C++ interface to SQLite. The name of a database is given by | ||
63 | the first argument and the second argument is one or more SQL statements | ||
64 | to execute against the database. The function calls to pay attention | ||
65 | to here are the call to <b>sqlite3_open()</b> on line 22 which opens | ||
66 | the database, <b>sqlite3_exec()</b> on line 27 that executes SQL | ||
67 | commands against the database, and <b>sqlite3_close()</b> on line 31 | ||
68 | that closes the database connection.</p> | ||
69 | |||
70 | <blockquote><pre> | ||
71 | #include <stdio.h> | ||
72 | #include <sqlite3.h> | ||
73 | |||
74 | static int callback(void *NotUsed, int argc, char **argv, char **azColName){ | ||
75 | int i; | ||
76 | for(i=0; i<argc; i++){ | ||
77 | printf("%s = %s\n", azColName[i], argv[i] ? argv[i] : "NULL"); | ||
78 | } | ||
79 | printf("\n"); | ||
80 | return 0; | ||
81 | } | ||
82 | |||
83 | int 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 | } | ||
110 | footer {$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 | # | ||
4 | set rcsid {$Id: } | ||
5 | source common.tcl | ||
6 | header {SQLite Shared-Cache Mode} | ||
7 | |||
8 | proc 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 | } | ||
22 | set pnum(1) 0 | ||
23 | set pnum(2) 0 | ||
24 | set pnum(3) 0 | ||
25 | set pnum(4) 0 | ||
26 | set pnum(5) 0 | ||
27 | set pnum(6) 0 | ||
28 | set pnum(7) 0 | ||
29 | set pnum(8) 0 | ||
30 | |||
31 | HEADING 1 {SQLite Shared-Cache Mode} | ||
32 | |||
33 | puts { | ||
34 | <p>Starting with version 3.3.0, SQLite includes a special "shared-cache" | ||
35 | mode (disabled by default) intended for use in embedded servers. If | ||
36 | shared-cache mode is enabled and a thread establishes multiple connections | ||
37 | to the same database, the connections share a single data and schema cache. | ||
38 | This can significantly reduce the quantity of memory and IO required by | ||
39 | the system.</p> | ||
40 | |||
41 | <p>Using shared-cache mode imposes some extra restrictions on | ||
42 | passing database handles between threads and changes the semantics | ||
43 | of the locking model in some cases. These details are described in full by | ||
44 | this 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> | ||
46 | for details) is assumed.</p> | ||
47 | } | ||
48 | |||
49 | HEADING 1 {Shared-Cache Locking Model} | ||
50 | |||
51 | puts { | ||
52 | <p>Externally, from the point of view of another process or thread, two | ||
53 | or more database connections using a shared-cache appear as a single | ||
54 | connection. The locking protocol used to arbitrate between multiple | ||
55 | shared-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 | ||
80 | database connections have been established. Connection 1 is a normal | ||
81 | SQLite database connection. Connections 2 and 3 share a cache (and so must | ||
82 | have been established by the same process thread). The normal locking | ||
83 | protocol is used to serialize database access between connection 1 and | ||
84 | the shared cache. The internal protocol used to serialize (or not, see | ||
85 | "Read-Uncommitted Isolation Mode" below) access to the shared-cache by | ||
86 | connections 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, | ||
90 | transaction level locking, table level locking and schema level locking. | ||
91 | They are described in the following three sub-sections.</p> | ||
92 | |||
93 | } | ||
94 | |||
95 | HEADING 2 {Transaction Level Locking} | ||
96 | |||
97 | puts { | ||
98 | <p>SQLite connections can open two kinds of transactions, read and write | ||
99 | transactions. This is not done explicitly, a transaction is implicitly a | ||
100 | read-transaction until it first writes to a database table, at which point | ||
101 | it becomes a write-transaction. | ||
102 | </p> | ||
103 | <p>At most one connection to a single shared cache may open a | ||
104 | write transaction at any one time. This may co-exist with any number of read | ||
105 | transactions. | ||
106 | </p> | ||
107 | } | ||
108 | |||
109 | HEADING 2 {Table Level Locking} | ||
110 | |||
111 | puts { | ||
112 | <p>When two or more connections use a shared-cache, locks are used to | ||
113 | serialize concurrent access attempts on a per-table basis. Tables support | ||
114 | two types of locks, "read-locks" and "write-locks". Locks are granted to | ||
115 | connections - at any one time, each database connection has either a | ||
116 | read-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 | ||
120 | or a single active write lock. To read data a table, a connection must | ||
121 | first obtain a read-lock. To write to a table, a connection must obtain a | ||
122 | write-lock on that table. If a required table lock cannot be obtained, | ||
123 | the 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 | ||
127 | current transaction (read or write) is concluded. | ||
128 | </p> | ||
129 | } | ||
130 | |||
131 | HEADING 3 {Read-Uncommitted Isolation Mode} | ||
132 | |||
133 | puts { | ||
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 | ||
139 | to obtain read-locks before reading from database tables as described | ||
140 | above. This can lead to inconsistent query results if another database | ||
141 | connection modifies a table while it is being read, but it also means that | ||
142 | a read-transaction opened by a connection in read-uncommitted mode can | ||
143 | neither 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 | ||
146 | database tables (i.e. read-uncommitted connections must still obtain | ||
147 | write-locks and hence database writes may still block or be blocked). | ||
148 | Also, read-uncommitted mode has no effect on the <i>sqlite_master</i> | ||
149 | locks 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 = <boolean>; | ||
160 | |||
161 | /* Retrieve the current value of the read-uncommitted flag */ | ||
162 | PRAGMA read_uncommitted; | ||
163 | </pre> | ||
164 | } | ||
165 | |||
166 | HEADING 2 {Schema (sqlite_master) Level Locking} | ||
167 | |||
168 | puts { | ||
169 | <p>The <i>sqlite_master</i> table supports shared-cache read and write | ||
170 | locks in the same way as all other database tables (see description | ||
171 | above). 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 | ||
176 | accessing 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. | ||
178 | a 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 | ||
182 | is holding a write-lock on the <i>sqlite_master</i> table of any attached | ||
183 | database (including the default database, "main"). | ||
184 | </li> | ||
185 | </ul> | ||
186 | } | ||
187 | |||
188 | HEADING 1 {Thread Related Issues} | ||
189 | |||
190 | puts { | ||
191 | <p>When shared-cache mode is enabled, a database connection may only be | ||
192 | used by the thread that called sqlite3_open() to create it. If another | ||
193 | thread attempts to use the database connection, in most cases an | ||
194 | SQLITE_MISUSE error is returned. However this is not guaranteed and | ||
195 | programs should not depend on this behaviour, in some cases a segfault | ||
196 | may result. | ||
197 | </p> | ||
198 | } | ||
199 | |||
200 | HEADING 1 {Enabling Shared-Cache Mode} | ||
201 | |||
202 | puts { | ||
203 | <p>Shared-cache mode is enabled on a thread-wide basis. Using the C | ||
204 | interface, the following API can be used to enable or disable shared-cache | ||
205 | mode for the calling thread: | ||
206 | </p> | ||
207 | |||
208 | <pre> | ||
209 | int sqlite3_enable_shared_cache(int); | ||
210 | </pre> | ||
211 | |||
212 | <p>It is illegal to call sqlite3_enable_shared_cache() if one or more | ||
213 | open database connections were opened by the calling thread. If the argument | ||
214 | is non-zero, shared-cache mode is enabled. If the argument is zero, | ||
215 | shared-cache mode is disabled. The return value is either SQLITE_OK (if the | ||
216 | operation was successful), SQLITE_NOMEM (if a malloc() failed), or | ||
217 | SQLITE_MISUSE (if the thread has open database connections). | ||
218 | </p> | ||
219 | } | ||
220 | |||
221 | footer $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 | # | ||
4 | set rcsid {$Id: speed.tcl,v 1.17 2005/03/12 15:55:11 drh Exp $ } | ||
5 | source common.tcl | ||
6 | header {SQLite Database Speed Comparison} | ||
7 | |||
8 | puts { | ||
9 | <h2>Database Speed Comparison</h2> | ||
10 | |||
11 | <font color="red"><b> | ||
12 | Note: This document is old. It describes a speed comparison between | ||
13 | an older version of SQLite against archaic versions of MySQL and PostgreSQL. | ||
14 | Readers are invited to contribute more up-to-date speed comparisons | ||
15 | on the <a href="http://www.sqlite.org/cvstrac/wiki">SQLite Wiki</a>. | ||
16 | <p> | ||
17 | The numbers here are old enough to be nearly meaningless. Until it is | ||
18 | updated, use this document only as proof that SQLite is not a | ||
19 | sluggard. | ||
20 | </b></font> | ||
21 | |||
22 | <h3>Executive Summary</h3> | ||
23 | |||
24 | <p>A series of tests were run to measure the relative performance of | ||
25 | SQLite 2.7.6, PostgreSQL 7.1.3, and MySQL 3.23.41. | ||
26 | The following are general | ||
27 | conclusions 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> | ||
53 | The 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> | ||
70 | The platform used for these tests is a 1.6GHz Athlon with 1GB or memory | ||
71 | and an IDE disk drive. The operating system is RedHat Linux 7.2 with | ||
72 | a stock kernel. | ||
73 | </p> | ||
74 | |||
75 | <p> | ||
76 | The PostgreSQL and MySQL servers used were as delivered by default on | ||
77 | RedHat 7.2. (PostgreSQL version 7.1.3 and MySQL version 3.23.41.) | ||
78 | No effort was made to tune these engines. Note in particular | ||
79 | the the default MySQL configuration on RedHat 7.2 does not support | ||
80 | transactions. Not having to support transactions gives MySQL a | ||
81 | big speed advantage, but SQLite is still able to hold its own on most | ||
82 | tests. | ||
83 | </p> | ||
84 | |||
85 | <p> | ||
86 | I am told that the default PostgreSQL configuration in RedHat 7.3 | ||
87 | is unnecessarily conservative (it is designed to | ||
88 | work on a machine with 8MB of RAM) and that PostgreSQL could | ||
89 | be made to run a lot faster with some knowledgeable configuration | ||
90 | tuning. | ||
91 | Matt Sergeant reports that he has tuned his PostgreSQL installation | ||
92 | and rerun the tests shown below. His results show that | ||
93 | PostgreSQL and MySQL run at about the same speed. For Matt's | ||
94 | results, visit | ||
95 | </p> | ||
96 | |||
97 | <blockquote> | ||
98 | <a href="http://www.sergeant.org/sqlite_vs_pgsync.html"> | ||
99 | http://www.sergeant.org/sqlite_vs_pgsync.html</a> | ||
100 | </blockquote> | ||
101 | |||
102 | <p> | ||
103 | SQLite was tested in the same configuration that it appears | ||
104 | on the website. It was compiled with -O6 optimization and with | ||
105 | the -DNDEBUG=1 switch which disables the many "assert()" statements | ||
106 | in the SQLite code. The -DNDEBUG=1 compiler option roughly doubles | ||
107 | the speed of SQLite. | ||
108 | </p> | ||
109 | |||
110 | <p> | ||
111 | All tests are conducted on an otherwise quiescent machine. | ||
112 | A simple Tcl script was used to generate and run all the tests. | ||
113 | A copy of this Tcl script can be found in the SQLite source tree | ||
114 | in the file <b>tools/speedtest.tcl</b>. | ||
115 | </p> | ||
116 | |||
117 | <p> | ||
118 | The times reported on all tests represent wall-clock time | ||
119 | in seconds. Two separate time values are reported for SQLite. | ||
120 | The first value is for SQLite in its default configuration with | ||
121 | full disk synchronization turned on. With synchronization turned | ||
122 | on, SQLite executes | ||
123 | an <b>fsync()</b> system call (or the equivalent) at key points | ||
124 | to make certain that critical data has | ||
125 | actually been written to the disk drive surface. Synchronization | ||
126 | is necessary to guarantee the integrity of the database if the | ||
127 | operating system crashes or the computer powers down unexpectedly | ||
128 | in the middle of a database update. The second time reported for SQLite is | ||
129 | when synchronization is turned off. With synchronization off, | ||
130 | SQLite is sometimes much faster, but there is a risk that an | ||
131 | operating system crash or an unexpected power failure could | ||
132 | damage the database. Generally speaking, the synchronous SQLite | ||
133 | times are for comparison against PostgreSQL (which is also | ||
134 | synchronous) and the asynchronous SQLite times are for | ||
135 | comparison against the asynchronous MySQL engine. | ||
136 | </p> | ||
137 | |||
138 | <h3>Test 1: 1000 INSERTs</h3> | ||
139 | <blockquote> | ||
140 | CREATE TABLE t1(a INTEGER, b INTEGER, c VARCHAR(100));<br> | ||
141 | INSERT INTO t1 VALUES(1,13153,'thirteen thousand one hundred fifty three');<br> | ||
142 | INSERT INTO t1 VALUES(2,75560,'seventy five thousand five hundred sixty');<br> | ||
143 | <i>... 995 lines omitted</i><br> | ||
144 | INSERT INTO t1 VALUES(998,66289,'sixty six thousand two hundred eighty nine');<br> | ||
145 | INSERT INTO t1 VALUES(999,24322,'twenty four thousand three hundred twenty two');<br> | ||
146 | INSERT 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"> 4.373</td></tr> | ||
150 | <tr><td>MySQL:</td><td align="right"> 0.114</td></tr> | ||
151 | <tr><td>SQLite 2.7.6:</td><td align="right"> 13.061</td></tr> | ||
152 | <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.223</td></tr> | ||
153 | </table> | ||
154 | |||
155 | <p> | ||
156 | Because it does not have a central server to coordinate access, | ||
157 | SQLite must close and reopen the database file, and thus invalidate | ||
158 | its cache, for each transaction. In this test, each SQL statement | ||
159 | is a separate transaction so the database file must be opened and closed | ||
160 | and the cache must be flushed 1000 times. In spite of this, the asynchronous | ||
161 | version of SQLite is still nearly as fast as MySQL. Notice how much slower | ||
162 | the synchronous version is, however. SQLite calls <b>fsync()</b> after | ||
163 | each synchronous transaction to make sure that all data is safely on | ||
164 | the disk surface before continuing. For most of the 13 seconds in the | ||
165 | synchronous 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> | ||
170 | BEGIN;<br> | ||
171 | CREATE TABLE t2(a INTEGER, b INTEGER, c VARCHAR(100));<br> | ||
172 | INSERT INTO t2 VALUES(1,59672,'fifty nine thousand six hundred seventy two');<br> | ||
173 | <i>... 24997 lines omitted</i><br> | ||
174 | INSERT INTO t2 VALUES(24999,89569,'eighty nine thousand five hundred sixty nine');<br> | ||
175 | INSERT INTO t2 VALUES(25000,94666,'ninety four thousand six hundred sixty six');<br> | ||
176 | COMMIT;<br> | ||
177 | |||
178 | </blockquote><table border=0 cellpadding=0 cellspacing=0> | ||
179 | <tr><td>PostgreSQL:</td><td align="right"> 4.900</td></tr> | ||
180 | <tr><td>MySQL:</td><td align="right"> 2.184</td></tr> | ||
181 | <tr><td>SQLite 2.7.6:</td><td align="right"> 0.914</td></tr> | ||
182 | <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.757</td></tr> | ||
183 | </table> | ||
184 | |||
185 | <p> | ||
186 | When all the INSERTs are put in a transaction, SQLite no longer has to | ||
187 | close and reopen the database or invalidate its cache between each statement. | ||
188 | It also does not | ||
189 | have to do any fsync()s until the very end. When unshackled in | ||
190 | this 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> | ||
195 | BEGIN;<br> | ||
196 | CREATE TABLE t3(a INTEGER, b INTEGER, c VARCHAR(100));<br> | ||
197 | CREATE INDEX i3 ON t3(c);<br> | ||
198 | <i>... 24998 lines omitted</i><br> | ||
199 | INSERT INTO t3 VALUES(24999,88509,'eighty eight thousand five hundred nine');<br> | ||
200 | INSERT INTO t3 VALUES(25000,84791,'eighty four thousand seven hundred ninety one');<br> | ||
201 | COMMIT;<br> | ||
202 | |||
203 | </blockquote><table border=0 cellpadding=0 cellspacing=0> | ||
204 | <tr><td>PostgreSQL:</td><td align="right"> 8.175</td></tr> | ||
205 | <tr><td>MySQL:</td><td align="right"> 3.197</td></tr> | ||
206 | <tr><td>SQLite 2.7.6:</td><td align="right"> 1.555</td></tr> | ||
207 | <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 1.402</td></tr> | ||
208 | </table> | ||
209 | |||
210 | <p> | ||
211 | There were reports that SQLite did not perform as well on an indexed table. | ||
212 | This test was recently added to disprove those rumors. It is true that | ||
213 | SQLite 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> | ||
219 | BEGIN;<br> | ||
220 | SELECT count(*), avg(b) FROM t2 WHERE b>=0 AND b<1000;<br> | ||
221 | SELECT count(*), avg(b) FROM t2 WHERE b>=100 AND b<1100;<br> | ||
222 | <i>... 96 lines omitted</i><br> | ||
223 | SELECT count(*), avg(b) FROM t2 WHERE b>=9800 AND b<10800;<br> | ||
224 | SELECT count(*), avg(b) FROM t2 WHERE b>=9900 AND b<10900;<br> | ||
225 | COMMIT;<br> | ||
226 | |||
227 | </blockquote><table border=0 cellpadding=0 cellspacing=0> | ||
228 | <tr><td>PostgreSQL:</td><td align="right"> 3.629</td></tr> | ||
229 | <tr><td>MySQL:</td><td align="right"> 2.760</td></tr> | ||
230 | <tr><td>SQLite 2.7.6:</td><td align="right"> 2.494</td></tr> | ||
231 | <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 2.526</td></tr> | ||
232 | </table> | ||
233 | |||
234 | |||
235 | <p> | ||
236 | This test does 100 queries on a 25000 entry table without an index, | ||
237 | thus requiring a full table scan. Prior versions of SQLite used to | ||
238 | be slower than PostgreSQL and MySQL on this test, but recent performance | ||
239 | enhancements have increased its speed so that it is now the fastest | ||
240 | of the group. | ||
241 | </p> | ||
242 | |||
243 | <h3>Test 5: 100 SELECTs on a string comparison</h3> | ||
244 | <blockquote> | ||
245 | BEGIN;<br> | ||
246 | SELECT count(*), avg(b) FROM t2 WHERE c LIKE '%one%';<br> | ||
247 | SELECT count(*), avg(b) FROM t2 WHERE c LIKE '%two%';<br> | ||
248 | <i>... 96 lines omitted</i><br> | ||
249 | SELECT count(*), avg(b) FROM t2 WHERE c LIKE '%ninety nine%';<br> | ||
250 | SELECT count(*), avg(b) FROM t2 WHERE c LIKE '%one hundred%';<br> | ||
251 | COMMIT;<br> | ||
252 | |||
253 | </blockquote><table border=0 cellpadding=0 cellspacing=0> | ||
254 | <tr><td>PostgreSQL:</td><td align="right"> 13.409</td></tr> | ||
255 | <tr><td>MySQL:</td><td align="right"> 4.640</td></tr> | ||
256 | <tr><td>SQLite 2.7.6:</td><td align="right"> 3.362</td></tr> | ||
257 | <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 3.372</td></tr> | ||
258 | </table> | ||
259 | |||
260 | <p> | ||
261 | This test still does 100 full table scans but it uses | ||
262 | uses string comparisons instead of numerical comparisons. | ||
263 | SQLite is over three times faster than PostgreSQL here and about 30% | ||
264 | faster than MySQL. | ||
265 | </p> | ||
266 | |||
267 | <h3>Test 6: Creating an index</h3> | ||
268 | <blockquote> | ||
269 | CREATE 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"> 0.381</td></tr> | ||
272 | <tr><td>MySQL:</td><td align="right"> 0.318</td></tr> | ||
273 | <tr><td>SQLite 2.7.6:</td><td align="right"> 0.777</td></tr> | ||
274 | <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.659</td></tr> | ||
275 | </table> | ||
276 | |||
277 | <p> | ||
278 | SQLite 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 | ||
280 | is being worked on. Hopefully, future versions of SQLite will do better | ||
281 | here. | ||
282 | </p> | ||
283 | |||
284 | <h3>Test 7: 5000 SELECTs with an index</h3> | ||
285 | <blockquote> | ||
286 | SELECT count(*), avg(b) FROM t2 WHERE b>=0 AND b<100;<br> | ||
287 | SELECT count(*), avg(b) FROM t2 WHERE b>=100 AND b<200;<br> | ||
288 | SELECT count(*), avg(b) FROM t2 WHERE b>=200 AND b<300;<br> | ||
289 | <i>... 4994 lines omitted</i><br> | ||
290 | SELECT count(*), avg(b) FROM t2 WHERE b>=499700 AND b<499800;<br> | ||
291 | SELECT count(*), avg(b) FROM t2 WHERE b>=499800 AND b<499900;<br> | ||
292 | SELECT 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"> 4.614</td></tr> | ||
296 | <tr><td>MySQL:</td><td align="right"> 1.270</td></tr> | ||
297 | <tr><td>SQLite 2.7.6:</td><td align="right"> 1.121</td></tr> | ||
298 | <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 1.162</td></tr> | ||
299 | </table> | ||
300 | |||
301 | <p> | ||
302 | All three database engines run faster when they have indices to work with. | ||
303 | But SQLite is still the fastest. | ||
304 | </p> | ||
305 | |||
306 | <h3>Test 8: 1000 UPDATEs without an index</h3> | ||
307 | <blockquote> | ||
308 | BEGIN;<br> | ||
309 | UPDATE t1 SET b=b*2 WHERE a>=0 AND a<10;<br> | ||
310 | UPDATE t1 SET b=b*2 WHERE a>=10 AND a<20;<br> | ||
311 | <i>... 996 lines omitted</i><br> | ||
312 | UPDATE t1 SET b=b*2 WHERE a>=9980 AND a<9990;<br> | ||
313 | UPDATE t1 SET b=b*2 WHERE a>=9990 AND a<10000;<br> | ||
314 | COMMIT;<br> | ||
315 | |||
316 | </blockquote><table border=0 cellpadding=0 cellspacing=0> | ||
317 | <tr><td>PostgreSQL:</td><td align="right"> 1.739</td></tr> | ||
318 | <tr><td>MySQL:</td><td align="right"> 8.410</td></tr> | ||
319 | <tr><td>SQLite 2.7.6:</td><td align="right"> 0.637</td></tr> | ||
320 | <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.638</td></tr> | ||
321 | </table> | ||
322 | |||
323 | <p> | ||
324 | For this particular UPDATE test, MySQL is consistently | ||
325 | five or ten times | ||
326 | slower than PostgreSQL and SQLite. I do not know why. MySQL is | ||
327 | normally a very fast engine. Perhaps this problem has been addressed | ||
328 | in later versions of MySQL. | ||
329 | </p> | ||
330 | |||
331 | <h3>Test 9: 25000 UPDATEs with an index</h3> | ||
332 | <blockquote> | ||
333 | BEGIN;<br> | ||
334 | UPDATE t2 SET b=468026 WHERE a=1;<br> | ||
335 | UPDATE t2 SET b=121928 WHERE a=2;<br> | ||
336 | <i>... 24996 lines omitted</i><br> | ||
337 | UPDATE t2 SET b=35065 WHERE a=24999;<br> | ||
338 | UPDATE t2 SET b=347393 WHERE a=25000;<br> | ||
339 | COMMIT;<br> | ||
340 | |||
341 | </blockquote><table border=0 cellpadding=0 cellspacing=0> | ||
342 | <tr><td>PostgreSQL:</td><td align="right"> 18.797</td></tr> | ||
343 | <tr><td>MySQL:</td><td align="right"> 8.134</td></tr> | ||
344 | <tr><td>SQLite 2.7.6:</td><td align="right"> 3.520</td></tr> | ||
345 | <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 3.104</td></tr> | ||
346 | </table> | ||
347 | |||
348 | <p> | ||
349 | As recently as version 2.7.0, SQLite ran at about the same speed as | ||
350 | MySQL on this test. But recent optimizations to SQLite have more | ||
351 | than doubled speed of UPDATEs. | ||
352 | </p> | ||
353 | |||
354 | <h3>Test 10: 25000 text UPDATEs with an index</h3> | ||
355 | <blockquote> | ||
356 | BEGIN;<br> | ||
357 | UPDATE t2 SET c='one hundred forty eight thousand three hundred eighty two' WHERE a=1;<br> | ||
358 | UPDATE t2 SET c='three hundred sixty six thousand five hundred two' WHERE a=2;<br> | ||
359 | <i>... 24996 lines omitted</i><br> | ||
360 | UPDATE t2 SET c='three hundred eighty three thousand ninety nine' WHERE a=24999;<br> | ||
361 | UPDATE t2 SET c='two hundred fifty six thousand eight hundred thirty' WHERE a=25000;<br> | ||
362 | COMMIT;<br> | ||
363 | |||
364 | </blockquote><table border=0 cellpadding=0 cellspacing=0> | ||
365 | <tr><td>PostgreSQL:</td><td align="right"> 48.133</td></tr> | ||
366 | <tr><td>MySQL:</td><td align="right"> 6.982</td></tr> | ||
367 | <tr><td>SQLite 2.7.6:</td><td align="right"> 2.408</td></tr> | ||
368 | <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 1.725</td></tr> | ||
369 | </table> | ||
370 | |||
371 | <p> | ||
372 | Here again, version 2.7.0 of SQLite used to run at about the same speed | ||
373 | as MySQL. But now version 2.7.6 is over two times faster than MySQL and | ||
374 | over twenty times faster than PostgreSQL. | ||
375 | </p> | ||
376 | |||
377 | <p> | ||
378 | In fairness to PostgreSQL, it started thrashing on this test. A | ||
379 | knowledgeable administrator might be able to get PostgreSQL to run a lot | ||
380 | faster here by tweaking and tuning the server a little. | ||
381 | </p> | ||
382 | |||
383 | <h3>Test 11: INSERTs from a SELECT</h3> | ||
384 | <blockquote> | ||
385 | BEGIN;<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"> 61.364</td></tr> | ||
388 | <tr><td>MySQL:</td><td align="right"> 1.537</td></tr> | ||
389 | <tr><td>SQLite 2.7.6:</td><td align="right"> 2.787</td></tr> | ||
390 | <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 1.599</td></tr> | ||
391 | </table> | ||
392 | |||
393 | <p> | ||
394 | The asynchronous SQLite is just a shade slower than MySQL on this test. | ||
395 | (MySQL seems to be especially adept at INSERT...SELECT statements.) | ||
396 | The PostgreSQL engine is still thrashing - most of the 61 seconds it used | ||
397 | were spent waiting on disk I/O. | ||
398 | </p> | ||
399 | |||
400 | <h3>Test 12: DELETE without an index</h3> | ||
401 | <blockquote> | ||
402 | DELETE FROM t2 WHERE c LIKE '%fifty%'; | ||
403 | </blockquote><table border=0 cellpadding=0 cellspacing=0> | ||
404 | <tr><td>PostgreSQL:</td><td align="right"> 1.509</td></tr> | ||
405 | <tr><td>MySQL:</td><td align="right"> 0.975</td></tr> | ||
406 | <tr><td>SQLite 2.7.6:</td><td align="right"> 4.004</td></tr> | ||
407 | <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.560</td></tr> | ||
408 | </table> | ||
409 | |||
410 | <p> | ||
411 | The synchronous version of SQLite is the slowest of the group in this test, | ||
412 | but the asynchronous version is the fastest. | ||
413 | The difference is the extra time needed to execute fsync(). | ||
414 | </p> | ||
415 | |||
416 | <h3>Test 13: DELETE with an index</h3> | ||
417 | <blockquote> | ||
418 | DELETE 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"> 1.316</td></tr> | ||
421 | <tr><td>MySQL:</td><td align="right"> 2.262</td></tr> | ||
422 | <tr><td>SQLite 2.7.6:</td><td align="right"> 2.068</td></tr> | ||
423 | <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.752</td></tr> | ||
424 | </table> | ||
425 | |||
426 | <p> | ||
427 | This test is significant because it is one of the few where | ||
428 | PostgreSQL is faster than MySQL. The asynchronous SQLite is, | ||
429 | however, faster then both the other two. | ||
430 | </p> | ||
431 | |||
432 | <h3>Test 14: A big INSERT after a big DELETE</h3> | ||
433 | <blockquote> | ||
434 | INSERT INTO t2 SELECT * FROM t1; | ||
435 | </blockquote><table border=0 cellpadding=0 cellspacing=0> | ||
436 | <tr><td>PostgreSQL:</td><td align="right"> 13.168</td></tr> | ||
437 | <tr><td>MySQL:</td><td align="right"> 1.815</td></tr> | ||
438 | <tr><td>SQLite 2.7.6:</td><td align="right"> 3.210</td></tr> | ||
439 | <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 1.485</td></tr> | ||
440 | </table> | ||
441 | |||
442 | <p> | ||
443 | Some older versions of SQLite (prior to version 2.4.0) | ||
444 | would show decreasing performance after a | ||
445 | sequence of DELETEs followed by new INSERTs. As this test shows, the | ||
446 | problem has now been resolved. | ||
447 | </p> | ||
448 | |||
449 | <h3>Test 15: A big DELETE followed by many small INSERTs</h3> | ||
450 | <blockquote> | ||
451 | BEGIN;<br> | ||
452 | DELETE FROM t1;<br> | ||
453 | INSERT INTO t1 VALUES(1,10719,'ten thousand seven hundred nineteen');<br> | ||
454 | <i>... 11997 lines omitted</i><br> | ||
455 | INSERT INTO t1 VALUES(11999,72836,'seventy two thousand eight hundred thirty six');<br> | ||
456 | INSERT INTO t1 VALUES(12000,64231,'sixty four thousand two hundred thirty one');<br> | ||
457 | COMMIT;<br> | ||
458 | |||
459 | </blockquote><table border=0 cellpadding=0 cellspacing=0> | ||
460 | <tr><td>PostgreSQL:</td><td align="right"> 4.556</td></tr> | ||
461 | <tr><td>MySQL:</td><td align="right"> 1.704</td></tr> | ||
462 | <tr><td>SQLite 2.7.6:</td><td align="right"> 0.618</td></tr> | ||
463 | <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.406</td></tr> | ||
464 | </table> | ||
465 | |||
466 | <p> | ||
467 | SQLite is very good at doing INSERTs within a transaction, which probably | ||
468 | explains 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> | ||
473 | DROP 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"> 0.135</td></tr> | ||
476 | <tr><td>MySQL:</td><td align="right"> 0.015</td></tr> | ||
477 | <tr><td>SQLite 2.7.6:</td><td align="right"> 0.939</td></tr> | ||
478 | <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.254</td></tr> | ||
479 | </table> | ||
480 | |||
481 | <p> | ||
482 | SQLite is slower than the other databases when it comes to dropping tables. | ||
483 | This probably is because when SQLite drops a table, it has to go through and | ||
484 | erase the records in the database file that deal with that table. MySQL and | ||
485 | PostgreSQL, on the other hand, use separate files to represent each table | ||
486 | so they can drop a table simply by deleting a file, which is much faster. | ||
487 | </p> | ||
488 | |||
489 | <p> | ||
490 | On the other hand, dropping tables is not a very common operation | ||
491 | so if SQLite takes a little longer, that is not seen as a big problem. | ||
492 | </p> | ||
493 | |||
494 | } | ||
495 | footer $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 | # | ||
4 | set rcsid {$Id: sqlite.tcl,v 1.25 2007/01/08 14:31:36 drh Exp $} | ||
5 | source common.tcl | ||
6 | header {sqlite3: A command-line access program for SQLite databases} | ||
7 | puts { | ||
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 | ||
12 | commands against an SQLite database. This document provides a brief | ||
13 | introduction 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 | ||
18 | the name the file that holds the SQLite database. If the file does | ||
19 | not exist, a new one is created automatically. | ||
20 | The <b>sqlite3</b> program will | ||
21 | then prompt you to enter SQL. Type in SQL statements (terminated by a | ||
22 | semicolon), press "Enter" and the SQL will be executed.</p> | ||
23 | |||
24 | <p>For example, to create a new SQLite database named "ex1" | ||
25 | with a single table named "tbl1", you might do this:</p> | ||
26 | } | ||
27 | |||
28 | proc Code {body} { | ||
29 | puts {<blockquote><tt>} | ||
30 | regsub -all {&} [string trim $body] {\&} body | ||
31 | regsub -all {>} $body {\>} body | ||
32 | regsub -all {<} $body {\<} body | ||
33 | regsub -all {\(\(\(} $body {<b>} body | ||
34 | regsub -all {\)\)\)} $body {</b>} body | ||
35 | regsub -all { } $body {\ } body | ||
36 | regsub -all \n $body <br>\n body | ||
37 | puts $body | ||
38 | puts {</tt></blockquote>} | ||
39 | } | ||
40 | |||
41 | Code { | ||
42 | $ (((sqlite3 ex1))) | ||
43 | SQLite version 3.3.10 | ||
44 | Enter ".help" for instructions | ||
45 | sqlite> (((create table tbl1(one varchar(10), two smallint);))) | ||
46 | sqlite> (((insert into tbl1 values('hello!',10);))) | ||
47 | sqlite> (((insert into tbl1 values('goodbye', 20);))) | ||
48 | sqlite> (((select * from tbl1;))) | ||
49 | hello!|10 | ||
50 | goodbye|20 | ||
51 | sqlite> | ||
52 | } | ||
53 | |||
54 | puts { | ||
55 | <p>You can terminate the sqlite3 program by typing your systems | ||
56 | End-Of-File character (usually a Control-D) or the interrupt | ||
57 | character (usually a Control-C).</p> | ||
58 | |||
59 | <p>Make sure you type a semicolon at the end of each SQL command! | ||
60 | The sqlite3 program looks for a semicolon to know when your SQL command is | ||
61 | complete. If you omit the semicolon, sqlite3 will give you a | ||
62 | continuation prompt and wait for you to enter more text to be | ||
63 | added to the current SQL command. This feature allows you to | ||
64 | enter SQL commands that span multiple lines. For example:</p> | ||
65 | } | ||
66 | |||
67 | Code { | ||
68 | sqlite> (((CREATE TABLE tbl2 ())) | ||
69 | ...> ((( f1 varchar(30) primary key,))) | ||
70 | ...> ((( f2 text,))) | ||
71 | ...> ((( f3 real))) | ||
72 | ...> ((();))) | ||
73 | sqlite> | ||
74 | } | ||
75 | |||
76 | puts { | ||
77 | |||
78 | <h3>Aside: Querying the SQLITE_MASTER table</h3> | ||
79 | |||
80 | <p>The database schema in an SQLite database is stored in | ||
81 | a special table named "sqlite_master". | ||
82 | You can execute "SELECT" statements against the | ||
83 | special sqlite_master table just like any other table | ||
84 | in an SQLite database. For example:</p> | ||
85 | } | ||
86 | |||
87 | Code { | ||
88 | $ (((sqlite3 ex1))) | ||
89 | SQlite vresion 3.3.10 | ||
90 | Enter ".help" for instructions | ||
91 | sqlite> (((select * from sqlite_master;))) | ||
92 | type = table | ||
93 | name = tbl1 | ||
94 | tbl_name = tbl1 | ||
95 | rootpage = 3 | ||
96 | sql = create table tbl1(one varchar(10), two smallint) | ||
97 | sqlite> | ||
98 | } | ||
99 | |||
100 | puts { | ||
101 | <p> | ||
102 | But you cannot execute DROP TABLE, UPDATE, INSERT or DELETE against | ||
103 | the sqlite_master table. The sqlite_master | ||
104 | table is updated automatically as you create or drop tables and | ||
105 | indices from the database. You can not make manual changes | ||
106 | to the sqlite_master table. | ||
107 | </p> | ||
108 | |||
109 | <p> | ||
110 | The schema for TEMPORARY tables is not stored in the "sqlite_master" table | ||
111 | since TEMPORARY tables are not visible to applications other than the | ||
112 | application that created the table. The schema for TEMPORARY tables | ||
113 | is 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> | ||
120 | Most of the time, sqlite3 just reads lines of input and passes them | ||
121 | on to the SQLite library for execution. | ||
122 | But if an input line begins with a dot ("."), then | ||
123 | that line is intercepted and interpreted by the sqlite3 program itself. | ||
124 | These "dot commands" are typically used to change the output format | ||
125 | of queries, or to execute certain prepackaged query statements. | ||
126 | </p> | ||
127 | |||
128 | <p> | ||
129 | For a listing of the available dot commands, you can enter ".help" | ||
130 | at any time. For example: | ||
131 | </p>} | ||
132 | |||
133 | Code { | ||
134 | sqlite> (((.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 | ||
167 | sqlite> | ||
168 | } | ||
169 | |||
170 | puts { | ||
171 | <h3>Changing Output Formats</h3> | ||
172 | |||
173 | <p>The sqlite3 program is able to show the results of a query | ||
174 | in eight different formats: "csv", "column", "html", "insert", | ||
175 | "line", "tabs", and "tcl". | ||
176 | You can use the ".mode" dot command to switch between these output | ||
177 | formats.</p> | ||
178 | |||
179 | <p>The default output mode is "list". In | ||
180 | list mode, each record of a query result is written on one line of | ||
181 | output and each column within that record is separated by a specific | ||
182 | separator string. The default separator is a pipe symbol ("|"). | ||
183 | List mode is especially useful when you are going to send the output | ||
184 | of a query to another program (such as AWK) for additional processing.</p>} | ||
185 | |||
186 | Code { | ||
187 | sqlite> (((.mode list))) | ||
188 | sqlite> (((select * from tbl1;))) | ||
189 | hello|10 | ||
190 | goodbye|20 | ||
191 | sqlite> | ||
192 | } | ||
193 | |||
194 | puts { | ||
195 | <p>You can use the ".separator" dot command to change the separator | ||
196 | for list mode. For example, to change the separator to a comma and | ||
197 | a space, you could do this:</p>} | ||
198 | |||
199 | Code { | ||
200 | sqlite> (((.separator ", "))) | ||
201 | sqlite> (((select * from tbl1;))) | ||
202 | hello, 10 | ||
203 | goodbye, 20 | ||
204 | sqlite> | ||
205 | } | ||
206 | |||
207 | puts { | ||
208 | <p>In "line" mode, each column in a row of the database | ||
209 | is shown on a line by itself. Each line consists of the column | ||
210 | name, an equal sign and the column data. Successive records are | ||
211 | separated by a blank line. Here is an example of line mode | ||
212 | output:</p>} | ||
213 | |||
214 | Code { | ||
215 | sqlite> (((.mode line))) | ||
216 | sqlite> (((select * from tbl1;))) | ||
217 | one = hello | ||
218 | two = 10 | ||
219 | |||
220 | one = goodbye | ||
221 | two = 20 | ||
222 | sqlite> | ||
223 | } | ||
224 | |||
225 | puts { | ||
226 | <p>In column mode, each record is shown on a separate line with the | ||
227 | data aligned in columns. For example:</p>} | ||
228 | |||
229 | Code { | ||
230 | sqlite> (((.mode column))) | ||
231 | sqlite> (((select * from tbl1;))) | ||
232 | one two | ||
233 | ---------- ---------- | ||
234 | hello 10 | ||
235 | goodbye 20 | ||
236 | sqlite> | ||
237 | } | ||
238 | |||
239 | puts { | ||
240 | <p>By default, each column is at least 10 characters wide. | ||
241 | Data that is too wide to fit in a column is truncated. You can | ||
242 | adjust the column widths using the ".width" command. Like this:</p>} | ||
243 | |||
244 | Code { | ||
245 | sqlite> (((.width 12 6))) | ||
246 | sqlite> (((select * from tbl1;))) | ||
247 | one two | ||
248 | ------------ ------ | ||
249 | hello 10 | ||
250 | goodbye 20 | ||
251 | sqlite> | ||
252 | } | ||
253 | |||
254 | puts { | ||
255 | <p>The ".width" command in the example above sets the width of the first | ||
256 | column to 12 and the width of the second column to 6. All other column | ||
257 | widths were unaltered. You can gives as many arguments to ".width" as | ||
258 | necessary to specify the widths of as many columns as are in your | ||
259 | query results.</p> | ||
260 | |||
261 | <p>If you specify a column a width of 0, then the column | ||
262 | width is automatically adjusted to be the maximum of three | ||
263 | numbers: 10, the width of the header, and the width of the | ||
264 | first row of data. This makes the column width self-adjusting. | ||
265 | The default width setting for every column is this | ||
266 | auto-adjusting 0 value.</p> | ||
267 | |||
268 | <p>The column labels that appear on the first two lines of output | ||
269 | can be turned on and off using the ".header" dot command. In the | ||
270 | examples above, the column labels are on. To turn them off you | ||
271 | could do this:</p>} | ||
272 | |||
273 | Code { | ||
274 | sqlite> (((.header off))) | ||
275 | sqlite> (((select * from tbl1;))) | ||
276 | hello 10 | ||
277 | goodbye 20 | ||
278 | sqlite> | ||
279 | } | ||
280 | |||
281 | puts { | ||
282 | <p>Another useful output mode is "insert". In insert mode, the output | ||
283 | is formatted to look like SQL INSERT statements. You can use insert | ||
284 | mode to generate text that can later be used to input data into a | ||
285 | different database.</p> | ||
286 | |||
287 | <p>When specifying insert mode, you have to give an extra argument | ||
288 | which is the name of the table to be inserted into. For example:</p> | ||
289 | } | ||
290 | |||
291 | Code { | ||
292 | sqlite> (((.mode insert new_table))) | ||
293 | sqlite> (((select * from tbl1;))) | ||
294 | INSERT INTO 'new_table' VALUES('hello',10); | ||
295 | INSERT INTO 'new_table' VALUES('goodbye',20); | ||
296 | sqlite> | ||
297 | } | ||
298 | |||
299 | puts { | ||
300 | <p>The last output mode is "html". In this mode, sqlite3 writes | ||
301 | the results of the query as an XHTML table. The beginning | ||
302 | <TABLE> and the ending </TABLE> are not written, but | ||
303 | all of the intervening <TR>s, <TH>s, and <TD>s | ||
304 | are. The html output mode is envisioned as being useful for | ||
305 | CGI.</p> | ||
306 | } | ||
307 | |||
308 | puts { | ||
309 | <h3>Writing results to a file</h3> | ||
310 | |||
311 | <p>By default, sqlite3 sends query results to standard output. You | ||
312 | can change this using the ".output" command. Just put the name of | ||
313 | an output file as an argument to the .output command and all subsequent | ||
314 | query results will be written to that file. Use ".output stdout" to | ||
315 | begin writing to standard output again. For example:</p>} | ||
316 | |||
317 | Code { | ||
318 | sqlite> (((.mode list))) | ||
319 | sqlite> (((.separator |))) | ||
320 | sqlite> (((.output test_file_1.txt))) | ||
321 | sqlite> (((select * from tbl1;))) | ||
322 | sqlite> (((.exit))) | ||
323 | $ (((cat test_file_1.txt))) | ||
324 | hello|10 | ||
325 | goodbye|20 | ||
326 | $ | ||
327 | } | ||
328 | |||
329 | puts { | ||
330 | <h3>Querying the database schema</h3> | ||
331 | |||
332 | <p>The sqlite3 program provides several convenience commands that | ||
333 | are useful for looking at the schema of the database. There is | ||
334 | nothing that these commands do that cannot be done by some other | ||
335 | means. 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 | ||
338 | can enter ".tables".</p> | ||
339 | } | ||
340 | |||
341 | Code { | ||
342 | sqlite> (((.tables))) | ||
343 | tbl1 | ||
344 | tbl2 | ||
345 | sqlite> | ||
346 | } | ||
347 | |||
348 | puts { | ||
349 | <p>The ".tables" command is similar to setting list mode then | ||
350 | executing the following query:</p> | ||
351 | |||
352 | <blockquote><pre> | ||
353 | SELECT name FROM sqlite_master | ||
354 | WHERE type IN ('table','view') AND name NOT LIKE 'sqlite_%' | ||
355 | UNION ALL | ||
356 | SELECT name FROM sqlite_temp_master | ||
357 | WHERE type IN ('table','view') | ||
358 | ORDER 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 | ||
363 | exactly the above query.</p> | ||
364 | |||
365 | <p>The ".indices" command works in a similar way to list all of | ||
366 | the indices for a particular table. The ".indices" command takes | ||
367 | a single argument which is the name of the table for which the | ||
368 | indices are desired. Last, but not least, is the ".schema" command. | ||
369 | With no arguments, the ".schema" command shows the original CREATE TABLE | ||
370 | and CREATE INDEX statements that were used to build the current database. | ||
371 | If you give the name of a table to ".schema", it shows the original | ||
372 | CREATE statement used to make that table and all if its indices. | ||
373 | We have:</p>} | ||
374 | |||
375 | Code { | ||
376 | sqlite> (((.schema))) | ||
377 | create table tbl1(one varchar(10), two smallint) | ||
378 | CREATE TABLE tbl2 ( | ||
379 | f1 varchar(30) primary key, | ||
380 | f2 text, | ||
381 | f3 real | ||
382 | ) | ||
383 | sqlite> (((.schema tbl2))) | ||
384 | CREATE TABLE tbl2 ( | ||
385 | f1 varchar(30) primary key, | ||
386 | f2 text, | ||
387 | f3 real | ||
388 | ) | ||
389 | sqlite> | ||
390 | } | ||
391 | |||
392 | puts { | ||
393 | <p>The ".schema" command accomplishes the same thing as setting | ||
394 | list mode, then entering the following query:</p> | ||
395 | |||
396 | <blockquote><pre> | ||
397 | SELECT sql FROM | ||
398 | (SELECT * FROM sqlite_master UNION ALL | ||
399 | SELECT * FROM sqlite_temp_master) | ||
400 | WHERE type!='meta' | ||
401 | ORDER BY tbl_name, type DESC, name | ||
402 | </pre></blockquote> | ||
403 | |||
404 | <p>Or, if you give an argument to ".schema" because you only | ||
405 | want the schema for a single table, the query looks like this:</p> | ||
406 | |||
407 | <blockquote><pre> | ||
408 | SELECT sql FROM | ||
409 | (SELECT * FROM sqlite_master UNION ALL | ||
410 | SELECT * FROM sqlite_temp_master) | ||
411 | WHERE type!='meta' AND sql NOT NULL AND name NOT LIKE 'sqlite_%' | ||
412 | ORDER BY substr(type,2,1), name | ||
413 | </pre></blockquote> | ||
414 | |||
415 | <p> | ||
416 | You can supply an argument to the .schema command. If you do, the | ||
417 | query looks like this: | ||
418 | </p> | ||
419 | |||
420 | <blockquote><pre> | ||
421 | SELECT sql FROM | ||
422 | (SELECT * FROM sqlite_master UNION ALL | ||
423 | SELECT * FROM sqlite_temp_master) | ||
424 | WHERE tbl_name LIKE '%s' | ||
425 | AND type!='meta' AND sql NOT NULL AND name NOT LIKE 'sqlite_%' | ||
426 | ORDER 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 | ||
430 | to view the schema for some subset of the database.</p> | ||
431 | } | ||
432 | |||
433 | Code { | ||
434 | sqlite> (((.schema %abc%))) | ||
435 | } | ||
436 | |||
437 | puts { | ||
438 | <p> | ||
439 | Along these same lines, | ||
440 | the ".table" command also accepts a pattern as its first argument. | ||
441 | If you give an argument to the .table command, a "%" is both | ||
442 | appended and prepended and a LIKE clause is added to the query. | ||
443 | This allows you to list only those tables that match a particular | ||
444 | pattern.</p> | ||
445 | |||
446 | <p>The ".databases" command shows a list of all databases open in | ||
447 | the current connection. There will always be at least 2. The first | ||
448 | one is "main", the original database opened. The second is "temp", | ||
449 | the database used for temporary tables. There may be additional | ||
450 | databases listed for databases attached using the ATTACH statement. | ||
451 | The first output column is the name the database is attached with, | ||
452 | and the second column is the filename of the external file.</p>} | ||
453 | |||
454 | Code { | ||
455 | sqlite> (((.databases))) | ||
456 | } | ||
457 | |||
458 | puts { | ||
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 | ||
462 | database into a single ASCII text file. This file can be converted | ||
463 | back 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 | |||
468 | Code { | ||
469 | $ (((echo '.dump' | sqlite3 ex1 | gzip -c >ex1.dump.gz))) | ||
470 | } | ||
471 | |||
472 | puts { | ||
473 | <p>This generates a file named <b>ex1.dump.gz</b> that contains everything | ||
474 | you need to reconstruct the database at a later time, or on another | ||
475 | machine. To reconstruct the database, just type:</p> | ||
476 | } | ||
477 | |||
478 | Code { | ||
479 | $ (((zcat ex1.dump.gz | sqlite3 ex2))) | ||
480 | } | ||
481 | |||
482 | puts { | ||
483 | <p>The text format is pure SQL so you | ||
484 | can also use the .dump command to export an SQLite database | ||
485 | into other popular SQL database engines. Like this:</p> | ||
486 | } | ||
487 | |||
488 | Code { | ||
489 | $ (((createdb ex2))) | ||
490 | $ (((sqlite3 ex1 .dump | psql ex2))) | ||
491 | } | ||
492 | |||
493 | puts { | ||
494 | <h3>Other Dot Commands</h3> | ||
495 | |||
496 | <p>The ".explain" dot command can be used to set the output mode | ||
497 | to "column" and to set the column widths to values that are reasonable | ||
498 | for looking at the output of an EXPLAIN command. The EXPLAIN command | ||
499 | is an SQLite-specific SQL extension that is useful for debugging. If any | ||
500 | regular SQL is prefaced by EXPLAIN, then the SQL command is parsed and | ||
501 | analyzed but is not executed. Instead, the sequence of virtual machine | ||
502 | instructions that would have been used to execute the SQL command are | ||
503 | returned like a query result. For example:</p>} | ||
504 | |||
505 | Code { | ||
506 | sqlite> (((.explain))) | ||
507 | sqlite> (((explain delete from tbl1 where two<20;))) | ||
508 | addr opcode p1 p2 p3 | ||
509 | ---- ------------ ----- ----- ------------------------------------- | ||
510 | 0 ListOpen 0 0 | ||
511 | 1 Open 0 1 tbl1 | ||
512 | 2 Next 0 9 | ||
513 | 3 Field 0 1 | ||
514 | 4 Integer 20 0 | ||
515 | 5 Ge 0 2 | ||
516 | 6 Key 0 0 | ||
517 | 7 ListWrite 0 0 | ||
518 | 8 Goto 0 2 | ||
519 | 9 Noop 0 0 | ||
520 | 10 ListRewind 0 0 | ||
521 | 11 ListRead 0 14 | ||
522 | 12 Delete 0 0 | ||
523 | 13 Goto 0 11 | ||
524 | 14 ListClose 0 0 | ||
525 | } | ||
526 | |||
527 | puts { | ||
528 | |||
529 | <p>The ".timeout" command sets the amount of time that the <b>sqlite3</b> | ||
530 | program will wait for locks to clear on files it is trying to access | ||
531 | before returning an error. The default value of the timeout is zero so | ||
532 | that an error is returned immediately if any needed database table or | ||
533 | index is locked.</p> | ||
534 | |||
535 | <p>And finally, we mention the ".exit" command which causes the | ||
536 | sqlite3 program to exit.</p> | ||
537 | |||
538 | <h3>Using sqlite3 in a shell script</h3> | ||
539 | |||
540 | <p> | ||
541 | One 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 | ||
543 | while redirecting input from the generated command file. This | ||
544 | works fine and is appropriate in many circumstances. But as | ||
545 | an added convenience, sqlite3 allows a single SQL command to be | ||
546 | entered on the command line as a second argument after the | ||
547 | database name. When the sqlite3 program is launched with two | ||
548 | arguments, the second argument is passed to the SQLite library | ||
549 | for processing, the query results are printed on standard output | ||
550 | in list mode, and the program exits. This mechanism is designed | ||
551 | to make sqlite3 easy to use in conjunction with programs like | ||
552 | "awk". For example:</p>} | ||
553 | |||
554 | Code { | ||
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 | |||
562 | puts { | ||
563 | <h3>Ending shell commands</h3> | ||
564 | |||
565 | <p> | ||
566 | SQLite commands are normally terminated by a semicolon. In the shell | ||
567 | you 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 | ||
569 | and Oracle, respectively. These won't work in <b>sqlite3_exec()</b>, | ||
570 | because the shell translates these into a semicolon before passing them | ||
571 | to that function.</p> | ||
572 | } | ||
573 | |||
574 | puts { | ||
575 | <h3>Compiling the sqlite3 program from sources</h3> | ||
576 | |||
577 | <p> | ||
578 | The sqlite3 program is built automatically when you compile the | ||
579 | SQLite library. Just get a copy of the source tree, run | ||
580 | "configure" and then "make".</p> | ||
581 | } | ||
582 | footer $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 @@ | |||
1 | set rcsid {$Id: support.tcl,v 1.7 2007/06/21 13:30:40 drh Exp $} | ||
2 | source common.tcl | ||
3 | header {SQLite Support Options} | ||
4 | puts { | ||
5 | <h2>SQLite Support Options</h2> | ||
6 | |||
7 | |||
8 | <h3>Mailing List</h3> | ||
9 | <p> | ||
10 | A mailing list has been set up for asking questions and | ||
11 | for open discussion of problems | ||
12 | and issues by the SQLite user community. | ||
13 | To subscribe to the mailing list, send an email to | ||
14 | <a href="mailto:sqlite-users-subscribe@sqlite.org"> | ||
15 | sqlite-users-subscribe@sqlite.org</a>. | ||
16 | If you would prefer to get digests rather than individual | ||
17 | emails, send a message to to | ||
18 | <a href="mailto:sqlite-users-digest-subscribe@sqlite.org"> | ||
19 | sqlite-users-digest-subscribe@sqlite.org</a>. | ||
20 | For additional information about operating and using this | ||
21 | mailing list, send a message to | ||
22 | <a href="mailto:sqlite-users-help@sqlite.org"> | ||
23 | sqlite-users-help@sqlite.org</a> and instructions will be | ||
24 | sent by to you by return email. | ||
25 | </p> | ||
26 | |||
27 | <p> | ||
28 | There are multiple archives of the mailing list: | ||
29 | </p> | ||
30 | |||
31 | <blockquote> | ||
32 | <a href="http://www.mail-archive.com/sqlite-users%40sqlite.org/"> | ||
33 | http://www.mail-archive.com/sqlite-users%40sqlite.org</a><br> | ||
34 | <a href="http://marc.info/?l=sqlite-users&r=1&w=2"> | ||
35 | http://marc.info/?l=sqlite-users&r=1&w=2</a><br> | ||
36 | <a href="http://news.gmane.org/gmane.comp.db.sqlite.general"> | ||
37 | http://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> | ||
46 | Use the mailing list. | ||
47 | Please do <b>not</b> send email directly to the author of SQLite | ||
48 | unless: | ||
49 | <ul> | ||
50 | <li>You have or intend to acquire a professional support contract | ||
51 | as described below, or</li> | ||
52 | <li>You are working on an open source project.</li> | ||
53 | </ul> | ||
54 | You are welcomed to use SQLite in closed source, proprietary, and/or | ||
55 | commerical projects and to ask questions about such use on the public | ||
56 | mailing list. But please do not ask to receive free direct technical | ||
57 | support. The software is free; direct technical support is not. | ||
58 | </p> | ||
59 | |||
60 | |||
61 | <h3>Professional Support</h3> | ||
62 | |||
63 | <p> | ||
64 | If you would like professional support for SQLite | ||
65 | or if you want custom modifications to SQLite performed by the | ||
66 | original author, these services are available for a modest fee. | ||
67 | For additional information visit | ||
68 | <a href="http://www.hwaci.com/sw/sqlite/prosupport.html"> | ||
69 | http://www.hwaci.com/sw/sqlite/prosupport.html</a> or contact:</p> | ||
70 | |||
71 | <blockquote> | ||
72 | D. Richard Hipp <br /> | ||
73 | Hwaci - Applied Software Research <br /> | ||
74 | 704.948.4565 <br /> | ||
75 | <a href="mailto:drh@hwaci.com">drh@hwaci.com</a> | ||
76 | </blockquote> | ||
77 | |||
78 | } | ||
79 | footer $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 | # | ||
4 | set rcsid {$Id: tclsqlite.tcl,v 1.17 2007/06/19 17:48:57 drh Exp $} | ||
5 | source common.tcl | ||
6 | header {The Tcl interface to the SQLite library} | ||
7 | proc METHOD {name text} { | ||
8 | puts "<a name=\"$name\">\n<h3>The \"$name\" method</h3>\n" | ||
9 | puts $text | ||
10 | } | ||
11 | puts { | ||
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 | ||
15 | a Tcl or Tcl/Tk script. This document gives an overview of the Tcl | ||
16 | programming interface.</p> | ||
17 | |||
18 | <h3>The API</h3> | ||
19 | |||
20 | <p>The interface to the SQLite library consists of single | ||
21 | tcl command named <b>sqlite3</b> | ||
22 | Because there is only this | ||
23 | one command, the interface is not placed in a separate | ||
24 | namespace.</p> | ||
25 | |||
26 | <p>The <b>sqlite3</b> command is used as follows:</p> | ||
27 | |||
28 | <blockquote> | ||
29 | <b>sqlite3</b> <i>dbcmd database-name</i> | ||
30 | </blockquote> | ||
31 | |||
32 | <p> | ||
33 | The <b>sqlite3</b> command opens the database named in the second | ||
34 | argument. If the database does not already exist, it is | ||
35 | automatically created. | ||
36 | The <b>sqlite3</b> command also creates a new Tcl | ||
37 | command to control the database. The name of the new Tcl command | ||
38 | is given by the first argument. This approach is similar to the | ||
39 | way widgets are created in Tk. | ||
40 | </p> | ||
41 | |||
42 | <p> | ||
43 | The name of the database is just the name of a disk file in which | ||
44 | the database is stored. If the name of the database is an empty | ||
45 | string or the special name ":memory:" then a new database is created | ||
46 | in memory. | ||
47 | </p> | ||
48 | |||
49 | <p> | ||
50 | Once an SQLite database is open, it can be controlled using | ||
51 | methods of the <i>dbcmd</i>. There are currently 22 methods | ||
52 | defined.</p> | ||
53 | |||
54 | <p> | ||
55 | <ul> | ||
56 | } | ||
57 | foreach 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 | } | ||
88 | puts { | ||
89 | </ul> | ||
90 | </p> | ||
91 | |||
92 | <p>The use of each of these methods will be explained in the sequel, though | ||
93 | not in the order shown above.</p> | ||
94 | |||
95 | } | ||
96 | |||
97 | ############################################################################## | ||
98 | METHOD eval { | ||
99 | <p> | ||
100 | The most useful <i>dbcmd</i> method is "eval". The eval method is used | ||
101 | to execute SQL on the database. The syntax of the eval method looks | ||
102 | like this:</p> | ||
103 | |||
104 | <blockquote> | ||
105 | <i>dbcmd</i> <b>eval</b> <i>sql</i> | ||
106 | ?<i>array-name </i>? ?<i>script</i>? | ||
107 | </blockquote> | ||
108 | |||
109 | <p> | ||
110 | The job of the eval method is to execute the SQL statement or statements | ||
111 | given in the second argument. For example, to create a new table in | ||
112 | a database, you can do this:</p> | ||
113 | |||
114 | <blockquote> | ||
115 | <b>sqlite3 db1 ./testdb<br> | ||
116 | db1 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 | ||
123 | query requests 2 columns and there are 3 rows matching the query, | ||
124 | then the returned list will contain 6 elements. For example:</p> | ||
125 | |||
126 | <blockquote> | ||
127 | <b>db1 eval {INSERT INTO t1 VALUES(1,'hello')}<br> | ||
128 | db1 eval {INSERT INTO t1 VALUES(2,'goodbye')}<br> | ||
129 | db1 eval {INSERT INTO t1 VALUES(3,'howdy!')}<br> | ||
130 | set 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 | ||
140 | by specifying the name of an array variable and a script following | ||
141 | the SQL code. For each row of the query result, the values of all | ||
142 | columns will be inserted into the array variable and the script will | ||
143 | be executed. For instance:</p> | ||
144 | |||
145 | <blockquote> | ||
146 | <b>db1 eval {SELECT * FROM t1 ORDER BY a} values {<br> | ||
147 | parray values<br> | ||
148 | puts ""<br> | ||
149 | }</b> | ||
150 | </blockquote> | ||
151 | |||
152 | <p>This last code will give the following output:</p> | ||
153 | |||
154 | <blockquote><b> | ||
155 | values(*) = a b<br> | ||
156 | values(a) = 1<br> | ||
157 | values(b) = hello<p> | ||
158 | |||
159 | values(*) = a b<br> | ||
160 | values(a) = 2<br> | ||
161 | values(b) = goodbye<p> | ||
162 | |||
163 | values(*) = a b<br> | ||
164 | values(a) = 3<br> | ||
165 | values(b) = howdy!</b> | ||
166 | </blockquote> | ||
167 | |||
168 | <p> | ||
169 | For each column in a row of the result, the name of that column | ||
170 | is used as an index in to array. The value of the column is stored | ||
171 | in the corresponding array entry. The special array index * is | ||
172 | used to store a list of column names in the order that they appear. | ||
173 | </p> | ||
174 | |||
175 | <p> | ||
176 | If the array variable name is omitted or is the empty string, then the value of | ||
177 | each column is stored in a variable with the same name as the column | ||
178 | itself. For example: | ||
179 | </p> | ||
180 | |||
181 | <blockquote> | ||
182 | <b>db1 eval {SELECT * FROM t1 ORDER BY a} {<br> | ||
183 | puts "a=$a b=$b"<br> | ||
184 | }</b> | ||
185 | </blockquote> | ||
186 | |||
187 | <p> | ||
188 | From this we get the following output | ||
189 | </p> | ||
190 | |||
191 | <blockquote><b> | ||
192 | a=1 b=hello<br> | ||
193 | a=2 b=goodbye<br> | ||
194 | a=3 b=howdy!</b> | ||
195 | </blockquote> | ||
196 | |||
197 | <p> | ||
198 | Tcl variable names can appear in the SQL statement of the second argument | ||
199 | in any position where it is legal to put a string or number literal. The | ||
200 | value of the variable is substituted for the variable name. If the | ||
201 | variable does not exist a NULL values is used. For example: | ||
202 | </p> | ||
203 | |||
204 | <blockquote><b> | ||
205 | db1 eval {INSERT INTO t1 VALUES(5,$bigstring)} | ||
206 | </b></blockquote> | ||
207 | |||
208 | <p> | ||
209 | Note that it is not necessary to quote the $bigstring value. That happens | ||
210 | automatically. If $bigstring is a large string or binary object, this | ||
211 | technique is not only easier to write, it is also much more efficient | ||
212 | since it avoids making a copy of the content of $bigstring. | ||
213 | </p> | ||
214 | |||
215 | <p> | ||
216 | If the $bigstring variable has both a string and a "bytearray" representation, | ||
217 | then TCL inserts the value as a string. If it has only a "bytearray" | ||
218 | representation, then the value is inserted as a BLOB. To force a | ||
219 | value to be inserted as a BLOB even if it also has a text representation, | ||
220 | us a "@" character to in place of the "$". Like this: | ||
221 | </p> | ||
222 | |||
223 | <blockquote><b> | ||
224 | db1 eval {INSERT INTO t1 VALUES(5,@bigstring)} | ||
225 | </b></blockquote> | ||
226 | |||
227 | <p> | ||
228 | If the variable does not have a bytearray representation, then "@" works | ||
229 | just like "$". | ||
230 | </p> | ||
231 | |||
232 | } | ||
233 | |||
234 | ############################################################################## | ||
235 | METHOD close { | ||
236 | |||
237 | <p> | ||
238 | As its name suggests, the "close" method to an SQLite database just | ||
239 | closes the database. This has the side-effect of deleting the | ||
240 | <i>dbcmd</i> Tcl command. Here is an example of opening and then | ||
241 | immediately closing a database: | ||
242 | </p> | ||
243 | |||
244 | <blockquote> | ||
245 | <b>sqlite3 db1 ./testdb<br> | ||
246 | db1 close</b> | ||
247 | </blockquote> | ||
248 | |||
249 | <p> | ||
250 | If you delete the <i>dbcmd</i> directly, that has the same effect | ||
251 | as invoking the "close" method. So the following code is equivalent | ||
252 | to the previous:</p> | ||
253 | |||
254 | <blockquote> | ||
255 | <b>sqlite3 db1 ./testdb<br> | ||
256 | rename db1 {}</b> | ||
257 | </blockquote> | ||
258 | } | ||
259 | |||
260 | ############################################################################## | ||
261 | METHOD transaction { | ||
262 | |||
263 | <p> | ||
264 | The "transaction" method is used to execute a TCL script inside an SQLite | ||
265 | database transaction. The transaction is committed when the script completes, | ||
266 | or it rolls back if the script fails. If the transaction occurs within | ||
267 | another transaction (even one that is started manually using BEGIN) it | ||
268 | is a no-op. | ||
269 | </p> | ||
270 | |||
271 | <p> | ||
272 | The transaction command can be used to group together several SQLite | ||
273 | commands in a safe way. You can always start transactions manually using | ||
274 | BEGIN, of | ||
275 | course. But if an error occurs so that the COMMIT or ROLLBACK are never | ||
276 | run, then the database will remain locked indefinitely. Also, BEGIN | ||
277 | does not nest, so you have to make sure no other transactions are active | ||
278 | before starting a new one. The "transaction" method takes care of | ||
279 | all of these details automatically. | ||
280 | </p> | ||
281 | |||
282 | <p> | ||
283 | The syntax looks like this: | ||
284 | </p> | ||
285 | |||
286 | <blockquote> | ||
287 | <i>dbcmd</i> <b>transaction</b> <i>?transaction-type?</i> | ||
288 | <i>SCRIPT,</i> | ||
289 | </blockquote> | ||
290 | |||
291 | |||
292 | <p> | ||
293 | The <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 | ############################################################################## | ||
299 | METHOD cache { | ||
300 | |||
301 | <p> | ||
302 | The "eval" method described <a href="#eval">above</a> keeps a cache of | ||
303 | <a href="capi3ref.html#sqlite3_prepare">prepared statements</a> | ||
304 | for recently evaluated SQL commands. | ||
305 | The "cache" method is used to control this cache. | ||
306 | The first form of this command is:</p> | ||
307 | |||
308 | <blockquote> | ||
309 | <i>dbcmd</i> <b>cache size</b> <i>N</i> | ||
310 | </blockquote> | ||
311 | |||
312 | <p>This sets the maximum number of statements that can be cached. | ||
313 | The upper limit is 100. The default is 10. If you set the cache size | ||
314 | to 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> <b>cache flush</b> | ||
321 | </blockquote> | ||
322 | |||
323 | <p>The cache-flush method | ||
324 | <a href="capi3ref.html#sqlite3_finalize">finalizes</a> | ||
325 | all prepared statements currently | ||
326 | in the cache.</p> | ||
327 | |||
328 | } | ||
329 | |||
330 | ############################################################################## | ||
331 | METHOD complete { | ||
332 | |||
333 | <p> | ||
334 | The "complete" method takes a string of supposed SQL as its only argument. | ||
335 | It returns TRUE if the string is a complete statement of SQL and FALSE if | ||
336 | there is more to be entered.</p> | ||
337 | |||
338 | <p>The "complete" method is useful when building interactive applications | ||
339 | in order to know when the user has finished entering a line of SQL code. | ||
340 | This is really just an interface to the | ||
341 | <a href="capi3ref.html#sqlite3_complete"><b>sqlite3_complete()</b></a> C | ||
342 | function. | ||
343 | } | ||
344 | |||
345 | ############################################################################## | ||
346 | METHOD copy { | ||
347 | |||
348 | <p> | ||
349 | The "copy" method copies data from a file into a table. | ||
350 | It returns the number of rows processed successfully from the file. | ||
351 | The syntax of the copy method looks like this:</p> | ||
352 | |||
353 | <blockquote> | ||
354 | <i>dbcmd</i> <b>copy</b> <i>conflict-algorithm</i> | ||
355 | <i>table-name </i> <i>file-name </i> | ||
356 | ?<i>column-separator </i>? | ||
357 | ?<i>null-indicator</i>? | ||
358 | </blockquote> | ||
359 | |||
360 | <p>Conflict-alogrithm must be one of the SQLite conflict algorithms for | ||
361 | the INSERT statement: <i>rollback</i>, <i>abort</i>, | ||
362 | <i>fail</i>,<i>ignore</i>, or <i>replace</i>. See the SQLite Language | ||
363 | section for <a href="lang.html#conflict">ON CONFLICT</a> for more information. | ||
364 | The 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 | ||
368 | each row must contain the same number of columns as defined in the table. | ||
369 | If a line in the file contains more or less than the number of columns defined, | ||
370 | the copy method rollbacks any inserts, and returns an error.</p> | ||
371 | |||
372 | <p>Column-separator is an optional column separator string. The default is | ||
373 | the ASCII tab character \t. </p> | ||
374 | |||
375 | <p>Null-indicator is an optional string that indicates a column value is null. | ||
376 | The default is an empty string. Note that column-separator and | ||
377 | null-indicator are optional positional arguments; if null-indicator | ||
378 | is specified, a column-separator argument must be specifed and | ||
379 | precede the null-indicator argument.</p> | ||
380 | |||
381 | <p>The copy method implements similar functionality to the <b>.import</b> | ||
382 | SQLite shell command. | ||
383 | The SQLite 2.x <a href="lang.html#copy"><b>COPY</b></a> statement | ||
384 | (using the PostgreSQL COPY file format) | ||
385 | can be implemented with this method as:</p> | ||
386 | |||
387 | <blockquote> | ||
388 | dbcmd copy $conflictalgo | ||
389 | $tablename $filename | ||
390 | \t | ||
391 | \\N | ||
392 | </blockquote> | ||
393 | |||
394 | } | ||
395 | |||
396 | ############################################################################## | ||
397 | METHOD timeout { | ||
398 | |||
399 | <p>The "timeout" method is used to control how long the SQLite library | ||
400 | will wait for locks to clear before giving up on a database transaction. | ||
401 | The default timeout is 0 millisecond. (In other words, the default behavior | ||
402 | is not to wait at all.)</p> | ||
403 | |||
404 | <p>The SQLite database allows multiple simultaneous | ||
405 | readers or a single writer but not both. If any process is writing to | ||
406 | the database no other process is allows to read or write. If any process | ||
407 | is reading the database other processes are allowed to read but not write. | ||
408 | The entire database shared a single lock.</p> | ||
409 | |||
410 | <p>When SQLite tries to open a database and finds that it is locked, it | ||
411 | can optionally delay for a short while and try to open the file again. | ||
412 | This process repeats until the query times out and SQLite returns a | ||
413 | failure. The timeout is adjustable. It is set to 0 by default so that | ||
414 | if the database is locked, the SQL statement fails immediately. But you | ||
415 | can use the "timeout" method to change the timeout value to a positive | ||
416 | number. 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 | ||
421 | to wait for the lock to clear. So in the example above, the maximum delay | ||
422 | would be 2 seconds.</p> | ||
423 | } | ||
424 | |||
425 | ############################################################################## | ||
426 | METHOD busy { | ||
427 | |||
428 | <p>The "busy" method, like "timeout", only comes into play when the | ||
429 | database is locked. But the "busy" method gives the programmer much more | ||
430 | control over what action to take. The "busy" method specifies a callback | ||
431 | Tcl procedure that is invoked whenever SQLite tries to open a locked | ||
432 | database. This callback can do whatever is desired. Presumably, the | ||
433 | callback will do some other useful work for a short while (such as service | ||
434 | GUI events) then return | ||
435 | so that the lock can be tried again. The callback procedure should | ||
436 | return "0" if it wants SQLite to try again to open the database and | ||
437 | should return "1" if it wants SQLite to abandon the current operation. | ||
438 | } | ||
439 | |||
440 | ############################################################################## | ||
441 | METHOD exists { | ||
442 | |||
443 | <p>The "exists" method is similar to "onecolumn" and "eval" in that | ||
444 | it executes SQL statements. The difference is that the "exists" method | ||
445 | always returns a boolean value which is TRUE if a query in the SQL | ||
446 | statement it executes returns one or more rows and FALSE if the SQL | ||
447 | returns an empty set.</p> | ||
448 | |||
449 | <p>The "exists" method is often used to test for the existance of | ||
450 | rows in a table. For example:</p> | ||
451 | |||
452 | <blockquote><b> | ||
453 | if {[db exists {SELECT 1 FROM table1 WHERE user=$user}]} {<br> | ||
454 | # Processing if $user exists<br> | ||
455 | } else {<br> | ||
456 | # Processing if $user does not exist<br> | ||
457 | } | ||
458 | </b></blockquote> | ||
459 | } | ||
460 | |||
461 | |||
462 | ############################################################################## | ||
463 | METHOD last_insert_rowid { | ||
464 | |||
465 | <p>The "last_insert_rowid" method returns an integer which is the ROWID | ||
466 | of the most recently inserted database row.</p> | ||
467 | } | ||
468 | |||
469 | ############################################################################## | ||
470 | METHOD function { | ||
471 | |||
472 | <p>The "function" method registers new SQL functions with the SQLite engine. | ||
473 | The arguments are the name of the new SQL function and a TCL command that | ||
474 | implements that function. Arguments to the function are appended to the | ||
475 | TCL command before it is invoked.</p> | ||
476 | |||
477 | <p> | ||
478 | The following example creates a new SQL function named "hex" that converts | ||
479 | its numeric argument in to a hexadecimal encoded string: | ||
480 | </p> | ||
481 | |||
482 | <blockquote><b> | ||
483 | db function hex {format 0x%X} | ||
484 | </b></blockquote> | ||
485 | |||
486 | } | ||
487 | |||
488 | ############################################################################## | ||
489 | METHOD nullvalue { | ||
490 | |||
491 | <p> | ||
492 | The "nullvalue" method changes the representation for NULL returned | ||
493 | as result of the "eval" method.</p> | ||
494 | |||
495 | <blockquote><b> | ||
496 | db1 nullvalue NULL | ||
497 | </b></blockquote> | ||
498 | |||
499 | <p>The "nullvalue" method is useful to differ between NULL and empty | ||
500 | column values as Tcl lacks a NULL representation. The default | ||
501 | representation for NULL values is an empty string.</p> | ||
502 | } | ||
503 | |||
504 | |||
505 | |||
506 | ############################################################################## | ||
507 | METHOD onecolumn { | ||
508 | |||
509 | <p>The "onecolumn" method works like | ||
510 | "<a href="#eval">eval</a>" in that it evaluates the | ||
511 | SQL query statement given as its argument. The difference is that | ||
512 | "onecolumn" returns a single element which is the first column of the | ||
513 | first row of the query result.</p> | ||
514 | |||
515 | <p>This is a convenience method. It saves the user from having to | ||
516 | do a "<tt>[lindex ... 0]</tt>" on the results of an "eval" | ||
517 | in order to extract a single column result.</p> | ||
518 | } | ||
519 | |||
520 | ############################################################################## | ||
521 | METHOD changes { | ||
522 | |||
523 | <p>The "changes" method returns an integer which is the number of rows | ||
524 | in the database that were inserted, deleted, and/or modified by the most | ||
525 | recent "eval" method.</p> | ||
526 | } | ||
527 | |||
528 | ############################################################################## | ||
529 | METHOD total_changes { | ||
530 | |||
531 | <p>The "total_changes" method returns an integer which is the number of rows | ||
532 | in the database that were inserted, deleted, and/or modified since the | ||
533 | current database connection was first opened.</p> | ||
534 | } | ||
535 | |||
536 | ############################################################################## | ||
537 | METHOD authorizer { | ||
538 | |||
539 | <p>The "authorizer" method provides access to the | ||
540 | <a href="capi3ref.html#sqlite3_set_authorizer">sqlite3_set_authorizer</a> | ||
541 | C/C++ interface. The argument to authorizer is the name of a procedure that | ||
542 | is called when SQL statements are being compiled in order to authorize | ||
543 | certain operations. The callback procedure takes 5 arguments which describe | ||
544 | the operation being coded. If the callback returns the text string | ||
545 | "SQLITE_OK", then the operation is allowed. If it returns "SQLITE_IGNORE", | ||
546 | then the operation is silently disabled. If the return is "SQLITE_DENY" | ||
547 | then the compilation fails with an error. | ||
548 | </p> | ||
549 | |||
550 | <p>If the argument is an empty string then the authorizer is disabled. | ||
551 | If the argument is omitted, then the current authorizer is returned.</p> | ||
552 | } | ||
553 | |||
554 | ############################################################################## | ||
555 | METHOD progress { | ||
556 | |||
557 | <p>This method registers a callback that is invoked periodically during | ||
558 | query processing. There are two arguments: the number of SQLite virtual | ||
559 | machine opcodes between invocations, and the TCL command to invoke. | ||
560 | Setting 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 | ||
563 | query or to process GUI events during a lengthy query.</p> | ||
564 | } | ||
565 | |||
566 | |||
567 | ############################################################################## | ||
568 | METHOD collate { | ||
569 | |||
570 | <p>This method registers new text collating sequences. There are | ||
571 | two arguments: the name of the collating sequence and the name of a | ||
572 | TCL procedure that implements a comparison function for the collating | ||
573 | sequence. | ||
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> | ||
581 | proc nocase_compare {a b} {<br> | ||
582 | return [string compare [string tolower $a] [string tolower $b]]<br> | ||
583 | }<br> | ||
584 | db collate NOCASE nocase_compare<br> | ||
585 | </b></blockquote> | ||
586 | } | ||
587 | |||
588 | ############################################################################## | ||
589 | METHOD collation_needed { | ||
590 | |||
591 | <p>This method registers a callback routine that is invoked when the SQLite | ||
592 | engine needs a particular collating sequence but does not have that | ||
593 | collating sequence registered. The callback can register the collating | ||
594 | sequence. The callback is invoked with a single parameter which is the | ||
595 | name of the needed collating sequence.</p> | ||
596 | } | ||
597 | |||
598 | ############################################################################## | ||
599 | METHOD commit_hook { | ||
600 | |||
601 | <p>This method registers a callback routine that is invoked just before | ||
602 | SQLite tries to commit changes to a database. If the callback throws | ||
603 | an exception or returns a non-zero result, then the transaction rolls back | ||
604 | rather than commit.</p> | ||
605 | } | ||
606 | |||
607 | ############################################################################## | ||
608 | METHOD rollback_hook { | ||
609 | |||
610 | <p>This method registers a callback routine that is invoked just before | ||
611 | SQLite tries to do a rollback. The script argument is run without change.</p> | ||
612 | } | ||
613 | |||
614 | ############################################################################## | ||
615 | METHOD update_hook { | ||
616 | |||
617 | <p>This method registers a callback routine that is invoked just before | ||
618 | each row is modified by an UPDATE, INSERT, or DELETE statement. Four | ||
619 | arguments 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 | ############################################################################## | ||
630 | METHOD incrblob { | ||
631 | |||
632 | <p>This method opens a TCL channel that can be used to read or write | ||
633 | into a preexisting BLOB in the database. The syntax is like this:</p> | ||
634 | |||
635 | <blockquote> | ||
636 | <i>dbcmd</i> <b>incrblob</b> <b>?-readonly??</b> | ||
637 | <i>?DB? TABLE COLUMN ROWID</i> | ||
638 | </blockquote> | ||
639 | |||
640 | <p> | ||
641 | The command returns a new TCL channel for reading or writing to the BLOB. | ||
642 | The channel is opened using the underlying | ||
643 | <a href="/capi3ref.html#sqlite3_blob_open">sqlite3_blob_open()</a> C-langauge | ||
644 | interface. Close the channel using the <b>close</b> command of TCL. | ||
645 | </p> | ||
646 | } | ||
647 | |||
648 | ############################################################################## | ||
649 | METHOD errorcode { | ||
650 | |||
651 | <p>This method returns the numeric error code that resulted from the most | ||
652 | recent SQLite operation.</p> | ||
653 | } | ||
654 | |||
655 | ############################################################################## | ||
656 | METHOD trace { | ||
657 | |||
658 | <p>The "trace" method registers a callback that is invoked as each SQL | ||
659 | statement is compiled. The text of the SQL is appended as a single string | ||
660 | to the command before it is invoked. This can be used (for example) to | ||
661 | keep a log of all SQL operations that an application performs. | ||
662 | </p> | ||
663 | } | ||
664 | |||
665 | |||
666 | footer $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 | # | ||
4 | set rcsid {$Id: vdbe.tcl,v 1.14 2005/03/12 15:55:11 drh Exp $} | ||
5 | source common.tcl | ||
6 | header {The Virtual Database Engine of SQLite} | ||
7 | puts { | ||
8 | <h2>The Virtual Database Engine of SQLite</h2> | ||
9 | |||
10 | <blockquote><b> | ||
11 | This document describes the virtual machine used in SQLite version 2.8.0. | ||
12 | The virtual machine in SQLite version 3.0 and 3.1 is very similar in | ||
13 | concept but many of the opcodes have changed and the algorithms are | ||
14 | somewhat different. Use this document as a rough guide to the idea | ||
15 | behind the virtual machine in SQLite version 3, not as a reference on | ||
16 | how the virtual machine works. | ||
17 | </b></blockquote> | ||
18 | } | ||
19 | |||
20 | puts { | ||
21 | <p>If you want to know how the SQLite library works internally, | ||
22 | you need to begin with a solid understanding of the Virtual Database | ||
23 | Engine or VDBE. The VDBE occurs right in the middle of the | ||
24 | processing stream (see the <a href="arch.html">architecture diagram</a>) | ||
25 | and so it seems to touch most parts of the library. Even | ||
26 | parts of the code that do not directly interact with the VDBE | ||
27 | are usually in a supporting role. The VDBE really is the heart of | ||
28 | SQLite.</p> | ||
29 | |||
30 | <p>This article is a brief introduction to how the VDBE | ||
31 | works and in particular how the various VDBE instructions | ||
32 | (documented <a href="opcode.html">here</a>) work together | ||
33 | to do useful things with the database. The style is tutorial, | ||
34 | beginning with simple tasks and working toward solving more | ||
35 | complex problems. Along the way we will visit most | ||
36 | submodules in the SQLite library. After completeing this tutorial, | ||
37 | you should have a pretty good understanding of how SQLite works | ||
38 | and 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 | ||
43 | its virtual machine language. The goal of each program is to | ||
44 | interrogate or change the database. Toward this end, the machine | ||
45 | language that the VDBE implements is specifically designed to | ||
46 | search, read, and modify databases.</p> | ||
47 | |||
48 | <p>Each instruction of the VDBE language contains an opcode and | ||
49 | three operands labeled P1, P2, and P3. Operand P1 is an arbitrary | ||
50 | integer. P2 is a non-negative integer. P3 is a pointer to a data | ||
51 | structure or null-terminated string, possibly null. Only a few VDBE | ||
52 | instructions use all three operands. Many instructions use only | ||
53 | one or two operands. A significant number of instructions use | ||
54 | no operands at all but instead take their data and store their results | ||
55 | on the execution stack. The details of what each instruction | ||
56 | does 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 | ||
60 | execution on instruction 0 and continues with successive instructions | ||
61 | until it either (1) encounters a fatal error, (2) executes a | ||
62 | Halt instruction, or (3) advances the program counter past the | ||
63 | last instruction of the program. When the VDBE completes execution, | ||
64 | all open database cursors are closed, all memory is freed, and | ||
65 | everything is popped from the stack. | ||
66 | So there are never any worries about memory leaks or | ||
67 | undeallocated resources.</p> | ||
68 | |||
69 | <p>If you have done any assembly language programming or have | ||
70 | worked with any kind of abstract machine before, all of these | ||
71 | details should be familiar to you. So let's jump right in and | ||
72 | start 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 | ||
78 | that is only a few instructions long. Suppose we have an SQL | ||
79 | table that was created like this:</p> | ||
80 | |||
81 | <blockquote><pre> | ||
82 | CREATE TABLE examp(one text, two int); | ||
83 | </pre></blockquote> | ||
84 | |||
85 | <p>In words, we have a database table named "examp" that has two | ||
86 | columns of data named "one" and "two". Now suppose we want to insert a single | ||
87 | record into this table. Like this:</p> | ||
88 | |||
89 | <blockquote><pre> | ||
90 | INSERT INTO examp VALUES('Hello, World!',99); | ||
91 | </pre></blockquote> | ||
92 | |||
93 | <p>We can see the VDBE program that SQLite uses to implement this | ||
94 | INSERT using the <b>sqlite</b> command-line utility. First start | ||
95 | up <b>sqlite</b> on a new, empty database, then create the table. | ||
96 | Next change the output format of <b>sqlite</b> to a form that | ||
97 | is designed to work with VDBE program dumps by entering the | ||
98 | ".explain" command. | ||
99 | Finally, enter the INSERT statement shown above, but precede the | ||
100 | INSERT with the special keyword "EXPLAIN". The EXPLAIN keyword | ||
101 | will cause <b>sqlite</b> to print the VDBE program rather than | ||
102 | execute it. We have:</p> | ||
103 | } | ||
104 | proc Code {body} { | ||
105 | puts {<blockquote><tt>} | ||
106 | regsub -all {&} [string trim $body] {\&} body | ||
107 | regsub -all {>} $body {\>} body | ||
108 | regsub -all {<} $body {\<} body | ||
109 | regsub -all {\(\(\(} $body {<b>} body | ||
110 | regsub -all {\)\)\)} $body {</b>} body | ||
111 | regsub -all { } $body {\ } body | ||
112 | regsub -all \n $body <br>\n body | ||
113 | puts $body | ||
114 | puts {</tt></blockquote>} | ||
115 | } | ||
116 | |||
117 | Code { | ||
118 | $ (((sqlite test_database_1))) | ||
119 | sqlite> (((CREATE TABLE examp(one text, two int);))) | ||
120 | sqlite> (((.explain))) | ||
121 | sqlite> (((EXPLAIN INSERT INTO examp VALUES('Hello, World!',99);))) | ||
122 | addr opcode p1 p2 p3 | ||
123 | ---- ------------ ----- ----- ----------------------------------- | ||
124 | 0 Transaction 0 0 | ||
125 | 1 VerifyCookie 0 81 | ||
126 | 2 Transaction 1 0 | ||
127 | 3 Integer 0 0 | ||
128 | 4 OpenWrite 0 3 examp | ||
129 | 5 NewRecno 0 0 | ||
130 | 6 String 0 0 Hello, World! | ||
131 | 7 Integer 99 0 99 | ||
132 | 8 MakeRecord 2 0 | ||
133 | 9 PutIntKey 0 1 | ||
134 | 10 Close 0 0 | ||
135 | 11 Commit 0 0 | ||
136 | 12 Halt 0 0 | ||
137 | } | ||
138 | |||
139 | puts {<p>As you can see above, our simple insert statement is | ||
140 | implemented in 12 instructions. The first 3 and last 2 instructions are | ||
141 | a standard prologue and epilogue, so the real work is done in the middle | ||
142 | 7 instructions. There are no jumps, so the program executes once through | ||
143 | from top to bottom. Let's now look at each instruction in detail.<p> | ||
144 | } | ||
145 | |||
146 | Code { | ||
147 | 0 Transaction 0 0 | ||
148 | 1 VerifyCookie 0 81 | ||
149 | 2 Transaction 1 0 | ||
150 | } | ||
151 | puts { | ||
152 | <p>The instruction <a href="opcode.html#Transaction">Transaction</a> | ||
153 | begins a transaction. The transaction ends when a Commit or Rollback | ||
154 | opcode is encountered. P1 is the index of the database file on which | ||
155 | the transaction is started. Index 0 is the main database file. A write | ||
156 | lock is obtained on the database file when a transaction is started. | ||
157 | No other process can read or write the file while the transaction is | ||
158 | underway. Starting a transaction also creates a rollback journal. A | ||
159 | transaction must be started before any changes can be made to the | ||
160 | database.</p> | ||
161 | |||
162 | <p>The instruction <a href="opcode.html#VerifyCookie">VerifyCookie</a> | ||
163 | checks cookie 0 (the database schema version) to make sure it is equal | ||
164 | to P2 (the value obtained when the database schema was last read). | ||
165 | P1 is the database number (0 for the main database). This is done to | ||
166 | make sure the database schema hasn't been changed by another thread, in | ||
167 | which case it has to be reread.</p> | ||
168 | |||
169 | <p> The second <a href="opcode.html#Transaction">Transaction</a> | ||
170 | instruction begins a transaction and starts a rollback journal for | ||
171 | database 1, the database used for temporary tables.</p> | ||
172 | } | ||
173 | |||
174 | proc 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 | |||
182 | Code { | ||
183 | 3 Integer 0 0 | ||
184 | 4 OpenWrite 0 3 examp | ||
185 | } | ||
186 | puts { | ||
187 | <p> The instruction <a href="opcode.html#Integer">Integer</a> pushes | ||
188 | the integer value P1 (0) onto the stack. Here 0 is the number of the | ||
189 | database to use in the following OpenWrite instruction. If P3 is not | ||
190 | NULL then it is a string representation of the same integer. Afterwards | ||
191 | the stack looks like this:</p> | ||
192 | } | ||
193 | stack {(integer) 0} | ||
194 | |||
195 | puts { | ||
196 | <p> The instruction <a href="opcode.html#OpenWrite">OpenWrite</a> opens | ||
197 | a new read/write cursor with handle P1 (0 in this case) on table "examp", | ||
198 | whose root page is P2 (3, in this database file). Cursor handles can be | ||
199 | any non-negative integer. But the VDBE allocates cursors in an array | ||
200 | with the size of the array being one more than the largest cursor. So | ||
201 | to conserve memory, it is best to use handles beginning with zero and | ||
202 | working upward consecutively. Here P3 ("examp") is the name of the | ||
203 | table being opened, but this is unused, and only generated to make the | ||
204 | code 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 | ||
206 | stack is empty again.</p> | ||
207 | } | ||
208 | |||
209 | Code { | ||
210 | 5 NewRecno 0 0 | ||
211 | } | ||
212 | puts { | ||
213 | <p> The instruction <a href="opcode.html#NewRecno">NewRecno</a> creates | ||
214 | a new integer record number for the table pointed to by cursor P1. The | ||
215 | record number is one not currently used as a key in the table. The new | ||
216 | record number is pushed onto the stack. Afterwards the stack looks like | ||
217 | this:</p> | ||
218 | } | ||
219 | stack {(integer) new record key} | ||
220 | |||
221 | Code { | ||
222 | 6 String 0 0 Hello, World! | ||
223 | } | ||
224 | puts { | ||
225 | <p> The instruction <a href="opcode.html#String">String</a> pushes its | ||
226 | P3 operand onto the stack. Afterwards the stack looks like this:</p> | ||
227 | } | ||
228 | stack {(string) "Hello, World!"} \ | ||
229 | {(integer) new record key} | ||
230 | |||
231 | Code { | ||
232 | 7 Integer 99 0 99 | ||
233 | } | ||
234 | puts { | ||
235 | <p> The instruction <a href="opcode.html#Integer">Integer</a> pushes | ||
236 | its P1 operand (99) onto the stack. Afterwards the stack looks like | ||
237 | this:</p> | ||
238 | } | ||
239 | stack {(integer) 99} \ | ||
240 | {(string) "Hello, World!"} \ | ||
241 | {(integer) new record key} | ||
242 | |||
243 | Code { | ||
244 | 8 MakeRecord 2 0 | ||
245 | } | ||
246 | puts { | ||
247 | <p> The instruction <a href="opcode.html#MakeRecord">MakeRecord</a> pops | ||
248 | the top P1 elements off the stack (2 in this case) and converts them into | ||
249 | the binary format used for storing records in a database file. | ||
250 | (See the <a href="fileformat.html">file format</a> description for | ||
251 | details.) The new record generated by the MakeRecord instruction is | ||
252 | pushed back onto the stack. Afterwards the stack looks like this:</p> | ||
253 | </ul> | ||
254 | } | ||
255 | stack {(record) "Hello, World!", 99} \ | ||
256 | {(integer) new record key} | ||
257 | |||
258 | Code { | ||
259 | 9 PutIntKey 0 1 | ||
260 | } | ||
261 | puts { | ||
262 | <p> The instruction <a href="opcode.html#PutIntKey">PutIntKey</a> uses | ||
263 | the top 2 stack entries to write an entry into the table pointed to by | ||
264 | cursor P1. A new entry is created if it doesn't already exist or the | ||
265 | data for an existing entry is overwritten. The record data is the top | ||
266 | stack entry, and the key is the next entry down. The stack is popped | ||
267 | twice by this instruction. Because operand P2 is 1 the row change count | ||
268 | is incremented and the rowid is stored for subsequent return by the | ||
269 | sqlite_last_insert_rowid() function. If P2 is 0 the row change count is | ||
270 | unmodified. This instruction is where the insert actually occurs.</p> | ||
271 | } | ||
272 | |||
273 | Code { | ||
274 | 10 Close 0 0 | ||
275 | } | ||
276 | puts { | ||
277 | <p> The instruction <a href="opcode.html#Close">Close</a> closes a | ||
278 | cursor previously opened as P1 (0, the only open cursor). If P1 is not | ||
279 | currently open, this instruction is a no-op.</p> | ||
280 | } | ||
281 | |||
282 | Code { | ||
283 | 11 Commit 0 0 | ||
284 | } | ||
285 | puts { | ||
286 | <p> The instruction <a href="opcode.html#Commit">Commit</a> causes all | ||
287 | modifications to the database that have been made since the last | ||
288 | Transaction to actually take effect. No additional modifications are | ||
289 | allowed until another transaction is started. The Commit instruction | ||
290 | deletes the journal file and releases the write lock on the database. | ||
291 | A read lock continues to be held if there are still cursors open.</p> | ||
292 | } | ||
293 | |||
294 | Code { | ||
295 | 12 Halt 0 0 | ||
296 | } | ||
297 | puts { | ||
298 | <p> The instruction <a href="opcode.html#Halt">Halt</a> causes the VDBE | ||
299 | engine to exit immediately. All open cursors, Lists, Sorts, etc are | ||
300 | closed automatically. P1 is the result code returned by sqlite_exec(). | ||
301 | For a normal halt, this should be SQLITE_OK (0). For errors, it can be | ||
302 | some other value. The operand P2 is only used when there is an error. | ||
303 | There is an implied "Halt 0 0 0" instruction at the end of every | ||
304 | program, 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 | ||
311 | macro, 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 | ||
313 | feature was originally intended for testing and debugging, it can also | ||
314 | be useful in learning about how the VDBE operates. | ||
315 | Use "<tt>PRAGMA vdbe_trace=ON;</tt>" to turn tracing on and | ||
316 | "<tt>PRAGMA vdbe_trace=OFF</tt>" to turn tracing back off. | ||
317 | Like this:</p> | ||
318 | } | ||
319 | |||
320 | Code { | ||
321 | sqlite> (((PRAGMA vdbe_trace=ON;))) | ||
322 | 0 Halt 0 0 | ||
323 | sqlite> (((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 | ||
328 | Stack: i:0 | ||
329 | 4 OpenWrite 0 3 examp | ||
330 | 5 NewRecno 0 0 | ||
331 | Stack: i:2 | ||
332 | 6 String 0 0 Hello, World! | ||
333 | Stack: t[Hello,.World!] i:2 | ||
334 | 7 Integer 99 0 99 | ||
335 | Stack: si:99 t[Hello,.World!] i:2 | ||
336 | 8 MakeRecord 2 0 | ||
337 | Stack: 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 | |||
344 | puts { | ||
345 | <p>With tracing mode on, the VDBE prints each instruction prior | ||
346 | to executing it. After the instruction is executed, the top few | ||
347 | entries in the stack are displayed. The stack display is omitted | ||
348 | if the stack is empty.</p> | ||
349 | |||
350 | <p>On the stack display, most entries are shown with a prefix | ||
351 | that tells the datatype of that stack entry. Integers begin | ||
352 | with "<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>". | ||
355 | The difference among the string prefixes is caused by how their | ||
356 | memory is allocated. The z: strings are stored in memory obtained | ||
357 | from <b>malloc()</b>. The t: strings are statically allocated. | ||
358 | The e: strings are ephemeral. All other strings have the s: prefix. | ||
359 | This doesn't make any difference to you, | ||
360 | the observer, but it is vitally important to the VDBE since the | ||
361 | z: strings need to be passed to <b>free()</b> when they are | ||
362 | popped to avoid a memory leak. Note that only the first 10 | ||
363 | characters of string values are displayed and that binary | ||
364 | values (such as the result of the MakeRecord instruction) are | ||
365 | treated as strings. The only other datatype that can be stored | ||
366 | on the VDBE stack is a NULL, which is display without prefix | ||
367 | as simply "<tt>NULL</tt>". If an integer has been placed on the | ||
368 | stack 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 | ||
375 | writes to a database. Now let's look at how it does queries. | ||
376 | We will use the following simple SELECT statement as our example:</p> | ||
377 | |||
378 | <blockquote><pre> | ||
379 | SELECT * FROM examp; | ||
380 | </pre></blockquote> | ||
381 | |||
382 | <p>The VDBE program generated for this SQL statement is as follows:</p> | ||
383 | } | ||
384 | |||
385 | Code { | ||
386 | sqlite> (((EXPLAIN SELECT * FROM examp;))) | ||
387 | addr opcode p1 p2 p3 | ||
388 | ---- ------------ ----- ----- ----------------------------------- | ||
389 | 0 ColumnName 0 0 one | ||
390 | 1 ColumnName 1 0 two | ||
391 | 2 Integer 0 0 | ||
392 | 3 OpenRead 0 3 examp | ||
393 | 4 VerifyCookie 0 81 | ||
394 | 5 Rewind 0 10 | ||
395 | 6 Column 0 0 | ||
396 | 7 Column 0 1 | ||
397 | 8 Callback 2 0 | ||
398 | 9 Next 0 6 | ||
399 | 10 Close 0 0 | ||
400 | 11 Halt 0 0 | ||
401 | } | ||
402 | |||
403 | puts { | ||
404 | <p>Before we begin looking at this problem, let's briefly review | ||
405 | how queries work in SQLite so that we will know what we are trying | ||
406 | to accomplish. For each row in the result of a query, | ||
407 | SQLite will invoke a callback function with the following | ||
408 | prototype:</p> | ||
409 | |||
410 | <blockquote><pre> | ||
411 | int 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 | ||
415 | and the <b>pUserData</b> pointer. (Both the callback and the user data were | ||
416 | originally passed in as arguments to the <b>sqlite_exec()</b> API function.) | ||
417 | The job of the VDBE is to | ||
418 | come up with values for <b>nColumn</b>, <b>azData[]</b>, | ||
419 | and <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 | ||
422 | of one of the result columns. <b>azData[]</b> is an array of strings holding | ||
423 | the actual data.</p> | ||
424 | } | ||
425 | |||
426 | Code { | ||
427 | 0 ColumnName 0 0 one | ||
428 | 1 ColumnName 1 0 two | ||
429 | } | ||
430 | puts { | ||
431 | <p>The first two instructions in the VDBE program for our query are | ||
432 | concerned with setting up values for <b>azColumn</b>. | ||
433 | The <a href="opcode.html#ColumnName">ColumnName</a> instructions tell | ||
434 | the VDBE what values to fill in for each element of the <b>azColumnName[]</b> | ||
435 | array. Every query will begin with one ColumnName instruction for each | ||
436 | column in the result, and there will be a matching Column instruction for | ||
437 | each one later in the query. | ||
438 | </p> | ||
439 | } | ||
440 | |||
441 | Code { | ||
442 | 2 Integer 0 0 | ||
443 | 3 OpenRead 0 3 examp | ||
444 | 4 VerifyCookie 0 81 | ||
445 | } | ||
446 | puts { | ||
447 | <p>Instructions 2 and 3 open a read cursor on the database table that is | ||
448 | to be queried. This works the same as the OpenWrite instruction in the | ||
449 | INSERT example except that the cursor is opened for reading this time | ||
450 | instead of for writing. Instruction 4 verifies the database schema as | ||
451 | in the INSERT example.</p> | ||
452 | } | ||
453 | |||
454 | Code { | ||
455 | 5 Rewind 0 10 | ||
456 | } | ||
457 | puts { | ||
458 | <p> The <a href="opcode.html#Rewind">Rewind</a> instruction initializes | ||
459 | a loop that iterates over the "examp" table. It rewinds the cursor P1 | ||
460 | to the first entry in its table. This is required by the the Column and | ||
461 | Next instructions, which use the cursor to iterate through the table. | ||
462 | If the table is empty, then jump to P2 (10), which is the instruction just | ||
463 | past the loop. If the table is not empty, fall through to the following | ||
464 | instruction at 6, which is the beginning of the loop body.</p> | ||
465 | } | ||
466 | |||
467 | Code { | ||
468 | 6 Column 0 0 | ||
469 | 7 Column 0 1 | ||
470 | 8 Callback 2 0 | ||
471 | } | ||
472 | puts { | ||
473 | <p> The instructions 6 through 8 form the body of the loop that will | ||
474 | execute once for each record in the database file. | ||
475 | |||
476 | The <a href="opcode.html#Column">Column</a> instructions at addresses 6 | ||
477 | and 7 each take the P2-th column from the P1-th cursor and push it onto | ||
478 | the stack. In this example, the first Column instruction is pushing the | ||
479 | value for the column "one" onto the stack and the second Column | ||
480 | instruction is pushing the value for column "two". | ||
481 | |||
482 | The <a href="opcode.html#Callback">Callback</a> instruction at address 8 | ||
483 | invokes the callback() function. The P1 operand to Callback becomes the | ||
484 | value for <b>nColumn</b>. The Callback instruction pops P1 values from | ||
485 | the stack and uses them to fill the <b>azData[]</b> array.</p> | ||
486 | } | ||
487 | |||
488 | Code { | ||
489 | 9 Next 0 6 | ||
490 | } | ||
491 | puts { | ||
492 | <p>The instruction at address 9 implements the branching part of the | ||
493 | loop. Together with the Rewind at address 5 it forms the loop logic. | ||
494 | This is a key concept that you should pay close attention to. | ||
495 | The <a href="opcode.html#Next">Next</a> instruction advances the cursor | ||
496 | P1 to the next record. If the cursor advance was successful, then jump | ||
497 | immediately to P2 (6, the beginning of the loop body). If the cursor | ||
498 | was at the end, then fall through to the following instruction, which | ||
499 | ends the loop.</p> | ||
500 | } | ||
501 | |||
502 | Code { | ||
503 | 10 Close 0 0 | ||
504 | 11 Halt 0 0 | ||
505 | } | ||
506 | puts { | ||
507 | <p>The Close instruction at the end of the program closes the | ||
508 | cursor that points into the table "examp". It is not really necessary | ||
509 | to call Close here since all cursors will be automatically closed | ||
510 | by the VDBE when the program halts. But we needed an instruction | ||
511 | for the Rewind to jump to so we might as well go ahead and have that | ||
512 | instruction do something useful. | ||
513 | The Halt instruction ends the VDBE program.</p> | ||
514 | |||
515 | <p>Note that the program for this SELECT query didn't contain the | ||
516 | Transaction and Commit instructions used in the INSERT example. Because | ||
517 | the SELECT is a read operation that doesn't alter the database, it | ||
518 | doesn't require a transaction.</p> | ||
519 | } | ||
520 | |||
521 | |||
522 | puts { | ||
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 | ||
527 | instruction to invoke the callback function, and the use of the Next | ||
528 | instruction to implement a loop over all records of the database file. | ||
529 | This example attempts to drive home those ideas by demonstrating a | ||
530 | slightly more complex query that involves more columns of | ||
531 | output, some of which are computed values, and a WHERE clause that | ||
532 | limits which records actually make it to the callback function. | ||
533 | Consider this query:</p> | ||
534 | |||
535 | <blockquote><pre> | ||
536 | SELECT one, two, one || two AS 'both' | ||
537 | FROM examp | ||
538 | WHERE one LIKE 'H%' | ||
539 | </pre></blockquote> | ||
540 | |||
541 | <p>This query is perhaps a bit contrived, but it does serve to | ||
542 | illustrate our points. The result will have three column with | ||
543 | names "one", "two", and "both". The first two columns are direct | ||
544 | copies of the two columns in the table and the third result | ||
545 | column is a string formed by concatenating the first and | ||
546 | second columns of the table. | ||
547 | Finally, the | ||
548 | WHERE clause says that we will only chose rows for the | ||
549 | results where the "one" column begins with an "H". | ||
550 | Here is what the VDBE program looks like for this query:</p> | ||
551 | } | ||
552 | |||
553 | Code { | ||
554 | addr opcode p1 p2 p3 | ||
555 | ---- ------------ ----- ----- ----------------------------------- | ||
556 | 0 ColumnName 0 0 one | ||
557 | 1 ColumnName 1 0 two | ||
558 | 2 ColumnName 2 0 both | ||
559 | 3 Integer 0 0 | ||
560 | 4 OpenRead 0 3 examp | ||
561 | 5 VerifyCookie 0 81 | ||
562 | 6 Rewind 0 18 | ||
563 | 7 String 0 0 H% | ||
564 | 8 Column 0 0 | ||
565 | 9 Function 2 0 ptr(0x7f1ac0) | ||
566 | 10 IfNot 1 17 | ||
567 | 11 Column 0 0 | ||
568 | 12 Column 0 1 | ||
569 | 13 Column 0 0 | ||
570 | 14 Column 0 1 | ||
571 | 15 Concat 2 0 | ||
572 | 16 Callback 3 0 | ||
573 | 17 Next 0 7 | ||
574 | 18 Close 0 0 | ||
575 | 19 Halt 0 0 | ||
576 | } | ||
577 | |||
578 | puts { | ||
579 | <p>Except for the WHERE clause, the structure of the program for | ||
580 | this example is very much like the prior example, just with an | ||
581 | extra column. There are now 3 columns, instead of 2 as before, | ||
582 | and there are three ColumnName instructions. | ||
583 | A cursor is opened using the OpenRead instruction, just like in the | ||
584 | prior example. The Rewind instruction at address 6 and the | ||
585 | Next at address 17 form a loop over all records of the table. | ||
586 | The Close instruction at the end is there to give the | ||
587 | Rewind instruction something to jump to when it is done. All of | ||
588 | this is just like in the first query demonstration.</p> | ||
589 | |||
590 | <p>The Callback instruction in this example has to generate | ||
591 | data for three result columns instead of two, but is otherwise | ||
592 | the same as in the first query. When the Callback instruction | ||
593 | is invoked, the left-most column of the result should be | ||
594 | the lowest in the stack and the right-most result column should | ||
595 | be the top of the stack. We can see the stack being set up | ||
596 | this way at addresses 11 through 15. The Column instructions at | ||
597 | 11 and 12 push the values for the first two columns in the result. | ||
598 | The two Column instructions at 13 and 14 pull in the values needed | ||
599 | to compute the third result column and the Concat instruction at | ||
600 | 15 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 | ||
603 | is the WHERE clause which is implemented by instructions at | ||
604 | addresses 7 through 10. Instructions at address 7 and 8 push | ||
605 | onto the stack the value of the "one" column from the table | ||
606 | and the literal string "H%". | ||
607 | The <a href="opcode.html#Function">Function</a> instruction at address 9 | ||
608 | pops these two values from the stack and pushes the result of the LIKE() | ||
609 | function back onto the stack. | ||
610 | The <a href="opcode.html#IfNot">IfNot</a> instruction pops the top stack | ||
611 | value and causes an immediate jump forward to the Next instruction if the | ||
612 | top value was false (<em>not</em> not like the literal string "H%"). | ||
613 | Taking this jump effectively skips the callback, which is the whole point | ||
614 | of the WHERE clause. If the result | ||
615 | of the comparison is true, the jump is not taken and control | ||
616 | falls through to the Callback instruction below.</p> | ||
617 | |||
618 | <p>Notice how the LIKE operator is implemented. It is a user-defined | ||
619 | function in SQLite, so the address of its function definition is | ||
620 | specified in P3. The operand P1 is the number of function arguments for | ||
621 | it to take from the stack. In this case the LIKE() function takes 2 | ||
622 | arguments. 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 | ||
624 | the next element is the data to compare. The return value is pushed | ||
625 | onto 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 | ||
632 | every 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 | ||
650 | additional complications such as joins, compound selects, using | ||
651 | indices to speed the search, sorting, and aggregate functions | ||
652 | with and without GROUP BY and HAVING clauses. | ||
653 | But 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 | ||
658 | that is very similar to the SELECT statement template. The main | ||
659 | difference, of course, is that the end action is to modify the | ||
660 | database rather than invoke a callback function. Because it modifies | ||
661 | the database it will also use transactions. Let's begin | ||
662 | by looking at a DELETE statement:</p> | ||
663 | |||
664 | <blockquote><pre> | ||
665 | DELETE FROM examp WHERE two<50; | ||
666 | </pre></blockquote> | ||
667 | |||
668 | <p>This DELETE statement will remove every record from the "examp" | ||
669 | table where the "two" column is less than 50. | ||
670 | The code generated to do this is as follows:</p> | ||
671 | } | ||
672 | |||
673 | Code { | ||
674 | addr opcode p1 p2 p3 | ||
675 | ---- ------------ ----- ----- ----------------------------------- | ||
676 | 0 Transaction 1 0 | ||
677 | 1 Transaction 0 0 | ||
678 | 2 VerifyCookie 0 178 | ||
679 | 3 Integer 0 0 | ||
680 | 4 OpenRead 0 3 examp | ||
681 | 5 Rewind 0 12 | ||
682 | 6 Column 0 1 | ||
683 | 7 Integer 50 0 50 | ||
684 | 8 Ge 1 11 | ||
685 | 9 Recno 0 0 | ||
686 | 10 ListWrite 0 0 | ||
687 | 11 Next 0 6 | ||
688 | 12 Close 0 0 | ||
689 | 13 ListRewind 0 0 | ||
690 | 14 Integer 0 0 | ||
691 | 15 OpenWrite 0 3 | ||
692 | 16 ListRead 0 20 | ||
693 | 17 NotExists 0 19 | ||
694 | 18 Delete 0 1 | ||
695 | 19 Goto 0 16 | ||
696 | 20 ListReset 0 0 | ||
697 | 21 Close 0 0 | ||
698 | 22 Commit 0 0 | ||
699 | 23 Halt 0 0 | ||
700 | } | ||
701 | |||
702 | puts { | ||
703 | <p>Here is what the program must do. First it has to locate all of | ||
704 | the records in the table "examp" that are to be deleted. This is | ||
705 | done using a loop very much like the loop used in the SELECT examples | ||
706 | above. Once all records have been located, then we can go back through | ||
707 | and delete them one by one. Note that we cannot delete each record | ||
708 | as soon as we find it. We have to locate all records first, then | ||
709 | go back and delete them. This is because the SQLite database | ||
710 | backend might change the scan order after a delete operation. | ||
711 | And if the scan | ||
712 | order changes in the middle of the scan, some records might be | ||
713 | visited 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 | ||
717 | and 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 | ||
719 | by one. </p> | ||
720 | } | ||
721 | |||
722 | |||
723 | Code { | ||
724 | 0 Transaction 1 0 | ||
725 | 1 Transaction 0 0 | ||
726 | 2 VerifyCookie 0 178 | ||
727 | 3 Integer 0 0 | ||
728 | 4 OpenRead 0 3 examp | ||
729 | } | ||
730 | puts { | ||
731 | <p>Instructions 0 though 4 are as in the INSERT example. They start | ||
732 | transactions for the main and temporary databases, verify the database | ||
733 | schema 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 | ||
735 | this stage of the program we are only going to be scanning the table, | ||
736 | not changing it. We will reopen the same table for writing later, at | ||
737 | instruction 15.</p> | ||
738 | } | ||
739 | |||
740 | Code { | ||
741 | 5 Rewind 0 12 | ||
742 | } | ||
743 | puts { | ||
744 | <p>As in the SELECT example, the <a href="opcode.html#Rewind">Rewind</a> | ||
745 | instruction rewinds the cursor to the beginning of the table, readying | ||
746 | it for use in the loop body.</p> | ||
747 | } | ||
748 | |||
749 | Code { | ||
750 | 6 Column 0 1 | ||
751 | 7 Integer 50 0 50 | ||
752 | 8 Ge 1 11 | ||
753 | } | ||
754 | puts { | ||
755 | <p>The WHERE clause is implemented by instructions 6 through 8. | ||
756 | The job of the where clause is to skip the ListWrite if the WHERE | ||
757 | condition is false. To this end, it jumps ahead to the Next instruction | ||
758 | if the "two" column (extracted by the Column instruction) is | ||
759 | greater than or equal to 50.</p> | ||
760 | |||
761 | <p>As before, the Column instruction uses cursor P1 and pushes the data | ||
762 | record in column P2 (1, column "two") onto the stack. The Integer | ||
763 | instruction pushes the value 50 onto the top of the stack. After these | ||
764 | two instructions the stack looks like:</p> | ||
765 | } | ||
766 | stack {(integer) 50} \ | ||
767 | {(record) current record for column "two" } | ||
768 | |||
769 | puts { | ||
770 | <p>The <a href="opcode.html#Ge">Ge</a> operator compares the top two | ||
771 | elements on the stack, pops them, and then branches based on the result | ||
772 | of the comparison. If the second element is >= the top element, then | ||
773 | jump to address P2 (the Next instruction at the end of the loop). | ||
774 | Because P1 is true, if either operand is NULL (and thus the result is | ||
775 | NULL) then take the jump. If we don't jump, just advance to the next | ||
776 | instruction.</p> | ||
777 | } | ||
778 | |||
779 | Code { | ||
780 | 9 Recno 0 0 | ||
781 | 10 ListWrite 0 0 | ||
782 | } | ||
783 | puts { | ||
784 | <p>The <a href="opcode.html#Recno">Recno</a> instruction pushes onto the | ||
785 | stack an integer which is the first 4 bytes of the the key to the current | ||
786 | entry in a sequential scan of the table pointed to by cursor P1. | ||
787 | The <a href="opcode.html#ListWrite">ListWrite</a> instruction writes the | ||
788 | integer on the top of the stack into a temporary storage list and pops | ||
789 | the top element. This is the important work of this loop, to store the | ||
790 | keys of the records to be deleted so we can delete them in the second | ||
791 | loop. After this ListWrite instruction the stack is empty again.</p> | ||
792 | } | ||
793 | |||
794 | Code { | ||
795 | 11 Next 0 6 | ||
796 | 12 Close 0 0 | ||
797 | } | ||
798 | puts { | ||
799 | <p> The Next instruction increments the cursor to point to the next | ||
800 | element in the table pointed to by cursor P0, and if it was successful | ||
801 | branches to P2 (6, the beginning of the loop body). The Close | ||
802 | instruction closes cursor P1. It doesn't affect the temporary storage | ||
803 | list because it isn't associated with cursor P1; it is instead a global | ||
804 | working list (which can be saved with ListPush).</p> | ||
805 | } | ||
806 | |||
807 | Code { | ||
808 | 13 ListRewind 0 0 | ||
809 | } | ||
810 | puts { | ||
811 | <p> The <a href="opcode.html#ListRewind">ListRewind</a> instruction | ||
812 | rewinds the temporary storage list to the beginning. This prepares it | ||
813 | for use in the second loop.</p> | ||
814 | } | ||
815 | |||
816 | Code { | ||
817 | 14 Integer 0 0 | ||
818 | 15 OpenWrite 0 3 | ||
819 | } | ||
820 | puts { | ||
821 | <p> As in the INSERT example, we push the database number P1 (0, the main | ||
822 | database) onto the stack and use OpenWrite to open the cursor P1 on table | ||
823 | P2 (base page 3, "examp") for modification.</p> | ||
824 | } | ||
825 | |||
826 | Code { | ||
827 | 16 ListRead 0 20 | ||
828 | 17 NotExists 0 19 | ||
829 | 18 Delete 0 1 | ||
830 | 19 Goto 0 16 | ||
831 | } | ||
832 | puts { | ||
833 | <p>This loop does the actual deleting. It is organized differently from | ||
834 | the one in the UPDATE example. The ListRead instruction plays the role | ||
835 | that the Next did in the INSERT loop, but because it jumps to P2 on | ||
836 | failure, and Next jumps on success, we put it at the start of the loop | ||
837 | instead of the end. This means that we have to put a Goto at the end of | ||
838 | the loop to jump back to the the loop test at the beginning. So this | ||
839 | loop has the form of a C while(){...} loop, while the loop in the INSERT | ||
840 | example had the form of a do{...}while() loop. The Delete instruction | ||
841 | fills 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 | ||
844 | element from the temporary storage list and pushes it onto the stack. | ||
845 | If this was successful, it continues to the next instruction. If this | ||
846 | fails because the list is empty, it branches to P2, which is the | ||
847 | instruction just after the loop. Afterwards the stack looks like:</p> | ||
848 | } | ||
849 | stack {(integer) key for current record} | ||
850 | |||
851 | puts { | ||
852 | <p>Notice the similarity between the ListRead and Next instructions. | ||
853 | Both operations work according to this rule: | ||
854 | </p> | ||
855 | <blockquote> | ||
856 | Push the next "thing" onto the stack and fall through OR jump to P2, | ||
857 | depending 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". | ||
860 | The "things" for the Next instruction are records in a database file. | ||
861 | "Things" for ListRead are integer keys in a list. Another difference | ||
862 | is whether to jump or fall through if there is no next "thing". In this | ||
863 | case, Next falls through, and ListRead jumps. Later on, we will see | ||
864 | other looping instructions (NextIdx and SortNext) that operate using the | ||
865 | same principle.</p> | ||
866 | |||
867 | <p>The <a href="opcode.html#NotExists">NotExists</a> instruction pops | ||
868 | the top stack element and uses it as an integer key. If a record with | ||
869 | that key does not exist in table P1, then jump to P2. If a record does | ||
870 | exist, then fall thru to the next instruction. In this case P2 takes | ||
871 | us to the Goto at the end of the loop, which jumps back to the ListRead | ||
872 | at the beginning. This could have been coded to have P2 be 16, the | ||
873 | ListRead at the start of the loop, but the SQLite parser which generated | ||
874 | this code didn't make that optimization.</p> | ||
875 | <p>The <a href="opcode.html#Delete">Delete</a> does the work of this | ||
876 | loop; it pops an integer key off the stack (placed there by the | ||
877 | preceding ListRead) and deletes the record of cursor P1 that has that key. | ||
878 | Because 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 | ||
880 | of the loop. This is the end of the loop.</p> | ||
881 | } | ||
882 | |||
883 | Code { | ||
884 | 20 ListReset 0 0 | ||
885 | 21 Close 0 0 | ||
886 | 22 Commit 0 0 | ||
887 | 23 Halt 0 0 | ||
888 | } | ||
889 | puts { | ||
890 | <p>This block of instruction cleans up the VDBE program. Three of these | ||
891 | instructions aren't really required, but are generated by the SQLite | ||
892 | parser from its code templates, which are designed to handle more | ||
893 | complicated cases.</p> | ||
894 | <p>The <a href="opcode.html#ListReset">ListReset</a> instruction empties | ||
895 | the temporary storage list. This list is emptied automatically when the | ||
896 | VDBE program terminates, so it isn't necessary in this case. The Close | ||
897 | instruction closes the cursor P1. Again, this is done by the VDBE | ||
898 | engine when it is finished running this program. The Commit ends the | ||
899 | current transaction successfully, and causes all changes that occurred | ||
900 | in this transaction to be saved to the database. The final Halt is also | ||
901 | unneccessary, since it is added to every VDBE program when it is | ||
902 | prepared to run.</p> | ||
903 | |||
904 | |||
905 | <p>UPDATE statements work very much like DELETE statements except | ||
906 | that instead of deleting the record they replace it with a new one. | ||
907 | Consider this example: | ||
908 | </p> | ||
909 | |||
910 | <blockquote><pre> | ||
911 | UPDATE examp SET one= '(' || one || ')' WHERE two < 50; | ||
912 | </pre></blockquote> | ||
913 | |||
914 | <p>Instead of deleting records where the "two" column is less than | ||
915 | 50, this statement just puts the "one" column in parentheses | ||
916 | The VDBE program to implement this statement follows:</p> | ||
917 | } | ||
918 | |||
919 | Code { | ||
920 | addr opcode p1 p2 p3 | ||
921 | ---- ------------ ----- ----- ----------------------------------- | ||
922 | 0 Transaction 1 0 | ||
923 | 1 Transaction 0 0 | ||
924 | 2 VerifyCookie 0 178 | ||
925 | 3 Integer 0 0 | ||
926 | 4 OpenRead 0 3 examp | ||
927 | 5 Rewind 0 12 | ||
928 | 6 Column 0 1 | ||
929 | 7 Integer 50 0 50 | ||
930 | 8 Ge 1 11 | ||
931 | 9 Recno 0 0 | ||
932 | 10 ListWrite 0 0 | ||
933 | 11 Next 0 6 | ||
934 | 12 Close 0 0 | ||
935 | 13 Integer 0 0 | ||
936 | 14 OpenWrite 0 3 | ||
937 | 15 ListRewind 0 0 | ||
938 | 16 ListRead 0 28 | ||
939 | 17 Dup 0 0 | ||
940 | 18 NotExists 0 16 | ||
941 | 19 String 0 0 ( | ||
942 | 20 Column 0 0 | ||
943 | 21 Concat 2 0 | ||
944 | 22 String 0 0 ) | ||
945 | 23 Concat 2 0 | ||
946 | 24 Column 0 1 | ||
947 | 25 MakeRecord 2 0 | ||
948 | 26 PutIntKey 0 1 | ||
949 | 27 Goto 0 16 | ||
950 | 28 ListReset 0 0 | ||
951 | 29 Close 0 0 | ||
952 | 30 Commit 0 0 | ||
953 | 31 Halt 0 0 | ||
954 | } | ||
955 | |||
956 | puts { | ||
957 | <p>This program is essentially the same as the DELETE program except | ||
958 | that the body of the second loop has been replace by a sequence of | ||
959 | instructions (at addresses 17 through 26) that update the record rather | ||
960 | than delete it. Most of this instruction sequence should already be | ||
961 | familiar to you, but there are a couple of minor twists so we will go | ||
962 | over it briefly. Also note that the order of some of the instructions | ||
963 | before and after the 2nd loop has changed. This is just the way the | ||
964 | SQLite 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) | ||
967 | the stack contains a single integer which is the key of the | ||
968 | record we want to modify. We are going to need to use this | ||
969 | key twice: once to fetch the old value of the record and | ||
970 | a second time to write back the revised record. So the first instruction | ||
971 | is a Dup to make a duplicate of the key on the top of the stack. The | ||
972 | Dup instruction will duplicate any element of the stack, not just the top | ||
973 | element. You specify which element to duplication using the | ||
974 | P1 operand. When P1 is 0, the top of the stack is duplicated. | ||
975 | When P1 is 1, the next element down on the stack duplication. | ||
976 | And so forth.</p> | ||
977 | |||
978 | <p>After duplicating the key, the next instruction, NotExists, | ||
979 | pops the stack once and uses the value popped as a key to | ||
980 | check the existence of a record in the database file. If there is no record | ||
981 | for 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 | ||
984 | that will be used to replace the existing record. This is | ||
985 | the same kind of code that we saw | ||
986 | in the description of INSERT and will not be described further. | ||
987 | After instruction 25 executes, the stack looks like this:</p> | ||
988 | } | ||
989 | |||
990 | stack {(record) new data record} {(integer) key} | ||
991 | |||
992 | puts { | ||
993 | <p>The PutIntKey instruction (also described | ||
994 | during the discussion about INSERT) writes an entry into the | ||
995 | database file whose data is the top of the stack and whose key | ||
996 | is the next on the stack, and then pops the stack twice. The | ||
997 | PutIntKey instruction will overwrite the data of an existing record | ||
998 | with the same key, which is what we want here. Overwriting was not | ||
999 | an issue with INSERT because with INSERT the key was generated | ||
1000 | by the NewRecno instruction which is guaranteed to provide a key | ||
1001 | that has not been used before.</p> | ||
1002 | } | ||
1003 | |||
1004 | if 0 {<p>(By the way, since keys must | ||
1005 | all be unique and each key is a 32-bit integer, a single | ||
1006 | SQLite database table can have no more than 2<sup>32</sup> | ||
1007 | rows. Actually, the Key instruction starts to become | ||
1008 | very inefficient as you approach this upper bound, so it | ||
1009 | is best to keep the number of entries below 2<sup>31</sup> | ||
1010 | or so. Surely a couple billion records will be enough for | ||
1011 | most applications!)</p> | ||
1012 | } | ||
1013 | |||
1014 | puts { | ||
1015 | <h2>CREATE and DROP</h2> | ||
1016 | |||
1017 | <p>Using CREATE or DROP to create or destroy a table or index is | ||
1018 | really 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. | ||
1020 | The sqlite_master table is a special table that is automatically | ||
1021 | created for every SQLite database. It looks like this:</p> | ||
1022 | |||
1023 | <blockquote><pre> | ||
1024 | CREATE 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) | ||
1033 | and every named index in an SQLite database has an entry | ||
1034 | in the sqlite_master table. You can query this table using | ||
1035 | a SELECT statement just like any other table. But you are | ||
1036 | not allowed to directly change the table using UPDATE, INSERT, | ||
1037 | or DELETE. Changes to sqlite_master have to occur using | ||
1038 | the CREATE and DROP commands because SQLite also has to update | ||
1039 | some of its internal data structures when tables and indices | ||
1040 | are added or destroyed.</p> | ||
1041 | |||
1042 | <p>But from the point of view of the VDBE, a CREATE works | ||
1043 | pretty much like an INSERT and a DROP works like a DELETE. | ||
1044 | When the SQLite library opens to an existing database, | ||
1045 | the first thing it does is a SELECT to read the "sql" | ||
1046 | columns from all entries of the sqlite_master table. | ||
1047 | The "sql" column contains the complete SQL text of the | ||
1048 | CREATE statement that originally generated the index or | ||
1049 | table. This text is fed back into the SQLite parser | ||
1050 | and used to reconstruct the | ||
1051 | internal 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 | ||
1056 | queried must be loaded off of the disk and examined, even if only | ||
1057 | a small percentage of the rows end up in the result. This can | ||
1058 | take a long time on a big table. To speed things up, SQLite | ||
1059 | can use an index.</p> | ||
1060 | |||
1061 | <p>An SQLite file associates a key with some data. For an SQLite | ||
1062 | table, the database file is set up so that the key is an integer | ||
1063 | and the data is the information for one row of the table. | ||
1064 | Indices in SQLite reverse this arrangement. The index key | ||
1065 | is (some of) the information being stored and the index data | ||
1066 | is an integer. | ||
1067 | To access a table row that has some particular | ||
1068 | content, we first look up the content in the index table to find | ||
1069 | its integer index, then we use that integer to look up the | ||
1070 | complete record in the table.</p> | ||
1071 | |||
1072 | <p>Note that SQLite uses b-trees, which are a sorted data structure, | ||
1073 | so indices can be used when the WHERE clause of the SELECT statement | ||
1074 | contains tests for equality or inequality. Queries like the following | ||
1075 | can use an index if it is available:</p> | ||
1076 | |||
1077 | <blockquote><pre> | ||
1078 | SELECT * FROM examp WHERE two==50; | ||
1079 | SELECT * FROM examp WHERE two<50; | ||
1080 | SELECT * 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" | ||
1084 | table into integers, then SQLite will use that index to find the integer | ||
1085 | keys of all rows in examp that have a value of 50 for column two, or | ||
1086 | all rows that are less than 50, etc. | ||
1087 | But the following queries cannot use the index:</p> | ||
1088 | |||
1089 | <blockquote><pre> | ||
1090 | SELECT * FROM examp WHERE two%50 == 10; | ||
1091 | SELECT * 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 | ||
1095 | index, even if it is possible to do so. The following queries will not | ||
1096 | currently use the index:</p> | ||
1097 | |||
1098 | <blockquote><pre> | ||
1099 | SELECT * FROM examp WHERE two+10 == 50; | ||
1100 | SELECT * 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 | ||
1104 | they are created. Let's go ahead and put an index on the two | ||
1105 | column of the examp table. We have:</p> | ||
1106 | |||
1107 | <blockquote><pre> | ||
1108 | CREATE INDEX examp_idx1 ON examp(two); | ||
1109 | </pre></blockquote> | ||
1110 | |||
1111 | <p>The VDBE code generated by the above statement looks like the | ||
1112 | following:</p> | ||
1113 | } | ||
1114 | |||
1115 | Code { | ||
1116 | addr opcode p1 p2 p3 | ||
1117 | ---- ------------ ----- ----- ----------------------------------- | ||
1118 | 0 Transaction 1 0 | ||
1119 | 1 Transaction 0 0 | ||
1120 | 2 VerifyCookie 0 178 | ||
1121 | 3 Integer 0 0 | ||
1122 | 4 OpenWrite 0 2 | ||
1123 | 5 NewRecno 0 0 | ||
1124 | 6 String 0 0 index | ||
1125 | 7 String 0 0 examp_idx1 | ||
1126 | 8 String 0 0 examp | ||
1127 | 9 CreateIndex 0 0 ptr(0x791380) | ||
1128 | 10 Dup 0 0 | ||
1129 | 11 Integer 0 0 | ||
1130 | 12 OpenWrite 1 0 | ||
1131 | 13 String 0 0 CREATE INDEX examp_idx1 ON examp(tw | ||
1132 | 14 MakeRecord 5 0 | ||
1133 | 15 PutIntKey 0 0 | ||
1134 | 16 Integer 0 0 | ||
1135 | 17 OpenRead 2 3 examp | ||
1136 | 18 Rewind 2 24 | ||
1137 | 19 Recno 2 0 | ||
1138 | 20 Column 2 1 | ||
1139 | 21 MakeIdxKey 1 0 n | ||
1140 | 22 IdxPut 1 0 indexed columns are not unique | ||
1141 | 23 Next 2 19 | ||
1142 | 24 Close 2 0 | ||
1143 | 25 Close 1 0 | ||
1144 | 26 Integer 333 0 | ||
1145 | 27 SetCookie 0 0 | ||
1146 | 28 Close 0 0 | ||
1147 | 29 Commit 0 0 | ||
1148 | 30 Halt 0 0 | ||
1149 | } | ||
1150 | |||
1151 | puts { | ||
1152 | <p>Remember that every table (except sqlite_master) and every named | ||
1153 | index has an entry in the sqlite_master table. Since we are creating | ||
1154 | a new index, we have to add a new entry to sqlite_master. This is | ||
1155 | handled by instructions 3 through 15. Adding an entry to sqlite_master | ||
1156 | works just like any other INSERT statement so we will not say anymore | ||
1157 | about it here. In this example, we want to focus on populating the | ||
1158 | new index with valid data, which happens on instructions 16 through | ||
1159 | 23.</p> | ||
1160 | } | ||
1161 | |||
1162 | Code { | ||
1163 | 16 Integer 0 0 | ||
1164 | 17 OpenRead 2 3 examp | ||
1165 | } | ||
1166 | puts { | ||
1167 | <p>The first thing that happens is that we open the table being | ||
1168 | indexed for reading. In order to construct an index for a table, | ||
1169 | we have to know what is in that table. The index has already been | ||
1170 | opened for writing using cursor 0 by instructions 3 and 4.</p> | ||
1171 | } | ||
1172 | |||
1173 | Code { | ||
1174 | 18 Rewind 2 24 | ||
1175 | 19 Recno 2 0 | ||
1176 | 20 Column 2 1 | ||
1177 | 21 MakeIdxKey 1 0 n | ||
1178 | 22 IdxPut 1 0 indexed columns are not unique | ||
1179 | 23 Next 2 19 | ||
1180 | } | ||
1181 | puts { | ||
1182 | <p>Instructions 18 through 23 implement a loop over every row of the | ||
1183 | table being indexed. For each table row, we first extract the integer | ||
1184 | key for that row using Recno in instruction 19, then get the value of | ||
1185 | the "two" column using Column in instruction 20. | ||
1186 | The <a href="opcode.html#MakeIdxKey">MakeIdxKey</a> instruction at 21 | ||
1187 | converts data from the "two" column (which is on the top of the stack) | ||
1188 | into a valid index key. For an index on a single column, this is | ||
1189 | basically a no-op. But if the P1 operand to MakeIdxKey had been | ||
1190 | greater than one multiple entries would have been popped from the stack | ||
1191 | and converted into a single index key. | ||
1192 | The <a href="opcode.html#IdxPut">IdxPut</a> instruction at 22 is what | ||
1193 | actually creates the index entry. IdxPut pops two elements from the | ||
1194 | stack. The top of the stack is used as a key to fetch an entry from the | ||
1195 | index table. Then the integer which was second on stack is added to the | ||
1196 | set of integers for that index and the new record is written back to the | ||
1197 | database file. Note | ||
1198 | that the same index entry can store multiple integers if there | ||
1199 | are two or more table entries with the same value for the two | ||
1200 | column. | ||
1201 | </p> | ||
1202 | |||
1203 | <p>Now let's look at how this index will be used. Consider the | ||
1204 | following query:</p> | ||
1205 | |||
1206 | <blockquote><pre> | ||
1207 | SELECT * FROM examp WHERE two==50; | ||
1208 | </pre></blockquote> | ||
1209 | |||
1210 | <p>SQLite generates the following VDBE code to handle this query:</p> | ||
1211 | } | ||
1212 | |||
1213 | Code { | ||
1214 | addr opcode p1 p2 p3 | ||
1215 | ---- ------------ ----- ----- ----------------------------------- | ||
1216 | 0 ColumnName 0 0 one | ||
1217 | 1 ColumnName 1 0 two | ||
1218 | 2 Integer 0 0 | ||
1219 | 3 OpenRead 0 3 examp | ||
1220 | 4 VerifyCookie 0 256 | ||
1221 | 5 Integer 0 0 | ||
1222 | 6 OpenRead 1 4 examp_idx1 | ||
1223 | 7 Integer 50 0 50 | ||
1224 | 8 MakeKey 1 0 n | ||
1225 | 9 MemStore 0 0 | ||
1226 | 10 MoveTo 1 19 | ||
1227 | 11 MemLoad 0 0 | ||
1228 | 12 IdxGT 1 19 | ||
1229 | 13 IdxRecno 1 0 | ||
1230 | 14 MoveTo 0 0 | ||
1231 | 15 Column 0 0 | ||
1232 | 16 Column 0 1 | ||
1233 | 17 Callback 2 0 | ||
1234 | 18 Next 1 11 | ||
1235 | 19 Close 0 0 | ||
1236 | 20 Close 1 0 | ||
1237 | 21 Halt 0 0 | ||
1238 | } | ||
1239 | |||
1240 | puts { | ||
1241 | <p>The SELECT begins in a familiar fashion. First the column | ||
1242 | names are initialized and the table being queried is opened. | ||
1243 | Things become different beginning with instructions 5 and 6 where | ||
1244 | the index file is also opened. Instructions 7 and 8 make | ||
1245 | a key with the value of 50. | ||
1246 | The <a href="opcode.html#MemStore">MemStore</a> instruction at 9 stores | ||
1247 | the index key in VDBE memory location 0. The VDBE memory is used to | ||
1248 | avoid having to fetch a value from deep in the stack, which can be done, | ||
1249 | but makes the program harder to generate. The following instruction | ||
1250 | <a href="opcode.html#MoveTo">MoveTo</a> at address 10 pops the key off | ||
1251 | the stack and moves the index cursor to the first row of the index with | ||
1252 | that 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 | ||
1255 | with the key that was fetched by instruction 8. All of the index | ||
1256 | records with this key will be contiguous in the index table, so we walk | ||
1257 | through them and fetch the corresponding table key from the index. | ||
1258 | This table key is then used to move the cursor to that row in the table. | ||
1259 | The rest of the loop is the same as the loop for the non-indexed SELECT | ||
1260 | query.</p> | ||
1261 | |||
1262 | <p>The loop begins with the <a href="opcode.html#MemLoad">MemLoad</a> | ||
1263 | instruction at 11 which pushes a copy of the index key back onto the | ||
1264 | stack. The instruction <a href="opcode.html#IdxGT">IdxGT</a> at 12 | ||
1265 | compares the key to the key in the current index record pointed to by | ||
1266 | cursor P1. If the index key at the current cursor location is greater | ||
1267 | than 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 | ||
1270 | pushes onto the stack the table record number from the index. The | ||
1271 | following MoveTo pops it and moves the table cursor to that row. The | ||
1272 | next 3 instructions select the column data the same way as in the non- | ||
1273 | indexed case. The Column instructions fetch the column data and the | ||
1274 | callback function is invoked. The final Next instruction advances the | ||
1275 | index cursor, not the table cursor, to the next row, and then branches | ||
1276 | back 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, | ||
1279 | it is important that the index and table be kept consistent. | ||
1280 | Now that there is an index on the examp table, we will have | ||
1281 | to update that index whenever data is inserted, deleted, or | ||
1282 | changed in the examp table. Remember the first example above | ||
1283 | where we were able to insert a new row into the "examp" table using | ||
1284 | 12 VDBE instructions. Now that this table is indexed, 19 | ||
1285 | instructions are required. The SQL statement is this:</p> | ||
1286 | |||
1287 | <blockquote><pre> | ||
1288 | INSERT INTO examp VALUES('Hello, World!',99); | ||
1289 | </pre></blockquote> | ||
1290 | |||
1291 | <p>And the generated code looks like this:</p> | ||
1292 | } | ||
1293 | |||
1294 | Code { | ||
1295 | addr opcode p1 p2 p3 | ||
1296 | ---- ------------ ----- ----- ----------------------------------- | ||
1297 | 0 Transaction 1 0 | ||
1298 | 1 Transaction 0 0 | ||
1299 | 2 VerifyCookie 0 256 | ||
1300 | 3 Integer 0 0 | ||
1301 | 4 OpenWrite 0 3 examp | ||
1302 | 5 Integer 0 0 | ||
1303 | 6 OpenWrite 1 4 examp_idx1 | ||
1304 | 7 NewRecno 0 0 | ||
1305 | 8 String 0 0 Hello, World! | ||
1306 | 9 Integer 99 0 99 | ||
1307 | 10 Dup 2 1 | ||
1308 | 11 Dup 1 1 | ||
1309 | 12 MakeIdxKey 1 0 n | ||
1310 | 13 IdxPut 1 0 | ||
1311 | 14 MakeRecord 2 0 | ||
1312 | 15 PutIntKey 0 1 | ||
1313 | 16 Close 0 0 | ||
1314 | 17 Close 1 0 | ||
1315 | 18 Commit 0 0 | ||
1316 | 19 Halt 0 0 | ||
1317 | } | ||
1318 | |||
1319 | puts { | ||
1320 | <p>At this point, you should understand the VDBE well enough to | ||
1321 | figure out on your own how the above program works. So we will | ||
1322 | not 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 | ||
1327 | result. The result table consists of every possible combination | ||
1328 | of rows from the tables being joined. The easiest and most natural | ||
1329 | way to implement this is with nested loops.</p> | ||
1330 | |||
1331 | <p>Recall the query template discussed above where there was a | ||
1332 | single loop that searched through every record of the table. | ||
1333 | In a join we have basically the same thing except that there | ||
1334 | are nested loops. For example, to join two tables, the query | ||
1335 | template 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 | ||
1356 | are now dealing with an O(N<sup>2</sup>) loop. But it often works | ||
1357 | out that the WHERE clause can be factored into terms and that one or | ||
1358 | more of those terms will involve only columns in the first table. | ||
1359 | When this happens, we can factor part of the WHERE clause test out of | ||
1360 | the inner loop and gain a lot of efficiency. So a better template | ||
1361 | would 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 | ||
1386 | the search of either or the two loops.</p> | ||
1387 | |||
1388 | <p>SQLite always constructs the loops in the same order as the | ||
1389 | tables appear in the FROM clause of the SELECT statement. The | ||
1390 | left-most table becomes the outer loop and the right-most table | ||
1391 | becomes the inner loop. It is possible, in theory, to reorder | ||
1392 | the loops in some circumstances to speed the evaluation of the | ||
1393 | join. But SQLite does not attempt this optimization.</p> | ||
1394 | |||
1395 | <p>You can see how SQLite constructs nested loops in the following | ||
1396 | example:</p> | ||
1397 | |||
1398 | <blockquote><pre> | ||
1399 | CREATE TABLE examp2(three int, four int); | ||
1400 | SELECT * FROM examp, examp2 WHERE two<50 AND four==two; | ||
1401 | </pre></blockquote> | ||
1402 | } | ||
1403 | |||
1404 | Code { | ||
1405 | addr opcode p1 p2 p3 | ||
1406 | ---- ------------ ----- ----- ----------------------------------- | ||
1407 | 0 ColumnName 0 0 examp.one | ||
1408 | 1 ColumnName 1 0 examp.two | ||
1409 | 2 ColumnName 2 0 examp2.three | ||
1410 | 3 ColumnName 3 0 examp2.four | ||
1411 | 4 Integer 0 0 | ||
1412 | 5 OpenRead 0 3 examp | ||
1413 | 6 VerifyCookie 0 909 | ||
1414 | 7 Integer 0 0 | ||
1415 | 8 OpenRead 1 5 examp2 | ||
1416 | 9 Rewind 0 24 | ||
1417 | 10 Column 0 1 | ||
1418 | 11 Integer 50 0 50 | ||
1419 | 12 Ge 1 23 | ||
1420 | 13 Rewind 1 23 | ||
1421 | 14 Column 1 1 | ||
1422 | 15 Column 0 1 | ||
1423 | 16 Ne 1 22 | ||
1424 | 17 Column 0 0 | ||
1425 | 18 Column 0 1 | ||
1426 | 19 Column 1 0 | ||
1427 | 20 Column 1 1 | ||
1428 | 21 Callback 4 0 | ||
1429 | 22 Next 1 14 | ||
1430 | 23 Next 0 10 | ||
1431 | 24 Close 0 0 | ||
1432 | 25 Close 1 0 | ||
1433 | 26 Halt 0 0 | ||
1434 | } | ||
1435 | |||
1436 | puts { | ||
1437 | <p>The outer loop over table examp is implement by instructions | ||
1438 | 7 through 23. The inner loop is instructions 13 through 22. | ||
1439 | Notice that the "two<50" term of the WHERE expression involves | ||
1440 | only columns from the first table and can be factored out of | ||
1441 | the inner loop. SQLite does this and implements the "two<50" | ||
1442 | test in instructions 10 through 12. The "four==two" test is | ||
1443 | implement by instructions 14 through 16 in the inner loop.</p> | ||
1444 | |||
1445 | <p>SQLite does not impose any arbitrary limits on the tables in | ||
1446 | a 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 | ||
1451 | done in memory.</p> | ||
1452 | |||
1453 | <p>SQLite implements the ORDER BY clause using a special | ||
1454 | set of instructions to control an object called a sorter. In the | ||
1455 | inner-most loop of the query, where there would normally be | ||
1456 | a Callback instruction, instead a record is constructed that | ||
1457 | contains both callback parameters and a key. This record | ||
1458 | is added to the sorter (in a linked list). After the query loop | ||
1459 | finishes, the list of records is sorted and this list is walked. For | ||
1460 | each record on the list, the callback is invoked. Finally, the sorter | ||
1461 | is 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> | ||
1466 | SELECT * FROM examp ORDER BY one DESC, two; | ||
1467 | </pre></blockquote> | ||
1468 | } | ||
1469 | |||
1470 | Code { | ||
1471 | addr opcode p1 p2 p3 | ||
1472 | ---- ------------ ----- ----- ----------------------------------- | ||
1473 | 0 ColumnName 0 0 one | ||
1474 | 1 ColumnName 1 0 two | ||
1475 | 2 Integer 0 0 | ||
1476 | 3 OpenRead 0 3 examp | ||
1477 | 4 VerifyCookie 0 909 | ||
1478 | 5 Rewind 0 14 | ||
1479 | 6 Column 0 0 | ||
1480 | 7 Column 0 1 | ||
1481 | 8 SortMakeRec 2 0 | ||
1482 | 9 Column 0 0 | ||
1483 | 10 Column 0 1 | ||
1484 | 11 SortMakeKey 2 0 D+ | ||
1485 | 12 SortPut 0 0 | ||
1486 | 13 Next 0 6 | ||
1487 | 14 Close 0 0 | ||
1488 | 15 Sort 0 0 | ||
1489 | 16 SortNext 0 19 | ||
1490 | 17 SortCallback 2 0 | ||
1491 | 18 Goto 0 16 | ||
1492 | 19 SortReset 0 0 | ||
1493 | 20 Halt 0 0 | ||
1494 | } | ||
1495 | |||
1496 | puts { | ||
1497 | <p>There is only one sorter object, so there are no instructions to open | ||
1498 | or close it. It is opened automatically when needed, and it is closed | ||
1499 | when the VDBE program halts.</p> | ||
1500 | |||
1501 | <p>The query loop is built from instructions 5 through 13. Instructions | ||
1502 | 6 through 8 build a record that contains the azData[] values for a single | ||
1503 | invocation of the callback. A sort key is generated by instructions | ||
1504 | 9 through 11. Instruction 12 combines the invocation record and the | ||
1505 | sort 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 | ||
1508 | sort key is formed by prepending one character from P3 to each string | ||
1509 | and concatenating all the strings. The sort comparison function will | ||
1510 | look at this character to determine whether the sort order is | ||
1511 | ascending or descending, and whether to sort as a string or number. | ||
1512 | In this example, the first column should be sorted as a string | ||
1513 | in descending order so its prefix is "D" and the second column should | ||
1514 | sorted numerically in ascending order so its prefix is "+". Ascending | ||
1515 | string sorting uses "A", and descending numeric sorting uses "-".</p> | ||
1516 | |||
1517 | <p>After the query loop ends, the table being queried is closed at | ||
1518 | instruction 14. This is done early in order to allow other processes | ||
1519 | or threads to access that table, if desired. The list of records | ||
1520 | that was built up inside the query loop is sorted by the instruction | ||
1521 | at 15. Instructions 16 through 18 walk through the record list | ||
1522 | (which is now in sorted order) and invoke the callback once for | ||
1523 | each 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 | ||
1528 | data structure and instructions for controlling that data structure. | ||
1529 | The data structure is an unordered set of buckets, where each bucket | ||
1530 | has a key and one or more memory locations. Within the query | ||
1531 | loop, the GROUP BY clause is used to construct a key and the bucket | ||
1532 | with that key is brought into focus. A new bucket is created with | ||
1533 | the key if one did not previously exist. Once the bucket is in | ||
1534 | focus, the memory locations of the bucket are used to accumulate | ||
1535 | the values of the various aggregate functions. After the query | ||
1536 | loop terminates, each bucket is visited once to generate a | ||
1537 | single row of the results.</p> | ||
1538 | |||
1539 | <p>An example will help to clarify this concept. Consider the | ||
1540 | following query:</p> | ||
1541 | |||
1542 | <blockquote><pre> | ||
1543 | SELECT three, min(three+four)+avg(four) | ||
1544 | FROM examp2 | ||
1545 | GROUP BY three; | ||
1546 | </pre></blockquote> | ||
1547 | |||
1548 | |||
1549 | <p>The VDBE code generated for this query is as follows:</p> | ||
1550 | } | ||
1551 | |||
1552 | Code { | ||
1553 | addr opcode p1 p2 p3 | ||
1554 | ---- ------------ ----- ----- ----------------------------------- | ||
1555 | 0 ColumnName 0 0 three | ||
1556 | 1 ColumnName 1 0 min(three+four)+avg(four) | ||
1557 | 2 AggReset 0 3 | ||
1558 | 3 AggInit 0 1 ptr(0x7903a0) | ||
1559 | 4 AggInit 0 2 ptr(0x790700) | ||
1560 | 5 Integer 0 0 | ||
1561 | 6 OpenRead 0 5 examp2 | ||
1562 | 7 VerifyCookie 0 909 | ||
1563 | 8 Rewind 0 23 | ||
1564 | 9 Column 0 0 | ||
1565 | 10 MakeKey 1 0 n | ||
1566 | 11 AggFocus 0 14 | ||
1567 | 12 Column 0 0 | ||
1568 | 13 AggSet 0 0 | ||
1569 | 14 Column 0 0 | ||
1570 | 15 Column 0 1 | ||
1571 | 16 Add 0 0 | ||
1572 | 17 Integer 1 0 | ||
1573 | 18 AggFunc 0 1 ptr(0x7903a0) | ||
1574 | 19 Column 0 1 | ||
1575 | 20 Integer 2 0 | ||
1576 | 21 AggFunc 0 1 ptr(0x790700) | ||
1577 | 22 Next 0 9 | ||
1578 | 23 Close 0 0 | ||
1579 | 24 AggNext 0 31 | ||
1580 | 25 AggGet 0 0 | ||
1581 | 26 AggGet 0 1 | ||
1582 | 27 AggGet 0 2 | ||
1583 | 28 Add 0 0 | ||
1584 | 29 Callback 2 0 | ||
1585 | 30 Goto 0 24 | ||
1586 | 31 Noop 0 0 | ||
1587 | 32 Halt 0 0 | ||
1588 | } | ||
1589 | |||
1590 | puts { | ||
1591 | <p>The first instruction of interest is the | ||
1592 | <a href="opcode.html#AggReset">AggReset</a> at 2. | ||
1593 | The AggReset instruction initializes the set of buckets to be the | ||
1594 | empty set and specifies the number of memory slots available in each | ||
1595 | bucket as P2. In this example, each bucket will hold 3 memory slots. | ||
1596 | It is not obvious, but if you look closely at the rest of the program | ||
1597 | you 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. | ||
1608 | The aggregate key specified by the GROUP BY clause is computed | ||
1609 | by instructions 9 and 10. Instruction 11 causes the appropriate | ||
1610 | bucket to come into focus. If a bucket with the given key does | ||
1611 | not already exists, a new bucket is created and control falls | ||
1612 | through to instructions 12 and 13 which initialize the bucket. | ||
1613 | If the bucket does already exist, then a jump is made to instruction | ||
1614 | 14. The values of aggregate functions are updated by the instructions | ||
1615 | between 11 and 21. Instructions 14 through 18 update memory | ||
1616 | slot 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 | ||
1620 | instruction 23 so that its lock will be released and it can be | ||
1621 | used by other threads or processes. The next step is to loop | ||
1622 | over all aggregate buckets and output one row of the result for | ||
1623 | each bucket. This is done by the loop at instructions 24 | ||
1624 | through 30. The AggNext instruction at 24 brings the next bucket | ||
1625 | into focus, or jumps to the end of the loop if all buckets have | ||
1626 | been examined already. The 3 columns of the result are fetched from | ||
1627 | the aggregator bucket in order at instructions 25 through 27. | ||
1628 | Finally, the callback is invoked at instruction 29.</p> | ||
1629 | |||
1630 | <p>In summary then, any query with aggregate functions is implemented | ||
1631 | by two loops. The first loop scans the input table and computes | ||
1632 | aggregate information into buckets and the second loop scans through | ||
1633 | all the buckets to compute the final result.</p> | ||
1634 | |||
1635 | <p>The realization that an aggregate query is really two consequtive | ||
1636 | loops makes it much easier to understand the difference between | ||
1637 | a WHERE clause and a HAVING clause in SQL query statement. The | ||
1638 | WHERE clause is a restriction on the first loop and the HAVING | ||
1639 | clause is a restriction on the second loop. You can see this | ||
1640 | by adding both a WHERE and a HAVING clause to our example query:</p> | ||
1641 | |||
1642 | |||
1643 | <blockquote><pre> | ||
1644 | SELECT three, min(three+four)+avg(four) | ||
1645 | FROM examp2 | ||
1646 | WHERE three>four | ||
1647 | GROUP BY three | ||
1648 | HAVING avg(four)<10; | ||
1649 | </pre></blockquote> | ||
1650 | } | ||
1651 | |||
1652 | Code { | ||
1653 | addr opcode p1 p2 p3 | ||
1654 | ---- ------------ ----- ----- ----------------------------------- | ||
1655 | 0 ColumnName 0 0 three | ||
1656 | 1 ColumnName 1 0 min(three+four)+avg(four) | ||
1657 | 2 AggReset 0 3 | ||
1658 | 3 AggInit 0 1 ptr(0x7903a0) | ||
1659 | 4 AggInit 0 2 ptr(0x790700) | ||
1660 | 5 Integer 0 0 | ||
1661 | 6 OpenRead 0 5 examp2 | ||
1662 | 7 VerifyCookie 0 909 | ||
1663 | 8 Rewind 0 26 | ||
1664 | 9 Column 0 0 | ||
1665 | 10 Column 0 1 | ||
1666 | 11 Le 1 25 | ||
1667 | 12 Column 0 0 | ||
1668 | 13 MakeKey 1 0 n | ||
1669 | 14 AggFocus 0 17 | ||
1670 | 15 Column 0 0 | ||
1671 | 16 AggSet 0 0 | ||
1672 | 17 Column 0 0 | ||
1673 | 18 Column 0 1 | ||
1674 | 19 Add 0 0 | ||
1675 | 20 Integer 1 0 | ||
1676 | 21 AggFunc 0 1 ptr(0x7903a0) | ||
1677 | 22 Column 0 1 | ||
1678 | 23 Integer 2 0 | ||
1679 | 24 AggFunc 0 1 ptr(0x790700) | ||
1680 | 25 Next 0 9 | ||
1681 | 26 Close 0 0 | ||
1682 | 27 AggNext 0 37 | ||
1683 | 28 AggGet 0 2 | ||
1684 | 29 Integer 10 0 10 | ||
1685 | 30 Ge 1 27 | ||
1686 | 31 AggGet 0 0 | ||
1687 | 32 AggGet 0 1 | ||
1688 | 33 AggGet 0 2 | ||
1689 | 34 Add 0 0 | ||
1690 | 35 Callback 2 0 | ||
1691 | 36 Goto 0 27 | ||
1692 | 37 Noop 0 0 | ||
1693 | 38 Halt 0 0 | ||
1694 | } | ||
1695 | |||
1696 | puts { | ||
1697 | <p>The code generated in this last example is the same as the | ||
1698 | previous except for the addition of two conditional jumps used | ||
1699 | to implement the extra WHERE and HAVING clauses. The WHERE | ||
1700 | clause is implemented by instructions 9 through 11 in the query | ||
1701 | loop. The HAVING clause is implemented by instruction 28 through | ||
1702 | 30 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 | ||
1707 | support nested queries. And, in fact, two different kinds of nesting | ||
1708 | are supported. Any SELECT statement that returns a single-row, single-column | ||
1709 | result can be used as a term in an expression of another SELECT statement. | ||
1710 | And, a SELECT statement that returns a single-column, multi-row result | ||
1711 | can be used as the right-hand operand of the IN and NOT IN operators. | ||
1712 | We will begin this section with an example of the first kind of nesting, | ||
1713 | where a single-row, single-column SELECT is used as a term in an expression | ||
1714 | of another SELECT. Here is our example:</p> | ||
1715 | |||
1716 | <blockquote><pre> | ||
1717 | SELECT * FROM examp | ||
1718 | WHERE 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 | ||
1724 | cell. SQLite then substitutes the value of this private memory | ||
1725 | cell for the inner SELECT when it evaluates the outer SELECT. | ||
1726 | The code looks like this:</p> | ||
1727 | } | ||
1728 | |||
1729 | Code { | ||
1730 | addr opcode p1 p2 p3 | ||
1731 | ---- ------------ ----- ----- ----------------------------------- | ||
1732 | 0 String 0 0 | ||
1733 | 1 MemStore 0 1 | ||
1734 | 2 Integer 0 0 | ||
1735 | 3 OpenRead 1 5 examp2 | ||
1736 | 4 VerifyCookie 0 909 | ||
1737 | 5 Rewind 1 13 | ||
1738 | 6 Column 1 1 | ||
1739 | 7 Integer 5 0 5 | ||
1740 | 8 Ne 1 12 | ||
1741 | 9 Column 1 0 | ||
1742 | 10 MemStore 0 1 | ||
1743 | 11 Goto 0 13 | ||
1744 | 12 Next 1 6 | ||
1745 | 13 Close 1 0 | ||
1746 | 14 ColumnName 0 0 one | ||
1747 | 15 ColumnName 1 0 two | ||
1748 | 16 Integer 0 0 | ||
1749 | 17 OpenRead 0 3 examp | ||
1750 | 18 Rewind 0 26 | ||
1751 | 19 Column 0 1 | ||
1752 | 20 MemLoad 0 0 | ||
1753 | 21 Eq 1 25 | ||
1754 | 22 Column 0 0 | ||
1755 | 23 Column 0 1 | ||
1756 | 24 Callback 2 0 | ||
1757 | 25 Next 0 19 | ||
1758 | 26 Close 0 0 | ||
1759 | 27 Halt 0 0 | ||
1760 | } | ||
1761 | |||
1762 | puts { | ||
1763 | <p>The private memory cell is initialized to NULL by the first | ||
1764 | two instructions. Instructions 2 through 13 implement the inner | ||
1765 | SELECT statement against the examp2 table. Notice that instead of | ||
1766 | sending the result to a callback or storing the result on a sorter, | ||
1767 | the result of the query is pushed into the memory cell by instruction | ||
1768 | 10 and the loop is abandoned by the jump at instruction 11. | ||
1769 | The jump at instruction at 11 is vestigial and never executes.</p> | ||
1770 | |||
1771 | <p>The outer SELECT is implemented by instructions 14 through 25. | ||
1772 | In particular, the WHERE clause that contains the nested select | ||
1773 | is implemented by instructions 19 through 21. You can see that | ||
1774 | the result of the inner select is loaded onto the stack by instruction | ||
1775 | 20 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 | ||
1778 | cell can be used, as shown in the previous | ||
1779 | example. But when the result of a sub-select is a vector, such | ||
1780 | as when the sub-select is the right-hand operand of IN or NOT IN, | ||
1781 | a different approach is needed. In this case, | ||
1782 | the result of the sub-select is | ||
1783 | stored in a transient table and the contents of that table | ||
1784 | are tested using the Found or NotFound operators. Consider this | ||
1785 | example:</p> | ||
1786 | |||
1787 | <blockquote><pre> | ||
1788 | SELECT * FROM examp | ||
1789 | WHERE 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 | |||
1795 | Code { | ||
1796 | addr opcode p1 p2 p3 | ||
1797 | ---- ------------ ----- ----- ----------------------------------- | ||
1798 | 0 OpenTemp 1 1 | ||
1799 | 1 Integer 0 0 | ||
1800 | 2 OpenRead 2 5 examp2 | ||
1801 | 3 VerifyCookie 0 909 | ||
1802 | 4 Rewind 2 10 | ||
1803 | 5 Column 2 0 | ||
1804 | 6 IsNull -1 9 | ||
1805 | 7 String 0 0 | ||
1806 | 8 PutStrKey 1 0 | ||
1807 | 9 Next 2 5 | ||
1808 | 10 Close 2 0 | ||
1809 | 11 ColumnName 0 0 one | ||
1810 | 12 ColumnName 1 0 two | ||
1811 | 13 Integer 0 0 | ||
1812 | 14 OpenRead 0 3 examp | ||
1813 | 15 Rewind 0 25 | ||
1814 | 16 Column 0 1 | ||
1815 | 17 NotNull -1 20 | ||
1816 | 18 Pop 1 0 | ||
1817 | 19 Goto 0 24 | ||
1818 | 20 NotFound 1 24 | ||
1819 | 21 Column 0 0 | ||
1820 | 22 Column 0 1 | ||
1821 | 23 Callback 2 0 | ||
1822 | 24 Next 0 16 | ||
1823 | 25 Close 0 0 | ||
1824 | 26 Halt 0 0 | ||
1825 | } | ||
1826 | |||
1827 | puts { | ||
1828 | <p>The transient table in which the results of the inner SELECT are | ||
1829 | stored is created by the <a href="opcode.html#OpenTemp">OpenTemp</a> | ||
1830 | instruction at 0. This opcode is used for tables that exist for the | ||
1831 | duration of a single SQL statement only. The transient cursor is always | ||
1832 | opened read/write even if the main database is read-only. The transient | ||
1833 | table is deleted automatically when the cursor is closed. The P2 value | ||
1834 | of 1 means the cursor points to a BTree index, which has no data but can | ||
1835 | have an arbitrary key.</p> | ||
1836 | |||
1837 | <p>The inner SELECT statement is implemented by instructions 1 through 10. | ||
1838 | All this code does is make an entry in the temporary table for each | ||
1839 | row of the examp2 table with a non-NULL value for the "three" column. | ||
1840 | The key for each temporary table entry is the "three" column of examp2 | ||
1841 | and 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 | ||
1844 | particular, the WHERE clause containing the IN operator is implemented | ||
1845 | by instructions at 16, 17, and 20. Instruction 16 pushes the value of | ||
1846 | the "two" column for the current row onto the stack and instruction 17 | ||
1847 | checks to see that it is non-NULL. If this is successful, execution | ||
1848 | jumps to 20, where it tests to see if top of the stack matches any key | ||
1849 | in the temporary table. The rest of the code is the same as what has | ||
1850 | been 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 | ||
1855 | peers using operators UNION, UNION ALL, INTERSECT, and EXCEPT. These | ||
1856 | compound select statements are implemented using transient tables. | ||
1857 | The implementation is slightly different for each operator, but the | ||
1858 | basic ideas are the same. For an example we will use the EXCEPT | ||
1859 | operator.</p> | ||
1860 | |||
1861 | <blockquote><pre> | ||
1862 | SELECT two FROM examp | ||
1863 | EXCEPT | ||
1864 | SELECT four FROM examp2; | ||
1865 | </pre></blockquote> | ||
1866 | |||
1867 | <p>The result of this last example should be every unique value | ||
1868 | of the "two" column in the examp table, except any value that is | ||
1869 | in the "four" column of examp2 is removed. The code to implement | ||
1870 | this query is as follows:</p> | ||
1871 | } | ||
1872 | |||
1873 | Code { | ||
1874 | addr opcode p1 p2 p3 | ||
1875 | ---- ------------ ----- ----- ----------------------------------- | ||
1876 | 0 OpenTemp 0 1 | ||
1877 | 1 KeyAsData 0 1 | ||
1878 | 2 Integer 0 0 | ||
1879 | 3 OpenRead 1 3 examp | ||
1880 | 4 VerifyCookie 0 909 | ||
1881 | 5 Rewind 1 11 | ||
1882 | 6 Column 1 1 | ||
1883 | 7 MakeRecord 1 0 | ||
1884 | 8 String 0 0 | ||
1885 | 9 PutStrKey 0 0 | ||
1886 | 10 Next 1 6 | ||
1887 | 11 Close 1 0 | ||
1888 | 12 Integer 0 0 | ||
1889 | 13 OpenRead 2 5 examp2 | ||
1890 | 14 Rewind 2 20 | ||
1891 | 15 Column 2 1 | ||
1892 | 16 MakeRecord 1 0 | ||
1893 | 17 NotFound 0 19 | ||
1894 | 18 Delete 0 0 | ||
1895 | 19 Next 2 15 | ||
1896 | 20 Close 2 0 | ||
1897 | 21 ColumnName 0 0 four | ||
1898 | 22 Rewind 0 26 | ||
1899 | 23 Column 0 0 | ||
1900 | 24 Callback 1 0 | ||
1901 | 25 Next 0 23 | ||
1902 | 26 Close 0 0 | ||
1903 | 27 Halt 0 0 | ||
1904 | } | ||
1905 | |||
1906 | puts { | ||
1907 | <p>The transient table in which the result is built is created by | ||
1908 | instruction 0. Three loops then follow. The loop at instructions | ||
1909 | 5 through 10 implements the first SELECT statement. The second | ||
1910 | SELECT statement is implemented by the loop at instructions 14 through | ||
1911 | 19. Finally, a loop at instructions 22 through 25 reads the transient | ||
1912 | table 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, | ||
1915 | the Column instruction extracts the value of a column from a larger | ||
1916 | record in the data of an SQLite file entry. Instruction 1 sets a flag on | ||
1917 | the transient table so that Column will instead treat the key of the | ||
1918 | SQLite file entry as if it were data and extract column information from | ||
1919 | the key.</p> | ||
1920 | |||
1921 | <p>Here is what is going to happen: The first SELECT statement | ||
1922 | will construct rows of the result and save each row as the key of | ||
1923 | an entry in the transient table. The data for each entry in the | ||
1924 | transient table is a never used so we fill it in with an empty string. | ||
1925 | The second SELECT statement also constructs rows, but the rows | ||
1926 | constructed by the second SELECT are removed from the transient table. | ||
1927 | That is why we want the rows to be stored in the key of the SQLite file | ||
1928 | instead 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 | ||
1931 | SELECT is implemented by the loop at instructions 5 through 10. | ||
1932 | Instruction 5 intializes the loop by rewinding its cursor. | ||
1933 | Instruction 6 extracts the value of the "two" column from "examp" | ||
1934 | and instruction 7 converts this into a row. Instruction 8 pushes | ||
1935 | an empty string onto the stack. Finally, instruction 9 writes the | ||
1936 | row into the temporary table. But remember, the PutStrKey opcode uses | ||
1937 | the top of the stack as the record data and the next on stack as the | ||
1938 | key. For an INSERT statement, the row generated by the | ||
1939 | MakeRecord opcode is the record data and the record key is an integer | ||
1940 | created by the NewRecno opcode. But here the roles are reversed and | ||
1941 | the row created by MakeRecord is the record key and the record data is | ||
1942 | just an empty string.</p> | ||
1943 | |||
1944 | <p>The second SELECT is implemented by instructions 14 through 19. | ||
1945 | Instruction 14 intializes the loop by rewinding its cursor. | ||
1946 | A new result row is created from the "four" column of table "examp2" | ||
1947 | by instructions 15 and 16. But instead of using PutStrKey to write this | ||
1948 | new row into the temporary table, we instead call Delete to remove | ||
1949 | it from the temporary table if it exists.</p> | ||
1950 | |||
1951 | <p>The result of the compound select is sent to the callback routine | ||
1952 | by the loop at instructions 22 through 25. There is nothing new | ||
1953 | or remarkable about this loop, except for the fact that the Column | ||
1954 | instruction at 23 will be extracting a column out of the record key | ||
1955 | rather than the record data.</p> | ||
1956 | |||
1957 | <h2>Summary</h2> | ||
1958 | |||
1959 | <p>This article has reviewed all of the major techniques used by | ||
1960 | SQLite's VDBE to implement SQL statements. What has not been shown | ||
1961 | is that most of these techniques can be used in combination to | ||
1962 | generate code for an appropriately complex query statement. For | ||
1963 | example, we have shown how sorting is accomplished on a simple query | ||
1964 | and we have shown how to implement a compound query. But we did | ||
1965 | not give an example of sorting in a compound query. This is because | ||
1966 | sorting a compound query does not introduce any new concepts: it | ||
1967 | merely combines two previous ideas (sorting and compounding) | ||
1968 | in the same VDBE program.</p> | ||
1969 | |||
1970 | <p>For additional information on how the SQLite library | ||
1971 | functions, the reader is directed to look at the SQLite source | ||
1972 | code directly. If you understand the material in this article, | ||
1973 | you should not have much difficulty in following the sources. | ||
1974 | Serious students of the internals of SQLite will probably | ||
1975 | also what to make a careful study of the VDBE opcodes | ||
1976 | as documented <a href="opcode.html">here</a>. Most of the | ||
1977 | opcode documentation is extracted from comments in the source | ||
1978 | code using a script so you can also get information about the | ||
1979 | various opcodes directly from the <b>vdbe.c</b> source file. | ||
1980 | If you have successfully read this far, you should have little | ||
1981 | difficulty understanding the rest.</p> | ||
1982 | |||
1983 | <p>If you find errors in either the documentation or the code, | ||
1984 | feel 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 | ||
1986 | suggestions are always welcomed.</p> | ||
1987 | } | ||
1988 | footer $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 | ||
2 | source common.tcl | ||
3 | header {SQLite Version 3 Overview} | ||
4 | puts { | ||
5 | <h2>SQLite Version 3 Overview</h2> | ||
6 | |||
7 | <p> | ||
8 | SQLite 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> | ||
21 | This document is a quick introduction to the changes for SQLite 3.0 | ||
22 | for users who are already familiar with SQLite version 2.8. | ||
23 | </p> | ||
24 | |||
25 | <h3>Naming Changes</h3> | ||
26 | |||
27 | <p> | ||
28 | SQLite version 2.8 will continue to be supported with bug fixes | ||
29 | for the foreseeable future. In order to allow SQLite version 2.8 | ||
30 | and SQLite version 3.0 to peacefully coexist, the names of key files | ||
31 | and APIs in SQLite version 3.0 have been changed to include the | ||
32 | character "3". For example, the include file used by C programs | ||
33 | has been changed from "sqlite.h" to "sqlite3.h". And the name of | ||
34 | the shell program used to interact with databases has been changed | ||
35 | from "sqlite.exe" to "sqlite3.exe". With these changes, it is possible | ||
36 | to have both SQLite 2.8 and SQLite 3.0 installed on the same system at | ||
37 | the same time. And it is possible for the same C program to link | ||
38 | against both SQLite 2.8 and SQLite 3.0 at the same time and to use | ||
39 | both libraries at the same time. | ||
40 | </p> | ||
41 | |||
42 | <h3>New File Format</h3> | ||
43 | |||
44 | <p> | ||
45 | The format used by SQLite database files has been completely revised. | ||
46 | The old version 2.1 format and the new 3.0 format are incompatible with | ||
47 | one another. Version 2.8 of SQLite will not read a version 3.0 database | ||
48 | files and version 3.0 of SQLite will not read a version 2.8 database file. | ||
49 | </p> | ||
50 | |||
51 | <p> | ||
52 | To convert an SQLite 2.8 database into an SQLite 3.0 database, have | ||
53 | ready the command-line shells for both version 2.8 and 3.0. Then | ||
54 | enter a command like the following: | ||
55 | </p> | ||
56 | |||
57 | <blockquote><pre> | ||
58 | sqlite OLD.DB .dump | sqlite3 NEW.DB | ||
59 | </pre></blockquote> | ||
60 | |||
61 | <p> | ||
62 | The new database file format uses B+trees for tables. In a B+tree, all | ||
63 | data is stored in the leaves of the tree instead of in both the leaves and | ||
64 | the intermediate branch nodes. The use of B+trees for tables allows for | ||
65 | better scalability and the storage of larger data fields without the use of | ||
66 | overflow pages. Traditional B-trees are still used for indices.</p> | ||
67 | |||
68 | <p> | ||
69 | The new file format also supports variable pages sizes between 512 and | ||
70 | 32768 bytes. The size of a page is stored in the file header so the | ||
71 | same library can read databases with different pages sizes, in theory, | ||
72 | though this feature has not yet been implemented in practice. | ||
73 | </p> | ||
74 | |||
75 | <p> | ||
76 | The new file format omits unused fields from its disk images. For example, | ||
77 | indices use only the key part of a B-tree record and not the data. So | ||
78 | for indices, the field that records the length of the data is omitted. | ||
79 | Integer values such as the length of key and data are stored using | ||
80 | a variable-length encoding so that only one or two bytes are required to | ||
81 | store the most common cases but up to 64-bits of information can be encoded | ||
82 | if needed. | ||
83 | Integer and floating point data is stored on the disk in binary rather | ||
84 | than being converted into ASCII as in SQLite version 2.8. | ||
85 | These changes taken together result in database files that are typically | ||
86 | 25% to 35% smaller than the equivalent files in SQLite version 2.8. | ||
87 | </p> | ||
88 | |||
89 | <p> | ||
90 | Details of the low-level B-tree format used in SQLite version 3.0 can | ||
91 | be found in header comments to the | ||
92 | <a href="http://www.sqlite.org/cvstrac/getfile/sqlite/src/btree.c">btree.c</a> | ||
93 | source file. | ||
94 | </p> | ||
95 | |||
96 | <h3>Manifest Typing and BLOB Support</h3> | ||
97 | |||
98 | <p> | ||
99 | SQLite version 2.8 will deal with data in various formats internally, | ||
100 | but when writing to the disk or interacting through its API, SQLite 2.8 | ||
101 | always converts data into ASCII text. SQLite 3.0, in contrast, exposes | ||
102 | its internal data representations to the user and stores binary representations | ||
103 | to disk when appropriate. The exposing of non-ASCII representations was | ||
104 | added in order to support BLOBs. | ||
105 | </p> | ||
106 | |||
107 | <p> | ||
108 | SQLite version 2.8 had the feature that any type of data could be stored | ||
109 | in any table column regardless of the declared type of that column. This | ||
110 | feature is retained in version 3.0, though in a slightly modified form. | ||
111 | Each table column will store any type of data, though columns have an | ||
112 | affinity for the format of data defined by their declared datatype. | ||
113 | When data is inserted into a column, that column will make at attempt | ||
114 | to convert the data format into the columns declared type. All SQL | ||
115 | database engines do this. The difference is that SQLite 3.0 will | ||
116 | still store the data even if a format conversion is not possible. | ||
117 | </p> | ||
118 | |||
119 | <p> | ||
120 | For example, if you have a table column declared to be of type "INTEGER" | ||
121 | and you try to insert a string, the column will look at the text string | ||
122 | and see if it looks like a number. If the string does look like a number | ||
123 | it is converted into a number and into an integer if the number does not | ||
124 | have a fractional part, and stored that way. But if the string is not | ||
125 | a well-formed number it is still stored as a string. A column with a | ||
126 | type of "TEXT" tries to convert numbers into an ASCII-Text representation | ||
127 | before storing them. But BLOBs are stored in TEXT columns as BLOBs because | ||
128 | you cannot in general convert a BLOB into text. | ||
129 | </p> | ||
130 | |||
131 | <p> | ||
132 | In most other SQL database engines the datatype is associated with | ||
133 | the table column that holds the data - with the data container. | ||
134 | In SQLite 3.0, the datatype is associated with the data itself, not | ||
135 | with 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> | ||
138 | calls this property "Manifest Typing". | ||
139 | Other writers have other definitions for the term "manifest typing", | ||
140 | so beware of confusion. But by whatever name, that is the datatype | ||
141 | model supported by SQLite 3.0. | ||
142 | </p> | ||
143 | |||
144 | <p> | ||
145 | Additional information about datatypes in SQLite version 3.0 is | ||
146 | available | ||
147 | <a href="datatype3.html">separately</a>. | ||
148 | </p> | ||
149 | |||
150 | <h3>Support for UTF-8 and UTF-16</h3> | ||
151 | |||
152 | <p> | ||
153 | The new API for SQLite 3.0 contains routines that accept text as | ||
154 | both UTF-8 and UTF-16 in the native byte order of the host machine. | ||
155 | Each database file manages text as either UTF-8, UTF-16BE (big-endian), | ||
156 | or UTF-16LE (little-endian). Internally and in the disk file, the | ||
157 | same text representation is used everywhere. If the text representation | ||
158 | specified by the database file (in the file header) does not match | ||
159 | the text representation required by the interface routines, then text | ||
160 | is converted on-the-fly. | ||
161 | Constantly converting text from one representation to another can be | ||
162 | computationally expensive, so it is suggested that programmers choose a | ||
163 | single representation and stick with it throughout their application. | ||
164 | </p> | ||
165 | |||
166 | <p> | ||
167 | In the current implementation of SQLite, the SQL parser only works | ||
168 | with UTF-8 text. So if you supply UTF-16 text it will be converted. | ||
169 | This is just an implementation issue and there is nothing to prevent | ||
170 | future versions of SQLite from parsing UTF-16 encoded SQL natively. | ||
171 | </p> | ||
172 | |||
173 | <p> | ||
174 | When creating new user-defined SQL functions and collating sequences, | ||
175 | each function or collating sequence can specify it if works with | ||
176 | UTF-8, UTF-16be, or UTF-16le. Separate implementations can be registered | ||
177 | for each encoding. If an SQL function or collating sequences is required | ||
178 | but a version for the current text encoding is not available, then | ||
179 | the text is automatically converted. As before, this conversion takes | ||
180 | computation time, so programmers are advised to pick a single | ||
181 | encoding and stick with it in order to minimize the amount of unnecessary | ||
182 | format juggling. | ||
183 | </p> | ||
184 | |||
185 | <p> | ||
186 | SQLite is not particular about the text it receives and is more than | ||
187 | happy to process text strings that are not normalized or even | ||
188 | well-formed UTF-8 or UTF-16. Thus, programmers who want to store | ||
189 | IS08859 data can do so using the UTF-8 interfaces. As long as no | ||
190 | attempts are made to use a UTF-16 collating sequence or SQL function, | ||
191 | the 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> | ||
197 | A collating sequence is just a defined order for text. When SQLite 3.0 | ||
198 | sorts (or uses a comparison operator like "<" or ">=") the sort order | ||
199 | is 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> | ||
210 | Collating sequences are used for comparing two text strings. | ||
211 | The collating sequence does not change the ordering of NULLs, numbers, | ||
212 | or BLOBs, only text. | ||
213 | </p> | ||
214 | |||
215 | <p> | ||
216 | A collating sequence is implemented as a function that takes the | ||
217 | two strings being compared as inputs and returns negative, zero, or | ||
218 | positive if the first string is less than, equal to, or greater than | ||
219 | the second. | ||
220 | SQLite 3.0 comes with a single built-in collating sequence named "BINARY" | ||
221 | which is implemented using the memcmp() routine from the standard C library. | ||
222 | The BINARY collating sequence works well for English text. For other | ||
223 | languages or locales, alternative collating sequences may be preferred. | ||
224 | </p> | ||
225 | |||
226 | <p> | ||
227 | The decision of which collating sequence to use is controlled by the | ||
228 | COLLATE clause in SQL. A COLLATE clause can occur on a table definition, | ||
229 | to define a default collating sequence to a table column, or on field | ||
230 | of an index, or in the ORDER BY clause of a SELECT statement. | ||
231 | Planned enhancements to SQLite are to include standard CAST() syntax | ||
232 | to allow the collating sequence of an expression to be defined. | ||
233 | </p> | ||
234 | |||
235 | <h3>64-bit ROWIDs</h3> | ||
236 | |||
237 | <p> | ||
238 | Every row of a table has a unique rowid. | ||
239 | If the table defines a column with the type "INTEGER PRIMARY KEY" then that | ||
240 | column becomes an alias for the rowid. But with or without an INTEGER PRIMARY | ||
241 | KEY column, every row still has a rowid. | ||
242 | </p> | ||
243 | |||
244 | <p> | ||
245 | In SQLite version 3.0, the rowid is a 64-bit signed integer. | ||
246 | This is an expansion of SQLite version 2.8 which only permitted | ||
247 | rowids of 32-bits. | ||
248 | </p> | ||
249 | |||
250 | <p> | ||
251 | To minimize storage space, the 64-bit rowid is stored as a variable length | ||
252 | integer. Rowids between 0 and 127 use only a single byte. | ||
253 | Rowids between 0 and 16383 use just 2 bytes. Up to 2097152 uses three | ||
254 | bytes. And so forth. Negative rowids are allowed but they always use | ||
255 | nine bytes of storage and so their use is discouraged. When rowids | ||
256 | are generated automatically by SQLite, they will always be non-negative. | ||
257 | </p> | ||
258 | |||
259 | <h3>Improved Concurrency</h3> | ||
260 | |||
261 | <p> | ||
262 | SQLite version 2.8 allowed multiple simultaneous readers or a single | ||
263 | writer but not both. SQLite version 3.0 allows one process to begin | ||
264 | writing the database while other processes continue to read. The | ||
265 | writer must still obtain an exclusive lock on the database for a brief | ||
266 | interval in order to commit its changes, but the exclusive lock is no | ||
267 | longer required for the entire write operation. | ||
268 | A <a href="lockingv3.html">more detailed report</a> on the locking | ||
269 | behavior of SQLite version 3.0 is available separately. | ||
270 | </p> | ||
271 | |||
272 | <p> | ||
273 | A limited form of table-level locking is now also available in SQLite. | ||
274 | If each table is stored in a separate database file, those separate | ||
275 | files can be attached to the main database (using the ATTACH command) | ||
276 | and the combined databases will function as one. But locks will only | ||
277 | be acquired on individual files as needed. So if you redefine "database" | ||
278 | to mean two or more database files, then it is entirely possible for | ||
279 | two processes to be writing to the same database at the same time. | ||
280 | To further support this capability, commits of transactions involving | ||
281 | two or more ATTACHed database are now atomic. | ||
282 | </p> | ||
283 | |||
284 | <h3>Credits</h3> | ||
285 | |||
286 | <p> | ||
287 | SQLite version 3.0 is made possible in part by AOL developers | ||
288 | supporting and embracing great Open-Source Software. | ||
289 | </p> | ||
290 | |||
291 | |||
292 | } | ||
293 | footer {$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 | # | ||
4 | set rcsid {$Id: whentouse.tcl,v 1.7 2007/04/14 12:04:39 drh Exp $} | ||
5 | source common.tcl | ||
6 | header {Appropriate Uses For SQLite} | ||
7 | |||
8 | puts { | ||
9 | <p> | ||
10 | SQLite is different from most other SQL database engines in that its | ||
11 | primary 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> | ||
22 | Many people like SQLite because it is small and fast. But those | ||
23 | qualities are just happy accidents. | ||
24 | Users also find that SQLite is very reliable. Reliability is | ||
25 | a consequence of simplicity. With less complication, there is | ||
26 | less to go wrong. So, yes, SQLite is small, fast, and reliable, | ||
27 | but first and foremost, SQLite strives to be simple. | ||
28 | </p> | ||
29 | |||
30 | <p> | ||
31 | Simplicity in a database engine can be either a strength or a | ||
32 | weakness, depending on what you are trying to do. In order to | ||
33 | achieve simplicity, SQLite has had to sacrifice other characteristics | ||
34 | that some people find useful, such as high concurrency, fine-grained | ||
35 | access control, a rich set of built-in functions, stored procedures, | ||
36 | esoteric SQL language features, XML and/or Java extensions, | ||
37 | tera- or peta-byte scalability, and so forth. If you need some of these | ||
38 | features and do not mind the added complexity that they | ||
39 | bring, then SQLite is probably not the database for you. | ||
40 | SQLite is not intended to be an enterprise database engine. It | ||
41 | not designed to compete with Oracle or PostgreSQL. | ||
42 | </p> | ||
43 | |||
44 | <p> | ||
45 | The basic rule of thumb for when it is appropriate to use SQLite is | ||
46 | this: Use SQLite in situations where simplicity of administration, | ||
47 | implementation, and maintenance are more important than the countless | ||
48 | complex features that enterprise database engines provide. | ||
49 | As it turns out, situations where simplicity is the better choice | ||
50 | are 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 | ||
59 | medium traffic websites (which is to say, 99.9% of all websites). | ||
60 | The amount of web traffic that SQLite can handle depends, of course, | ||
61 | on how heavily the website uses its database. Generally | ||
62 | speaking, any site that gets fewer than a 100000 hits/day should work | ||
63 | fine with SQLite. | ||
64 | The 100000 hits/day figure is a conservative estimate, not a | ||
65 | hard upper bound. | ||
66 | SQLite has been demonstrated to work with 10 times that amount | ||
67 | of 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, | ||
73 | SQLite is a good choice for devices or services that must work | ||
74 | unattended and without human support. SQLite is a good fit for | ||
75 | use in cellphones, PDAs, set-top boxes, and/or appliances. It also | ||
76 | works 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> | ||
83 | SQLite has been used with great success as the on-disk file format | ||
84 | for desktop applications such as financial analysis tools, CAD | ||
85 | packages, record keeping programs, and so forth. The traditional | ||
86 | File/Open operation does an sqlite3_open() and executes a | ||
87 | BEGIN TRANSACTION to get exclusive access to the content. File/Save | ||
88 | does a COMMIT followed by another BEGIN TRANSACTION. The use | ||
89 | of transactions guarantees that updates to the application file are atomic, | ||
90 | durable, isolated, and consistent. | ||
91 | </p> | ||
92 | |||
93 | <p> | ||
94 | Temporary triggers can be added to the database to record all | ||
95 | changes into a (temporary) undo/redo log table. These changes can then | ||
96 | be played back when the user presses the Undo and Redo buttons. Using | ||
97 | this technique, a unlimited depth undo/redo implementation can be written | ||
98 | in 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 | ||
105 | manage files of data in home-grown formats. SQLite works | ||
106 | particularly well as a | ||
107 | replacement 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> | ||
113 | For programs that have a lot of data that must be sifted and sorted | ||
114 | in diverse ways, it is often easier and quicker to load the data into | ||
115 | an in-memory SQLite database and use queries with joins and ORDER BY | ||
116 | clauses to extract the data in the form and order needed rather than | ||
117 | to try to code the same operations manually. | ||
118 | Using an SQL database internally in this way also gives the program | ||
119 | greater flexibility since new columns and indices can be added without | ||
120 | having to recode every query. | ||
121 | </p> | ||
122 | </li> | ||
123 | |||
124 | <li><p><b>Command-line dataset analysis tool</b></p> | ||
125 | |||
126 | <p> | ||
127 | Experienced SQL users can employ | ||
128 | the command-line <b>sqlite</b> program to analyze miscellaneous | ||
129 | datasets. Raw data can be imported from CSV files, then that | ||
130 | data can be sliced and diced to generate a myriad of summary | ||
131 | reports. Possible uses include website log analysis, sports | ||
132 | statistics analysis, compilation of programming metrics, and | ||
133 | analysis of experimental results. | ||
134 | </p> | ||
135 | |||
136 | <p> | ||
137 | You can also do the same thing with a enterprise client/server | ||
138 | database, of course. The advantages to using SQLite in this situation | ||
139 | are that SQLite is much easier to set up and the resulting database | ||
140 | is a single file that you can store on a floppy disk or flash-memory stick | ||
141 | or 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> | ||
148 | If you are writing a client application for an enterprise database engine, | ||
149 | it makes sense to use a generic database backend that allows you to connect | ||
150 | to many different kinds of SQL database engines. It makes even better | ||
151 | sense to | ||
152 | go ahead and include SQLite in the mix of supported database and to statically | ||
153 | link the SQLite engine in with the client. That way the client program | ||
154 | can be used standalone with an SQLite data file for testing or for | ||
155 | demonstrations. | ||
156 | </p> | ||
157 | </li> | ||
158 | |||
159 | <li><p><b>Database Pedagogy</b></p> | ||
160 | |||
161 | <p> | ||
162 | Because it is simple to setup and use (installation is trivial: just | ||
163 | copy the <b>sqlite</b> or <b>sqlite.exe</b> executable to the target machine | ||
164 | and run it) SQLite makes a good database engine for use in teaching SQL. | ||
165 | Students can easily create as many databases as they like and can | ||
166 | email databases to the instructor for comments or grading. For more | ||
167 | advanced students who are interested in studying how an RDBMS is | ||
168 | implemented, the modular and well-commented and documented SQLite code | ||
169 | can serve as a good basis. This is not to say that SQLite is an accurate | ||
170 | model of how other database engines are implemented, but rather a student who | ||
171 | understands how SQLite works can more quickly comprehend the operational | ||
172 | principles 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 | ||
179 | prototyping 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 | ||
192 | over a network, you should consider using a client/server database | ||
193 | engine instead of SQLite. SQLite will work over a network filesystem, | ||
194 | but because of the latency associated with most network filesystems, | ||
195 | performance will not be great. Also, the file locking logic of | ||
196 | many network filesystems implementation contains bugs (on both Unix | ||
197 | and windows). If file locking does not work like it should, | ||
198 | it might be possible for two or more client programs to modify the | ||
199 | same part of the same database at the same time, resulting in | ||
200 | database corruption. Because this problem results from bugs in | ||
201 | the underlying filesystem implementation, there is nothing SQLite | ||
202 | can do to prevent it.</p> | ||
203 | |||
204 | <p>A good rule of thumb is that you should avoid using SQLite | ||
205 | in situations where the same database will be accessed simultaneously | ||
206 | from 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. | ||
212 | But if you website is so busy that your are thinking of splitting the | ||
213 | database component off onto a separate machine, then you should | ||
214 | definitely consider using an enterprise-class client/server database | ||
215 | engine 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 | ||
221 | before any write operation that is not within an explicit BEGIN...COMMIT) | ||
222 | the engine has to allocate a bitmap of dirty pages in the disk file to | ||
223 | help it manage its rollback journal. SQLite needs 256 bytes of RAM for | ||
224 | every 1MiB of database (assuming a 1024-byte page size: less memory is | ||
225 | used with larger page sizes, of course). | ||
226 | For smaller databases, the amount of memory | ||
227 | required is not a problem, but when database begin to grow into the | ||
228 | multi-gigabyte range, the size of the bitmap can get quite large. If | ||
229 | you need to store and modify more than a few dozen GB of data, you should | ||
230 | consider using a different database engine. | ||
231 | </p> | ||
232 | </li> | ||
233 | |||
234 | <li><p><b>High Concurrency</b></p> | ||
235 | |||
236 | <p> | ||
237 | SQLite uses reader/writer locks on the entire database file. That means | ||
238 | if any process is reading from any part of the database, all other | ||
239 | processes are prevented from writing any other part of the database. | ||
240 | Similarly, if any one process is writing to the database, | ||
241 | all other processes are prevented from reading any other part of the | ||
242 | database. | ||
243 | For many situations, this is not a problem. Each application | ||
244 | does its database work quickly and moves on, and no lock lasts for more | ||
245 | than a few dozen milliseconds. But there are some applications that require | ||
246 | more concurrency, and those applications may need to seek a different | ||
247 | solution. | ||
248 | </p> | ||
249 | </li> | ||
250 | |||
251 | </ul> | ||
252 | |||
253 | } | ||
254 | footer $rcsid | ||