History
+History
There are two main C interfaces to the SQLite library: @@ -48,7 +39,7 @@ the plumbing is very different. The diagram at the right shows the structure of SQLite for version 2.8.13 and following.
-Interface
+Interface
Much of the public interface to the SQLite library is implemented by functions found in the main.c source file though some routines are @@ -67,11 +58,11 @@ Those symbols that are intended for external use (in other words, those symbols which form the API for SQLite) begin with sqlite_.
-SQL Command Process
+SQL Command Process
-
Tokenizer
+Tokenizer
When a string containing SQL statements is to be executed, the interface passes that string to the tokenizer. The job of the tokenizer @@ -87,7 +78,7 @@ of SQLite has done it both ways and finds things generally work out nicer for the tokenizer to call the parser. YACC has it backwards.
-Parser
+Parser
The parser is the piece that assigns meaning to tokens based on their context. The parser for SQLite is generated using the @@ -106,7 +97,7 @@ SQLite distribution in the "tool" subdirectory. Documentation on lemon is found in the "doc" subdirectory of the distribution.
-Code Generator
+Code Generator
After the parser assembles tokens into complete SQL statements, it calls the code generator to produce virtual machine code that @@ -126,7 +117,7 @@ for SQL statements with the same names. (Each of these files calls routines in expr.c and where.c as necessary.) All other SQL statements are coded out of build.c.
-Virtual Machine
+Virtual Machine
The program generated by the code generator is executed by the virtual machine. Additional information about the virtual @@ -146,20 +137,20 @@ The vdbeaux.c file contains utilities used by the virtual machine and interface modules used by the rest of the library to construct VM programs.
-Backend
+Backend
The backend is an abstraction layer that presents a uniform interface to the virtual machine for either the B-Tree drivers for disk-based databases or the Red/Black Tree driver for in-memory databases. The btree.h source file contains the details.
-Red/Black Tree
+Red/Black Tree
In-memory databases are stored in a red/black tree implementation contain in the btree_rb.c source file.
-B-Tree
+B-Tree
An SQLite database is maintained on disk using a B-tree implementation found in the btree.c source file. A separate B-tree is used for @@ -173,7 +164,7 @@ entry. Any additional payload is stored in a chain of overflow pages.
btree.h. -Page Cache
+Page Cache
The B-tree module requests information from the disk in 1024 byte chunks. The page cache is reponsible for reading, writing, and @@ -190,7 +181,7 @@ source file pager.c. The interface to the page cache subsystem is defined by the header file pager.h.
-OS Interface
+OS Interface
In order to provide portability between POSIX and Win32 operating systems, @@ -203,12 +194,4 @@ for Win32. The interface to the OS abstraction layer is defined by the os.h header file.
} - -puts { --
-
-Back to the SQLite Home Page
-
-The C language interface to the SQLite library -
} -puts "-(This page was last modified on [lrange $rcsid 3 4] UTC) -
" - +set rcsid {$Id: c_interface.tcl,v 1.40 2004/05/31 15:06:29 drh Exp $} +source common.tcl +header {The C language interface to the SQLite library} puts { +The C language interface to the SQLite library
+The SQLite library is designed to be very easy to use from a C or C++ program. This document gives an overview of the C/C++ programming interface.
-1.0 The Core API
+1.0 The Core API
The interface to the SQLite library consists of three core functions, one opaque data structure, and some constants used as return values. @@ -51,7 +42,7 @@ the core functions shown above.
-1.1 Opening a database
+1.1 Opening a database
Use the sqlite_open function to open an existing SQLite database or to create a new SQLite database. The first argument @@ -83,7 +74,7 @@ deal with the same database. NULL is returned if the open fails for any reason.
-1.2 Closing the database
+1.2 Closing the database
To close an SQLite database, call the sqlite_close function passing it the sqlite structure pointer that was obtained @@ -92,7 +83,7 @@ If a transaction is active when the database is closed, the transaction is rolled back.
-1.3 Executing SQL statements
+1.3 Executing SQL statements
The sqlite_exec function is used to process SQL statements and queries. This function requires 5 parameters as follows:
@@ -170,7 +161,7 @@ result set is empty. function returns non-zero, the query is immediately aborted and sqlite_exec will return SQLITE_ABORT. -1.4 Error Codes
+1.4 Error Codes
The sqlite_exec function normally returns SQLITE_OK. But @@ -344,7 +335,7 @@ the sqlite_finalize routine is ready to be called. -
2.0 Accessing Data Without Using A Callback Function
+2.0 Accessing Data Without Using A Callback Function
The sqlite_exec routine described above used to be the only @@ -390,7 +381,7 @@ once for each row of output, and finally call sqlite_finalize to clean up after the SQL has finished execution.
-2.1 Compiling An SQL Statement Into A Virtual Machine
+2.1 Compiling An SQL Statement Into A Virtual Machine
The sqlite_compile "compiles" a single SQL statement (specified @@ -436,7 +427,7 @@ On success, sqlite_compile returns SQLITE_OK. Otherwise and error code is returned.
-2.2 Step-By-Step Execution Of An SQL Statement
+2.2 Step-By-Step Execution Of An SQL Statement
After a virtual machine has been generated using sqlite_compile @@ -521,7 +512,7 @@ usage prior to a mishap. The misuse detection logic is not guaranteed to work in every case.
-2.3 Deleting A Virtual Machine
+2.3 Deleting A Virtual Machine
Every virtual machine that sqlite_compile creates should @@ -556,7 +547,7 @@ It is also acceptable to call sqlite_finalize on a virtual machine that has never been passed to sqlite_step even once.
-3.0 The Extended API
+3.0 The Extended API
Only the three core routines described in section 1.0 are required to use SQLite. But there are many other functions that provide @@ -642,7 +633,7 @@ void sqlite_progress_handler(sqlite*, int, int (*)(void*), void*);
All of the above definitions are included in the "sqlite.h" header file that comes in the source tree.
-3.1 The ROWID of the most recent insert
+3.1 The ROWID of the most recent insert
Every row of an SQLite table has a unique integer key. If the table has a column labeled INTEGER PRIMARY KEY, then that column @@ -658,7 +649,7 @@ the key is automatically generated. You can find the value of the key for the most recent INSERT statement using the sqlite_last_insert_rowid API function.
-3.2 The number of rows that changed
+3.2 The number of rows that changed
The sqlite_changes API function returns the number of rows that have been inserted, deleted, or modified since the database was @@ -686,7 +677,7 @@ will be zero regardless of the number of elements that were originally in the table. If an accurate count of the number of elements deleted is necessary, use "DELETE FROM table WHERE 1" instead.
-3.3 Querying into memory obtained from malloc()
+3.3 Querying into memory obtained from malloc()
The sqlite_get_table function is a wrapper around sqlite_exec that collects all the information from successive @@ -773,7 +764,7 @@ as would be returned if the result set is empty.
The sqlite_get_table routine returns the same integer result code as sqlite_exec.
-3.4 Interrupting an SQLite operation
+3.4 Interrupting an SQLite operation
The sqlite_interrupt function can be called from a different thread or from a signal handler to cause the current database @@ -781,7 +772,7 @@ operation to exit at its first opportunity. When this happens, the sqlite_exec routine (or the equivalent) that started the database operation will return SQLITE_INTERRUPT.
-3.5 Testing for a complete SQL statement
+3.5 Testing for a complete SQL statement
The next interface routine to SQLite is a convenience function used to test whether or not a string forms a complete SQL statement. @@ -803,7 +794,7 @@ then sqlite_exec is called and the input buffer is reset. If the continuation prompt and another line of text is read and added to the input buffer.
-3.6 Library version string
+3.6 Library version string
The SQLite library exports the string constant named sqlite_version which contains the version number of the @@ -813,7 +804,7 @@ the SQLITE_VERSION macro against the sqlite_version string constant to verify that the version number of the header file and the library match.
-3.7 Library character encoding
+3.7 Library character encoding
By default, SQLite assumes that all data uses a fixed-size 8-bit character (iso8859). But if you give the --enable-utf8 option @@ -830,7 +821,7 @@ be changed at run-time. This is a compile-time option only. The sqlite_encoding character string just tells you how the library was compiled.
-3.8 Changing the library's response to locked files
+3.8 Changing the library's response to locked files
The sqlite_busy_handler procedure can be used to register a busy callback with an open SQLite database. The busy callback will @@ -860,7 +851,7 @@ will wait for the lock to clear for at least the number of milliseconds specified before it returns SQLITE_BUSY. Specifying zero milliseconds for the timeout restores the default behavior.
-3.9 Using the _printf() wrapper functions
+3.9 Using the _printf() wrapper functions
The four utility functions
@@ -981,7 +972,7 @@ routine. The string pointer that these routines return should be freed by passing it to sqlite_freemem(). -3.10 Performing background jobs during large queries
+3.10 Performing background jobs during large queries
The sqlite_progress_handler() routine can be used to register a callback routine with an SQLite database to be invoked periodically during long @@ -1006,7 +997,7 @@ determine whether or not background jobs need to be run.
-4.0 Adding New SQL Functions
+4.0 Adding New SQL Functions
Beginning with version 2.4.0, SQLite allows the SQL language to be extended with new functions implemented as C code. The following interface @@ -1089,7 +1080,7 @@ new SQL functions, review the SQLite source code in the file func.c.
-5.0 Multi-Threading And SQLite
+5.0 Multi-Threading And SQLite
If SQLite is compiled with the THREADSAFE preprocessor macro set to 1, @@ -1112,7 +1103,7 @@ Under Unix, an sqlite* pointer should not be carried across a should open its own copy of the database after the fork().
-6.0 Usage Examples
+6.0 Usage Examples
For examples of how the SQLite C/C++ interface can be used, refer to the source code for the sqlite program in the @@ -1122,11 +1113,4 @@ Additional information about sqlite is available at See also the sources to the Tcl interface for SQLite in the source file src/tclsqlite.c.
} - -puts { --
-Back to the SQLite Home Page
-
Recent Changes To SQLite
- +source common.tcl +header {SQLite changes} +puts {
-This file provides a high-level summary of changes to SQLite.
+This page provides a high-level summary of changes to SQLite.
For more detail, refer the the checkin logs generated by
CVS at
@@ -1097,9 +1093,5 @@ chng {2000 May 29} {
puts {
-
-Back to the SQLite Home Page
-
 |
++ |
+
|
++ | + + | +
-Constraint Conflict Resolution in SQLite -
} -puts "-(This page was last modified on [lrange $rcsid 3 4] UTC) -
" - +set rcsid {$Id: conflict.tcl,v 1.3 2004/05/31 15:06:30 drh Exp $ } +source common.tcl +header {Constraint Conflict Resolution in SQLite} puts { -Introduction
+Constraint Conflict Resolution in SQLite
In most SQL databases, if you have a UNIQUE constraint on a table and you try to do an UPDATE or INSERT that violates -that constraint, the database will aborts the operation in -progress, back out any prior changes associated with that -one UPDATE or INSERT command, and return an error. +the constraint, the database will abort the operation in +progress, back out any prior changes associated with +UPDATE or INSERT command, and return an error. This is the default behavior of SQLite. Beginning with version 2.3.0, though, SQLite allows you to define alternative ways for dealing with constraint violations. @@ -99,11 +88,4 @@ What you really want is to use the IGNORE algorithm to insert all but the malformed record.
} - -puts { --
-Back to the SQLite Home Page
-
+Copyright Release for
+Contributions To SQLite
+
+
++SQLite is software that implements an embeddable SQL database engine. +SQLite is available for free download from http://www.sqlite.org/. +The principal author and maintainer of SQLite has disclaimed all +copyright interest in his contributions to SQLite +and thus released his contributions into the public domain. +In order to keep the SQLite software unencumbered by copyright +claims, the principal author asks others who may from time to +time contribute changes and enhancements to likewise disclaim +their own individual copyright interest. +
+ ++Because the SQLite software found at http://www.sqlite.org/ is in the +public domain, anyone is free to download the SQLite software +from that website, make changes to the software, use, distribute, +or sell the modified software, under either the original name or +under some new name, without any need to obtain permission, pay +royalties, acknowledge the original source of the software, or +in any other way compensate, identify, or notify the original authors. +Nobody is in any way compelled to contribute their SQLite changes and +enhancements back to the SQLite website. This document concerns +only changes and enhancements to SQLite that are intentionally and +deliberately contributed back to the SQLite website. +
+ ++For the purposes of this document, "SQLite software" shall mean any +computer source code, documentation, makefiles, test scripts, or +other information that is published on the SQLite website, +http://www.sqlite.org/. Precompiled binaries are excluded from +the definition of "SQLite software" in this document because the +process of compiling the software may introduce information from +outside sources which is not properly a part of SQLite. +
+ ++The header comments on the SQLite source files exhort the reader to +share freely and to never take more than one gives. +In the spirit of that exhortation I make the following declarations: +
+ +-
+
+I dedicate to the public domain +any and all copyright interest in the SQLite software that +was publicly available on the SQLite website (http://www.sqlite.org/) prior +to the date of the signature below and any changes or enhancements to +the SQLite software +that I may cause to be published on that website in the future. +I make this dedication for the benefit of the public at large and +to the detriment of my heirs and successors. I intend this +dedication to be an overt act of relinquishment in perpetuity of +all present and future rights to the SQLite software under copyright +law. +
+
++To the best of my knowledge and belief, the changes and enhancements that +I have contributed to SQLite are either originally written by me +or are derived from prior works which I have verified are also +in the public domain and are not subject to claims of copyright +by other parties. +
+
++To the best of my knowledge and belief, no individual, business, organization, +government, or other entity has any copyright interest +in the SQLite software as it existed on the +SQLite website as of the date on the signature line below. +
+
++I agree never to publish any additional information +to the SQLite website (by CVS, email, scp, FTP, or any other means) unless +that information is an original work of authorship by me or is derived from +prior published versions of SQLite. +I agree never to copy and paste code into the SQLite code base from +other sources. +I agree never to publish on the SQLite website any information that +would violate a law or breach a contract. +
+
+
|
+Signature:
+ + + + | +Date: + | +Name (printed): + | + +
Datatypes In SQLite Version 2
-puts { - --Datatypes In SQLite -
-} -puts "-(This page was last modified on [lrange $rcsid 3 4] UTC) -
" - -puts {1.0 Typelessness
+1.0 Typelessness
SQLite is "typeless". This means that you can store any kind of data you want in any column of any table, regardless of the @@ -79,7 +70,7 @@ And so forth. Basically any sequence of names optionally followed by one or two signed integers in parentheses will do.
-2.0 The INTEGER PRIMARY KEY
+2.0 The INTEGER PRIMARY KEY
One exception to the typelessness of SQLite is a column whose type @@ -101,7 +92,7 @@ the sqlite_last_insert_rowid() API function or using the last_insert_rowid() SQL function in a subsequent SELECT statement.
-3.0 Comparison and Sort Order
+3.0 Comparison and Sort Order
SQLite is typeless for the purpose of deciding what data is allowed @@ -144,7 +135,7 @@ A comparison of any value against NULL using operators like "<" or ">=" is always false.
-4.0 How SQLite Determines Datatypes
+4.0 How SQLite Determines Datatypes
For SQLite version 2.6.3 and earlier, all values used the numeric datatype. @@ -193,7 +184,7 @@ then the datatype is numeric. Note in particular that the datatype for columns with an empty type declaration is numeric.
-5.0 Examples
+5.0 Examples
Consider the following two command sequences: @@ -249,11 +240,4 @@ are treated as numbers and are therefore indistinct. But the SELECT statement on the right returns two rows since 0 and 0.0 are treated a strings which are different.
} - -puts { --
-Back to the SQLite Home Page
-
Available Documentation
+| } + regsub -all { +} $name {\ } name + puts "$name | " + puts {} + puts { | } + puts $desc + puts { |
SQLite Download Page
+puts { +SQLite Download Page
-
-
-Back to the SQLite home page
-
Frequently Asked Questions
-} -puts "-(This page was last modified on [lrange $rcsid 3 4] UTC) -
" - +set rcsid {$Id: faq.tcl,v 1.24 2004/05/31 15:06:30 drh Exp $} +source common.tcl +header {SQLite Frequently Asked Questions} set cnt 1 proc faq {question answer} { @@ -432,12 +422,19 @@ faq { # End of questions and answers. ############# -puts {- }
+puts {
- ($i) " +# puts "
- [lindex $faq($i) 0] " +# } +# puts {
- ($i) " - puts "
- [lindex $faq($i) 0] " + puts "
- [lindex $faq($i) 0] " } -puts {
Frequently Asked Questions
} + +# puts {- }
+# for {set i 1} {$i<$cnt} {incr i} {
+# puts "
- }
for {set i 1} {$i<$cnt} {incr i} {
- puts "
" @@ -445,11 +442,5 @@ for {set i 1} {$i<$cnt} {incr i} { puts "
[lindex $faq($i) 1]\n" } -puts { - -
-
-Back to the SQLite Home Page
-
-SQLite Database File Format -
-} -puts "-(This page was last modified on [lrange $rcsid 3 4] UTC) -
" - +set rcsid {$Id: fileformat.tcl,v 1.12 2004/05/31 15:06:30 drh Exp $} +source common.tcl +header {SQLite Database File Format (Version 2)} puts { -1.0 Layers
+SQLite 2.X Database File Format
+ ++This document describes the disk file format for SQLite versions 2.1 +through 2.8. SQLite version 3.0 and following uses a very different +format which is described separately. +
+ +1.0 Layers
SQLite is implemented in layers. @@ -37,7 +33,7 @@ We wil describe each layer beginning with the bottom (pager) layer and working upwards.
-2.0 The Pager Layer
+2.0 The Pager Layer
An SQLite database consists of @@ -158,7 +154,7 @@ Here is a summary of the journal file format: -
3.0 The B-Tree Layer
+3.0 The B-Tree Layer
The B-Tree layer builds on top of the pager layer to implement @@ -206,7 +202,7 @@ The b-tree itself does not record which pages are root pages and which are not. That information is handled entirely at the schema layer.
-3.1 B-Tree Page 1 Details
+3.1 B-Tree Page 1 Details
Page 1 begins with the following 48-byte string: @@ -275,7 +271,7 @@ Here is a summary of the information contained on page 1 in the b-tree layer:
3.2 Structure Of A Single B-Tree Page
+3.2 Structure Of A Single B-Tree Page
Conceptually, a b-tree page contains N database entries and N+1 pointers @@ -502,7 +498,7 @@ the page by moving all cells to the beginning and constructing a single freeblock at the end to take up all remaining space.
-3.3 The B-Tree Free Page List
+3.3 The B-Tree Free Page List
When information is removed from an SQLite database such that one or @@ -571,7 +567,7 @@ these two optimizations allow some database operations to go four to six times faster than they would otherwise.
-4.0 The Schema Layer
+4.0 The Schema Layer
The schema layer implements an SQL database on top of one or more @@ -591,7 +587,7 @@ extracted. For indices, the b-tree key varies in size depending on the size of the fields being indexed and the b-tree data is empty.
-4.1 SQL Table Implementation Details
+4.1 SQL Table Implementation Details
Each row of an SQL table is stored in a single b-tree entry. The b-tree key is a 4-byte big-endian integer that is the ROWID @@ -659,7 +655,7 @@ INTEGER PRIMARY KEY, just like any other column. But the Value associated with that offset is always NULL.
-4.2 SQL Index Implementation Details
+4.2 SQL Index Implementation Details
SQL indices are implement using a b-tree in which the key is used @@ -685,7 +681,7 @@ NULLs being sorted first, followed by numerical values in numerical order, followed by text values in lexigraphical order.
-4.4 SQL Schema Storage And Root B-Tree Page Numbers
+4.4 SQL Schema Storage And Root B-Tree Page Numbers
The database schema is stored in the database in a special tabled named @@ -720,7 +716,7 @@ database. But the schema table for the temporary database named name change, it works exactly the same.
-4.4 Schema Version Numbering And Other Meta-Information
+4.4 Schema Version Numbering And Other Meta-Information
The nine 32-bit integers that are stored beginning at byte offset @@ -785,13 +781,5 @@ to a SYNCHRONOUS setting of NORMAL. A value of 3 corresponds to a SYNCHRONOUS setting of FULL. If the value is 0, that means it has not been initialized so the default synchronous setting of NORMAL is used.
- } - -puts { --
-Back to the SQLite Home Page
-
-File Format Changes in SQLite -
} -puts "-(This page was last modified on [lrange $rcsid 3 4] UTC) -
" - +set rcsid {$Id: formatchng.tcl,v 1.10 2004/05/31 15:06:30 drh Exp $ } +source common.tcl +header {File Format Changes in SQLite} puts { +File Format Changes in SQLite
+From time to time, enhancements or bug fixes require a change to the underlying file format for SQLite. When this happens and you @@ -175,6 +166,16 @@ occurred since version 1.0.0: to restore the database.
+Version 3.0.0 is a major upgrade for SQLite that incorporates + support for UTF-16, BLOBs, and a more compact encoding that results + in database files that are typically 25% to 35% smaller. The new file + format is radically different and completely incompatible with the + version 2 file format.
+