Documentation Source Text

architectures.  These features make SQLite a popular choice as
an <a href="whentouse.html#appfileformat">Application File Format</a>.
Think of SQLite not as a replacement for 
<a href="http://www.oracle.com/database/index.html">Oracle</a> but
as a replacement for <a href="http://man.he.net/man3/fopen">fopen()</a></p>

<p>SQLite is a compact library.
With all features enabled, the library size can be less than 300KiB,
depending on compiler optimization settings.  (Some compiler optimizations
such as aggressive function inlining and loop unrolling can cause the
object code to be much larger.)  If optional features are omitted, the
size of the SQLite library can be reduced below 180KiB.  SQLite can also
be made to run in minimal stack space (16KiB) and
very little heap (100KiB), making SQLite a popular database engine 
choice on memory constrained gadgets such as cellphones, PDAs, and MP3 players.

<title>The SQLite Amalgamation</title>
<tcl>hd_keywords {amalgamation} {the amalgamation}</tcl>

<h2>The SQLite Amalgamation</h2>

<p>The core SQLite library consists of about 88 files of C code
(as of [Version 3.6.11]) in the core with 12 additional files
in the FTS3 and [RTREE] extensions.
Most of these are "source" files in the sense that they are stored 
in the configuration management system and are maintained directly. 
But 6 of the core C files are generated automatically during the 
compilation process.  Of the 88 code files, 67 are C code and 
21 are C header files.</p>

<p>The standard makefiles for SQLite have a target for building
an object we call the "amalgamation".  
The amalgamation is a single C code file, named "sqlite3.c",
that contains all C code 
for the core SQLite library and the FTS3 and [RTREE] extensions.
This file contains about 104K lines of code 
(62K if you omit blank lines and comments) and is over 3.5 megabytes
in size.</p>

<p>The amalgamation contains everything you need to integrate SQLite 
into a larger project.  Just copy the amalgamation into your source 
directory and compile it along with the other C code files in your project.
You may also want to make use of the "sqlite3.h" header file that 
defines the programming API for SQLite. 

}

chng {2009 Feb 18 (3.6.11)} {
<li>Added the [sqlite3_backup_init | hot-backup interface].
<li>Added new commands ".backup" and ".restore" to the [CLI].
<li>Added new methods <a href="tclsqlite.html#backup">backup</a> and
    <a href="tclsqlite.html#restore">restore</a> to the TCL interface.
<li>Improvements to the <a href="syntaxdiagrams.html">syntax bubble
    diagrams</a>
<li>Various minor bug fixes
}

chng {2009 Jan 15 (3.6.10)} {
<li>Fix a cache coherency problem that could lead to database corruption.
    [Ticket #3584].
}

  guide.  This article is intended as introduction only and is neither a
  complete or authoritative reference for the SQLite API.
</p>

<tcl>HEADING 1 {Core Objects And Interfaces}</tcl>

<p>
  The principal task of an SQL database engine is to evaluate statements
  of SQL.  In order to accomplish this purpose, the developer needs
  to know about two objects:
</p>

<p><ul>
  <li> The [database connection] object: sqlite3 </li>
  <li> The [prepared statement] object: sqlite3_stmt </li>
</ul></p>

<p>
  Strictly speaking, the [prepared statement] object is not required since
  the convenience wrapper interfaces, [sqlite3_exec] or
  [sqlite3_get_table], can be used and these convenience wrappers
  encapsulate and hide the [prepared statement] object.
  Nevertheless, an understanding of
  [prepared statements] is needed to make full use of SQLite.
</p>

<p>
  The [database connection] and [prepared statement] objects are controlled
  by a small set of C/C++ interface routine listed below.
</p>

  be thought of as methods on the [database connection] object.
  This routine is the constructor for the [database connection] object.
</td>

<tr><td valign="top" align="right">[sqlite3_prepare()]</td>
<td valign="top">
  This routine
  converts SQL text into a [prepared statement] object and returns a pointer
  to that object.  This interface requires a [database connection] pointer
  created by a prior call to [sqlite3_open()] and a text string containing
  the SQL statement to be prepared.  This API does not actually evaluate
  the SQL statement.  It merely prepares the SQL statement for evaluation.

  <p>Note that the use of [sqlite3_prepare()] is not recommended for new
  applications.  The alternative routine [sqlite3_prepare_v2()] should

</p>

<p>
  Usually, though, it is not useful to evaluate exactly the same SQL
  statement more than once.  More often, one wants to evalute similar
  statements.  For example, you might want to evaluate an INSERT statement
  multiple times though with different values to insert.  To accommodate
  this kind of flexibility, SQLite allows SQL statements to contain
  [parameter | parameters]
  which are "bound" to values prior to being evaluated.  These values can
  later be changed and the same [prepared statement] can be evaluated
  a second time using the new values.
</p>

<p>
  In SQLite, whereever it is valid to include a string literal, one can use
  a [parameter] in one of the following forms:
</p>

<p><ul>
  <li> <b>?</b> </li>
  <li> <b>?</b><i>NNN</i> </li>
  <li> <b>:</b><i>AAA</i> </li>
  <li> <b>$</b><i>AAA</i> </li>

<li> memcpy()
<li> memcmp()
<li> strcmp()
<li> malloc(), free(), and realloc()
</ul>

<p>
SQLite can be configured at start-time to 
[memsys5 | use a static buffer in place of calling malloc()]
for the memory it needs.
The date and time SQL functions provided by SQLite require
some additional C library support, but those functions can
be also be omitted from the build using compile-time options.
</p>

<p>
Communications between SQLite and the operating system and disk are
mediated through an interchangable 
[sqlite3_vfs | Virtual File System (VFS)] layer.
VFS modules for Unix (Linux and Mac OS X), OS/2, and Windows (Win32 and WinCE)
are provided in the source tree.  It is a simple matter to devise an
alternative VFS for embedded devices.
</p>

<p>
For safe operation in multi-threaded environments, SQLite requires
the use of mutexes.  Appropriate mutex libraries are linked automatically
for Win32 and POSIX platforms.  For other systems, mutex primitives
can be added at start-time using the 
[sqlite3_config]([SQLITE_CONFIG_MUTEX],...) interface.
Mutexes are only required if SQLite is
used by more than one thread at a time.
</p>

<p>
The SQLite source code is available as an
"[amalgamation]" - a single large C source code file.
Projects that want to include SQLite can do so simply
by dropping this one source file (named "sqlite3.c") and
its corresponding header ("sqlite3.h") into their source
tree and compiling it together with the rest of the
code.  SQLite does not link against any external libraries
(other than the C library, as described above) and does
not require any special build support.