Documentation Source Text

automatically and transparently, it appears to the program using
SQLite as if the aborted transaction had never begun.</p>

<br clear="both">
<h2>5.0 Multi-file Commit</h2>

<p>SQLite allows a single 
<a href="/capi3ref.html#sqlite3">database connection</a> to talk to
two or more database files simultaneously through the use of
the <a href="/lang_attach.html">ATTACH DATABASE</a> command.
When multiple database files are modified within a single
transaction, all files are updated atomically.  
In other words, either all of the database files are updated or
else none of them are.
Achieving an atomic commit across multiple database files is

<h3>5.2 The Master Journal File</h3>
<img src="images/ac/multi-1.gif" align="right" hspace="15">

<p>The next step in a multi-file commit is the creation of a
"master journal" file.  The name of the master journal file is
the same name as the original database filename (the database
that was opened using the 
<a href="capi3ref.html#sqlite3_open">sqlite3_open()</a> interface,
not one of the <a href="lang_attach.html">ATTACHed</a> auxiliary
databases) with the text "<b>-mj</b><i>HHHHHHHH</i>" appended where
<i>HHHHHHHH</i> is a random 32-bit hexadecimal number.  The
random <i>HHHHHHHH</i> suffix changes for every new master journal.</p>

<p><i>(Nota bene: The formula for computing the master journal filename
given in the previous paragraph corresponds to the implementation as

}


chng {2007 Sep 04 (3.5.0) alpha} {
<li>Redesign the OS interface layer.  See
    <a href="34to35.html">34to35.html</a> for details.
    <font color="red">*** Potentially incompatible change ***</font>
<li>The <a href="capi3ref.html#sqlite3_release_memory">
    sqlite3_release_memory()</a>,
    <a href="capi3ref.html#sqlite3_soft_heap_limit">
    sqlite3_soft_heap_limit()</a>,
    and <a href="capi3ref.html#sqlite3_enable_shared_cache">
    sqlite3_enable_shared_cache()</a> interfaces now work cross all
    threads in the process, not just the single thread in which they
    are invoked.
    <font color="red">*** Potentially incompatible change ***</font>
<li>Added the 
    <a href="capi3ref.html#sqlite3_open_v2">sqlite3_open_v2()</a>
    interface.  
<li>Reimplemented the memory allocation subsystem and made it 
    replacable at compile-time.
<li>Created a new mutex subsystem and made it replacable at
    compile-time.
<li>The same database connection may now be used simultaneously by
    separate threads.
}


chng {2007 August 13 (3.4.2)} {
<li>Fix a database corruption bug that might occur if a ROLLBACK command
is executed in <a href="pragma.html#pragma_auto_vacuum">auto-vacuum mode</a>
and a very small <a href="capi3ref.html#sqlite3_soft_heap_limit">
soft_heap_limit</a> is set. 
<a href="http://www.sqlite.org/cvstrac/tktview?tn=2565">Ticket #2565</a>.

<li>Add the ability to run a full regression test with a small
<a href="capi3ref.html#sqlite3_soft_heap_limit">soft_heap_limit</a>.

<li>Fix other minor problems with using small soft heap limits.

<li>Work-around for 
<a href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=32575">GCC bug 32575</a>.

<li>Improved error detection of misused aggregate functions.

    <a href="http://www.sqlite.org/cvstrac/tktview?tn=2418">ticket #2418</a>. 
    </li>
<li>Added explicit <a href="limits.html">upper bounds</a> on the sizes and
    quantities of things SQLite can process.  This change might cause
    compatibility problems for
    applications that use SQLite in the extreme, which is why the current
    release is 3.4.0 instead of 3.3.18.</li>
<li>Added support for <a href="capi3ref.html#sqlite3_blob_open">
    Incremental BLOB I/O</a>.</li>
<li>Added the <a href="capi3ref.html#sqlite3_bind_zeroblob">zeroblob API</a>
    and the <a href="lang_expr.html#zeroblob">zeroblob()</a> SQL function.</li>
<li>Added support for <a href="pragma.html#pragma_incremental_vacuum">
    Incremental Vacuum</a>.</li>
<li>Added the SQLITE_MIXED_ENDIAN_64BIT_FLOAT compile-time option to suppport
    ARM7 processors with goofy endianness.</li>
<li>Removed all instances of sprintf() and strcpy() from the core library.</li>
<li>Added support for <a href="http://www.icu-project.org/">
    International Components for Unicode (ICU)</a> to the full-text search
    extensions.
</ul><p>
<ul type="circle">
<li>In the windows OS driver, reacquire a SHARED lock if an attempt to
    acquire an EXCLUSIVE lock fails.  Ticket #2354</li>
<li>Fix the REPLACE() function so that it returns NULL if the second argument
    is an empty string.  Ticket #2324.</li>
<li>Document the hazards of type coversions in
    <a href="capi3ref.html#sqlite3_column_blob">sqlite3_column_blob()</a>
    and related APIs.  Fix unnecessary type conversions.  Ticket #2321.</li>
<li>Internationalization of the TRIM() function.  Ticket #2323</li>
<li>Use memmove() instead of memcpy() when moving between memory regions
    that might overlap.  Ticket #2334</li>
<li>Fix an optimizer bug involving subqueries in a compound SELECT that has
    both an ORDER BY and a LIMIT clause.  Ticket #2339.</li>
<li>Make sure the <a href="capi3ref.html#sqlite3_snprintf">sqlite3_snprintf()
    </a> interface does not zero-terminate the buffer if the buffer size is
    less than 1.  Ticket #2341</li>
<li>Fix the built-in printf logic so that it prints "NaN" not "Inf" for
    floating-point NaNs.  Ticket #2345</li>
<li>When converting BLOB to TEXT, use the text encoding of the main database.
    Ticket #2349</li>
<li>Keep the full precision of integers (if possible) when casting to

<a href="pragma.html#pragma_integrity_check">PRAGMA integrity_check</a>
generates.</li>
<li>Minor syntactic changes to support a wider variety of compilers.</li>
}

chng {2007 January 22 (3.3.11)} {
<li>Fix another bug in the implementation of the new 
<a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a> API.
We'll get it right eventually...</li>
<li>Fix a bug in the IS NULL optimization that was added in version 3.3.9 -
the bug was causing incorrect results on certain LEFT JOINs that included
in the WHERE clause an IS NULL constraint for the right table of the
LEFT JOIN.</li>
<li>Make AreFileApisANSI() a no-op macro in winCE since winCE does not
support this function.</li>
}

chng {2007 January 9 (3.3.10)} {
<li>Fix bugs in the implementation of the new 
<a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a> API
that can lead to segfaults.</li>
<li>Fix 1-second round-off errors in the 
<a href="http://www.sqlite.org/cvstrac/wiki?p=DateAndTimeFunctions">
strftime()</a> function</li>
<li>Enhance the windows OS layer to provide detailed error codes</li>
<li>Work around a win2k problem so that SQLite can use single-character
database file names</li>
<li>The
<a href="pragma.html#pragma_user_version">user_version</a> and
<a href="pragma.html#pragma_schema_version">schema_version</a> pragmas 
correctly set their column names in the result set</li>
<li>Documentation updates</li>
}

chng {2007 January 4 (3.3.9)} {
<li>Fix bugs in pager.c that could lead to database corruption if two
processes both try to recover a hot journal at the same instant</li>
<li>Added the <a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a>
API.</li>
<li>Fixed the ".dump" command in the command-line shell to show
indices, triggers and views again.</li>
<li>Change the table_info pragma so that it returns NULL for the default
value if there is no default value</li>
<li>Support for non-ASCII characters in win95 filenames</li>
<li>Query optimizer enhancements:

<li>Added support for
<a href="http://www.sqlite.org/cvstrac/wiki?p=VirtualTables">virtual tables</a>
(beta)</li>
<li>Added support for 
<a href="http://www.sqlite.org/cvstrac/wiki?p=LoadableExtensions">
dynamically loaded extensions</a> (beta)</li>
<li>The 
<a href="capi3ref.html#sqlite3_interrupt">sqlite3_interrupt()</a>
routine can be called for a different thread</li>
<li>Added the <a href="lang_expr.html#match">MATCH</a> operator.</li>
<li>The default file format is now 1.  
}

chng {2006 June 6 (3.3.6)} {
<li>Plays better with virus scanners on windows</li>

When this option is defined, the 
<a href="lang_altertable.html">ALTER TABLE</a> command is not included in the 
library. Executing an ALTER TABLE statement causes a parse error.
</p>

<p><b>SQLITE_OMIT_AUTHORIZATION</b><br>
Defining this option omits the authorization callback feature from the
library. The <a href="capi3ref.html#sqlite3_set_authorizer">
sqlite3_set_authorizer()</a> API function is not present in the library.
</p>

<p><b>SQLITE_OMIT_AUTOVACUUM</b><br>
If this option is defined, the library cannot create or write to 
databases that support 
<a href="pragma.html#pragma_auto_vacuum">auto-vacuum</a>. Executing a

#that contain blobs, so disabling this functionality may render a database
#unvacuumable.
#</p>
#<p><i>TODO: Need a link here - is that syntax documented anywhere?</i><p>
puts {

<p><b>SQLITE_OMIT_COMPLETE</b><br>
This option causes the <a href="capi3ref.html#sqlite3_complete">
sqlite3_complete</a> API to be omitted.
</p>

<p><b>SQLITE_OMIT_COMPOUND_SELECT</b><br>
This option is used to omit the compound SELECT functionality. 
<a href="lang_select.html">SELECT statements</a> that use the 
UNION, UNION ALL, INTERSECT or EXCEPT compound SELECT operators will 

specific pragmas in addition to this, as they may also remove supporting code
in other sub-systems. This macro removes the PRAGMA command only.
</p>

<p><b>SQLITE_OMIT_PROGRESS_CALLBACK</b><br>
This option may be defined to omit the capability to issue "progress" 
callbacks during long-running SQL statements. The 
<a href="capi3ref.html#sqlite3_progress_handler">sqlite3_progress_handler()</a>
API function is not present in the library.

<p><b>SQLITE_OMIT_REINDEX</b><br>
When this option is defined, the <a href="lang_reindex.html">REINDEX</a> 
command is not included in the library. Executing a REINDEX statement causes 
a parse error.
</p>

  <a href="lang_replace.html">REPLACE</a> and the
  <a href="lang_conflict.html">ON CONFLICT</a> clause that allow for
  added control over the resolution of constraint conflicts.
  SQLite supports <a href="lang_attach.html">ATTACH</a> and
  <a href="lang_detach.html">DETACH</a> commands that allow multiple
  independent databases to be used together in the same query.
  And SQLite defines APIs that allows the user to add new
  <a href="capi3ref.html#sqlite3_create_function">SQL functions</a>
  and <a href="capi3ref.html#sqlite3_create_collation">collating sequences</a>.
}

</tcl>

For all of these errors, SQLite attempts to undo just the one statement
it was working on and leave changes from prior statements within the
same transaction intact and continue with the transaction.  However, 
depending on the statement being evaluated and the point at which the
error occurs, it might be necessary for SQLite to rollback and
cancel the transaction.  An application can tell which
course of action SQLite took by using the
<a href="capi3ref.html#sqlite3_get_autocommit">sqlite3_get_autocommit()</a>
C-language interface.</p>

<p>It is recommended that applications respond to the errors
listed above by explicitly issuing a ROLLBACK command.  If the 
transaction has already been rolled back automatically
by the error response, then the ROLLBACK command will fail with an
error, but no harm is caused by this.</p>

with an ordinary table, except that you cannot create triggers on a
virtual table.  Some virtual table implementations might impose additional
restrictions.  For example, many virtual tables are read-only.</p>

<p>The &lt;module-name&gt; is the name of an object that implements
the virtual table.  The &lt;module-name&gt; must be registered with
the SQLite database connection using
<a href="capi3ref.html#sqlite3_create_module">sqlite3_create_module</a>
prior to issuing the CREATE VIRTUAL TABLE statement.
The module takes zero or more comma-separated arguments.
The arguments can be just about any text as long as it has balanced
parentheses.  The argument syntax is sufficiently general that the
arguments can be made to appear as column definitions in a traditional
<a href="#createtable">CREATE TABLE</a> statement.  
SQLite passes the module arguments directly

<p>
A literal value can also be the token "NULL".
</p>

<p>
A parameter specifies a placeholder in the expression for a literal
value that is filled in at runtime using the
<a href="capi3ref.html#sqlite3_bind_int">sqlite3_bind</a> API.
Parameters can take several forms:
</p

<blockquote>
<table class="pdf_functions">
<tr>
<td align="right" valign="top"><b>?</b><i>NNN</i></td><td width="20"></td>

any text at all.  This syntax is the form of a variable name in the Tcl
programming language.</td>
</tr>
</table>
</blockquote>

<p>Parameters that are not assigned values using
<a href="capi3ref.html#sqlite3_bind_int">sqlite3_bind</a> are treated
as NULL.</p>

<a name="like"></a>
<p>The LIKE operator does a pattern matching comparison. The operand
to the right contains the pattern, the left hand operand contains the
string to match against the pattern. 

their result across all rows of the result set.</p>

<a name="corefunctions"></a>
<b>Core Functions</b>

<p>The core functions shown below are available by default.  Additional
functions may be written in C and added to the database engine using
the <a href="capi3ref.html#cfunc">sqlite3_create_function()</a>
API.</p>

<table border=0 cellpadding=10 class="pdf_functions">
<tr>
<td valign="top" align="right" width=120>abs(<i>X</i>)</td>
<td valign="top">Return the absolute value of argument <i>X</i>.</td>
</tr>

<tr>
<td valign="top" align="right">
<a name="globFunc"></a>
glob(<i>X</i>,<i>Y</i>)</td>
<td valign="top">This function is used to implement the
"<b>X GLOB Y</b>" syntax of SQLite.  The
<a href="capi3ref.html#sqlite3_create_function">sqlite3_create_function()</a> 
interface can
be used to override this function and thereby change the operation
of the <a href="#globFunc">GLOB</a> operator.</td>
</tr>

<tr>
<td valign="top" align="right">ifnull(<i>X</i>,<i>Y</i>)</td>

like(<i>X</i>,<i>Y</i>)<br>
like(<i>X</i>,<i>Y</i>,<i>Z</i>)</td>
<td valign="top">
This function is used to implement the "<b>X LIKE Y [ESCAPE Z]</b>"
syntax of SQL. If the optional ESCAPE clause is present, then the
user-function is invoked with three arguments. Otherwise, it is
invoked with two arguments only. The 
<a href="capi3ref.html#sqlite3_create_function">
sqlite_create_function()</a> interface can be used to override this
function and thereby change the operation of the <a
href= "#like">LIKE</a> operator. When doing this, it may be important
to override both the two and three argument versions of the like() 
function. Otherwise, different code may be called to implement the
LIKE operator depending on whether or not an ESCAPE clause was 
specified.</td>

<p>This function will fail if the extension attempts to modify
or delete a SQL function or collating sequence.  The
extension can add new functions or collating sequences, but cannot
modify or delete existing functions or collating sequences because
those functions and/or collating sequences might be used elsewhere
in the currently running SQL statement.  To load an extension that
changes or deletes functions or collating sequences, use the
<a href="capi3ref.html#sqlite3_load_extension">sqlite3_load_extension()</a>
C-language API.</p>
</tr>

<tr>
<td valign="top" align="right">lower(<i>X</i>)</td>
<td valign="top">Return a copy of string <i>X</i> will all characters
converted to lower case.  The C library <b>tolower()</b> routine is used

<tr>
<td valign="top" align="right">zeroblob(<i>N</i>)</td>
<td valign="top"><a name="zeroblob"></a>
Return a BLOB consisting of N bytes of 0x00.  SQLite
manages these zeroblobs very efficiently.  Zeroblobs can be used to
reserve space for a BLOB that is later written using 
<a href="capi3ref.html#sqlite3_blob_open">incremental BLOB I/O</a>.</td>
</tr>

</table>

<b>Date And Time Functions</b>

<p>Date and time functions are documented in the 
<a href="http://www.sqlite.org/cvstrac/wiki?p=DateAndTimeFunctions">
SQLite Wiki</a>.</p>

<a name="aggregatefunctions"></a>
<b>Aggregate Functions</b>

<p>
The aggregate functions shown below are available by default.  Additional
aggregate functions written in C may be added using the 
<a href="capi3ref.html#sqlite3_create_function">sqlite3_create_function()</a>
API.</p>

<p>
In any aggregate function that takes a single argument, that argument
can be preceeded by the keyword DISTINCT.  In such cases, duplicate
elements are filtered before being passed into the aggregate function.
For example, the function "count(distinct X)" will return the number

<p>
In most applications, the number of columns is small - a few dozen.
There are places in the SQLite code generator that use algorithms
that are O(N&sup2;) where N is the number of columns.  
So if you redefine SQLITE_MAX_COLUMN to be a
really huge number and you generate SQL that uses a large number of
columns, you may find that 
<a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a>
runs slowly.
}

limititem {Maximum Length Of An SQL Statement} {
<p>
The maximum number of bytes in the text of an SQL statement is 
limited to SQLITE_MAX_SQL_LENGTH which defaults to 1000000.  You

<blockquote>
INSERT INTO tab1 VALUES(?,?,?);
</blockquote>

<p>
Then use the
<a href="capi3ref.html#sqlite3_bind_text">sqlite3_bind_XXXX()</a> functions
to bind your large string values to the SQL statement.  The use of binding
obviates the need to escape quote characters in the string, reducing the
risk of SQL injection attacks.  It is also runs faster since the large
string does not need to be parsed or copied as much.
</p>
}

</p>
}

limititem {Maximum Number Of Host Parameters In A Single SQL Statement} {
<p>
A host parameter is a place-holder in an SQL statement that is filled
in using one of the
<a href="capi3ref.html#sqlite3_bind_blob">sqlite3_bind_XXXX()</a> interfaces.
Many SQL programmers are familiar with using a question mark ("?") as a
host parameter.  SQLite also supports named host parameters prefaced
by ":", "$", or "@" and numbered host parameters of the form "?123".
</p>

<p>
Each host parameter in an SQLite statement is assigned a number.  The

  regsub -all "\n( *\n)+" $text "</p>\n\n<p>" txt
  puts "<p>$txt</p>"
  puts "<hr width=\"50%\">"
}

newsitem {2007-Aug-13} {Version 3.4.2} {
  While stress-testing the 
  <a href="capi3ref.html#sqlite3_soft_heap_limit">soft_heap_limit</a>
  feature, a bug that could lead to
  <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption">database
  corruption</a> was <a href="http://www.sqlite.org/cvstrac/tktview?tn=2565">
  discovered and fixed</a>.
  Though the consequences of this bug are severe, the chances of hitting 
  it in a typical application are remote.  Upgrading is recommended
  only if you use the 
  <a href="capi3ref.html#sqlite3_soft_heap_limit">sqlite3_soft_heap_limit</a>
  interface.
}

newsitem {2007-Jly-20} {Version 3.4.1} {
  This release fixes a bug in <a href="lang_vacuum.html">VACUUM</a> that
  can lead to <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption">
  database corruption</a>.  The bug was introduced in version 

  use excessively large strings, BLOBs, tables, or SQL statements. 
  The new limits can be increased at compile-time to work around any problems
  that arise.  Nevertheless, the version number of this release is
  3.4.0 instead of 3.3.18 in order to call attention to the possible
  incompatibility.
  </p>
  There are also new features, including
  <a href="capi3ref.html#sqlite3_blob_open">incremental BLOB I/O</a> and
  <a href="pragma.html#pragma_incremental_vacuum">incremental vacuum</a>.
  See the <a href="changes.html#version_3_4_0">change log</a> 
  for additional information.
}

newsitem {2007-Apr-25} {Version 3.3.17} {
  This version fixes a bug in the forwards-compatibility logic of SQLite

newsitem {2007-Jan-4} {Version 3.3.9} {
  Version 3.3.9 fixes bugs that can lead to database corruption under
  obscure and difficult to reproduce circumstances.  See
  <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption">
  DatabaseCorruption</a> in the
  <a href="http://www.sqlite.org/cvstrac/wiki">wiki</a> for details.
  This release also adds the new
  <a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a>
  API and includes important bug fixes in the command-line
  shell and enhancements to the query optimizer.  Upgrading is
  recommended.
}

newsitem {2006-Oct-9} {Version 3.3.8} {
  Version 3.3.8 adds support for full-text search using the 

<li><p><b>PRAGMA read_uncommitted;
       <br>PRAGMA read_uncommitted = </b><i>0 | 1</i><b>;</b></p>
    <p>Query, set, or clear READ UNCOMMITTED isolation.  The default isolation
    level for SQLite is SERIALIZABLE.  Any process or thread can select
    READ UNCOMMITTED isolation, but SERIALIZABLE will still be used except
    between connections that share a common page and schema cache.
    Cache sharing is enabled using the
    <a href="capi3ref.html#sqlite3_enable_shared_cache">
    sqlite3_enable_shared_cache()</a> API and is only available between
    connections running the same thread.  Cache sharing is off by default.
    </p>
</li>

<a name="pragma_short_column_names"></a>
<li><p><b>PRAGMA short_column_names;

}

##############################################################################
METHOD cache {

<p>
The "eval" method described <a href="#eval">above</a> keeps a cache of
<a href="capi3ref.html#sqlite3_prepare">prepared statements</a>
for recently evaluated SQL commands.  
The "cache" method is used to control this cache.
The first form of this command is:</p>

<blockquote>
<i>dbcmd</i>&nbsp;&nbsp;<b>cache size</b>&nbsp;&nbsp;<i>N</i>
</blockquote>

<p>This sets the maximum number of statements that can be cached.
The upper limit is 100.  The default is 10.  If you set the cache size
to 0, no caching is done.</p>

<p>The second form of the command is this:</p>


<blockquote>
<i>dbcmd</i>&nbsp;&nbsp;<b>cache flush</b>
</blockquote>

<p>The cache-flush method 
<a href="capi3ref.html#sqlite3_finalize">finalizes</a>
all prepared statements currently
in the cache.</p>

}

##############################################################################
METHOD complete {

<p>
The "complete" method takes a string of supposed SQL as its only argument.
It returns TRUE if the string is a complete statement of SQL and FALSE if
there is more to be entered.</p>

<p>The "complete" method is useful when building interactive applications
in order to know when the user has finished entering a line of SQL code.
This is really just an interface to the 
<a href="capi3ref.html#sqlite3_complete"><b>sqlite3_complete()</b></a> C
function.
}

##############################################################################
METHOD copy {

<p>

current database connection was first opened.</p>
}

##############################################################################
METHOD authorizer {

<p>The "authorizer" method provides access to the 
<a href="capi3ref.html#sqlite3_set_authorizer">sqlite3_set_authorizer</a>
C/C++ interface.  The argument to authorizer is the name of a procedure that
is called when SQL statements are being compiled in order to authorize
certain operations.  The callback procedure takes 5 arguments which describe
the operation being coded.  If the callback returns the text string
"SQLITE_OK", then the operation is allowed.  If it returns "SQLITE_IGNORE",
then the operation is silently disabled.  If the return is "SQLITE_DENY"
then the compilation fails with an error.

<i>dbcmd</i>&nbsp;&nbsp;<b>incrblob</b>&nbsp;&nbsp;<b>?-readonly??</b>
&nbsp;&nbsp;<i>?DB?&nbsp;&nbsp;TABLE&nbsp;&nbsp;COLUMN&nbsp;&nbsp;ROWID</i>
</blockquote>

<p>
The command returns a new TCL channel for reading or writing to the BLOB.
The channel is opened using the underlying 
<a href="/capi3ref.html#sqlite3_blob_open">sqlite3_blob_open()</a> C-langauge
interface.  Close the channel using the <b>close</b> command of TCL.
</p>
}

##############################################################################
METHOD errorcode {