576 lines
26 KiB
HTML
576 lines
26 KiB
HTML
<!DOCTYPE html>
|
|
<html><head>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
|
|
<link href="sqlite.css" rel="stylesheet">
|
|
<title>An Introduction To The SQLite C/C++ Interface</title>
|
|
<!-- path= -->
|
|
</head>
|
|
<body>
|
|
<div class=nosearch>
|
|
<a href="index.html">
|
|
<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite" border="0">
|
|
</a>
|
|
<div><!-- IE hack to prevent disappearing logo --></div>
|
|
<div class="tagline desktoponly">
|
|
Small. Fast. Reliable.<br>Choose any three.
|
|
</div>
|
|
<div class="menu mainmenu">
|
|
<ul>
|
|
<li><a href="index.html">Home</a>
|
|
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
|
|
<li class='wideonly'><a href='about.html'>About</a>
|
|
<li class='desktoponly'><a href="docs.html">Documentation</a>
|
|
<li class='desktoponly'><a href="download.html">Download</a>
|
|
<li class='wideonly'><a href='copyright.html'>License</a>
|
|
<li class='desktoponly'><a href="support.html">Support</a>
|
|
<li class='desktoponly'><a href="prosupport.html">Purchase</a>
|
|
<li class='search' id='search_menubutton'>
|
|
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
|
|
</ul>
|
|
</div>
|
|
<div class="menu submenu" id="submenu">
|
|
<ul>
|
|
<li><a href='about.html'>About</a>
|
|
<li><a href='docs.html'>Documentation</a>
|
|
<li><a href='download.html'>Download</a>
|
|
<li><a href='support.html'>Support</a>
|
|
<li><a href='prosupport.html'>Purchase</a>
|
|
</ul>
|
|
</div>
|
|
<div class="searchmenu" id="searchmenu">
|
|
<form method="GET" action="search">
|
|
<select name="s" id="searchtype">
|
|
<option value="d">Search Documentation</option>
|
|
<option value="c">Search Changelog</option>
|
|
</select>
|
|
<input type="text" name="q" id="searchbox" value="">
|
|
<input type="submit" value="Go">
|
|
</form>
|
|
</div>
|
|
</div>
|
|
<script>
|
|
function toggle_div(nm) {
|
|
var w = document.getElementById(nm);
|
|
if( w.style.display=="block" ){
|
|
w.style.display = "none";
|
|
}else{
|
|
w.style.display = "block";
|
|
}
|
|
}
|
|
function toggle_search() {
|
|
var w = document.getElementById("searchmenu");
|
|
if( w.style.display=="block" ){
|
|
w.style.display = "none";
|
|
} else {
|
|
w.style.display = "block";
|
|
setTimeout(function(){
|
|
document.getElementById("searchbox").focus()
|
|
}, 30);
|
|
}
|
|
}
|
|
function div_off(nm){document.getElementById(nm).style.display="none";}
|
|
window.onbeforeunload = function(e){div_off("submenu");}
|
|
/* Disable the Search feature if we are not operating from CGI, since */
|
|
/* Search is accomplished using CGI and will not work without it. */
|
|
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
|
|
document.getElementById("search_menubutton").style.display = "none";
|
|
}
|
|
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
|
|
function hideorshow(btn,obj){
|
|
var x = document.getElementById(obj);
|
|
var b = document.getElementById(btn);
|
|
if( x.style.display!='none' ){
|
|
x.style.display = 'none';
|
|
b.innerHTML='show';
|
|
}else{
|
|
x.style.display = '';
|
|
b.innerHTML='hide';
|
|
}
|
|
return false;
|
|
}
|
|
</script>
|
|
</div>
|
|
<div class=fancy>
|
|
<div class=nosearch>
|
|
<div class="fancy_title">
|
|
An Introduction To The SQLite C/C++ Interface
|
|
</div>
|
|
<div class="fancy_toc">
|
|
<a onclick="toggle_toc()">
|
|
<span class="fancy_toc_mark" id="toc_mk">►</span>
|
|
Table Of Contents
|
|
</a>
|
|
<div id="toc_sub"><div class="fancy-toc1"><a href="#summary">1. Summary</a></div>
|
|
<div class="fancy-toc1"><a href="#introduction">2. Introduction</a></div>
|
|
<div class="fancy-toc1"><a href="#core_objects_and_interfaces">3. Core Objects And Interfaces</a></div>
|
|
<div class="fancy-toc1"><a href="#typical_usage_of_core_routines_and_objects">4. Typical Usage Of Core Routines And Objects</a></div>
|
|
<div class="fancy-toc1"><a href="#convenience_wrappers_around_core_routines">5. Convenience Wrappers Around Core Routines</a></div>
|
|
<div class="fancy-toc1"><a href="#binding_parameters_and_reusing_prepared_statements">6. Binding Parameters and Reusing Prepared Statements</a></div>
|
|
<div class="fancy-toc1"><a href="#configuring_sqlite">7. Configuring SQLite</a></div>
|
|
<div class="fancy-toc1"><a href="#extending_sqlite">8. Extending SQLite</a></div>
|
|
<div class="fancy-toc1"><a href="#other_interfaces">9. Other Interfaces</a></div>
|
|
</div>
|
|
</div>
|
|
<script>
|
|
function toggle_toc(){
|
|
var sub = document.getElementById("toc_sub")
|
|
var mk = document.getElementById("toc_mk")
|
|
if( sub.style.display!="block" ){
|
|
sub.style.display = "block";
|
|
mk.innerHTML = "▼";
|
|
} else {
|
|
sub.style.display = "none";
|
|
mk.innerHTML = "►";
|
|
}
|
|
}
|
|
</script>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h1 id="summary"><span>1. </span>Summary</h1>
|
|
|
|
<p>The following two objects and eight methods comprise the essential
|
|
elements of the SQLite interface:
|
|
|
|
</p><ul>
|
|
<li><p><b><a href="c3ref/sqlite3.html">sqlite3</a></b> →
|
|
The database connection object. Created by
|
|
<a href="c3ref/open.html">sqlite3_open()</a> and destroyed by <a href="c3ref/close.html">sqlite3_close()</a>.
|
|
|
|
</p></li><li><p><b><a href="c3ref/stmt.html">sqlite3_stmt</a></b> →
|
|
The prepared statement object. Created by
|
|
<a href="c3ref/prepare.html">sqlite3_prepare()</a> and destroyed by <a href="c3ref/finalize.html">sqlite3_finalize()</a>.
|
|
|
|
|
|
</p></li><li><p><b><a href="c3ref/open.html">sqlite3_open()</a></b> →
|
|
Open a connection to a new or existing SQLite database.
|
|
The constructor for <a href="c3ref/sqlite3.html">sqlite3</a>.
|
|
|
|
</p></li><li><p><b><a href="c3ref/prepare.html">sqlite3_prepare()</a></b> →
|
|
Compile SQL text into
|
|
byte-code that will do the work of querying or updating the database.
|
|
The constructor for <a href="c3ref/stmt.html">sqlite3_stmt</a>.
|
|
|
|
</p></li><li><p><b><a href="c3ref/bind_blob.html">sqlite3_bind()</a></b> →
|
|
Store application data into
|
|
<a href="lang_expr.html#varparam">parameters</a> of the original SQL.
|
|
|
|
|
|
</p></li><li><p><b><a href="c3ref/step.html">sqlite3_step()</a></b> →
|
|
Advance an <a href="c3ref/stmt.html">sqlite3_stmt</a> to the next result row or to completion.
|
|
|
|
</p></li><li><p><b><a href="c3ref/column_blob.html">sqlite3_column()</a></b> →
|
|
Column values in the current result row for an <a href="c3ref/stmt.html">sqlite3_stmt</a>.
|
|
|
|
</p></li><li><p><b><a href="c3ref/finalize.html">sqlite3_finalize()</a></b> →
|
|
Destructor for <a href="c3ref/stmt.html">sqlite3_stmt</a>.
|
|
|
|
</p></li><li><p><b><a href="c3ref/close.html">sqlite3_close()</a></b> →
|
|
Destructor for <a href="c3ref/sqlite3.html">sqlite3</a>.
|
|
|
|
</p></li><li><p><b><a href="c3ref/exec.html">sqlite3_exec()</a></b> →
|
|
A wrapper function that does <a href="c3ref/prepare.html">sqlite3_prepare()</a>, <a href="c3ref/step.html">sqlite3_step()</a>,
|
|
<a href="c3ref/column_blob.html">sqlite3_column()</a>, and <a href="c3ref/finalize.html">sqlite3_finalize()</a> for
|
|
a string of one or more SQL statements.
|
|
</p></li></ul>
|
|
|
|
<h1 id="introduction"><span>2. </span>Introduction</h1>
|
|
|
|
<p>
|
|
SQLite has more than 225 APIs.
|
|
However, most of the APIs are optional and very specialized
|
|
and can be ignored by beginners.
|
|
The core API is small, simple, and easy to learn.
|
|
This article summarizes the core API.
|
|
</p>
|
|
|
|
<p>
|
|
A separate document, <a href="c3ref/intro.html">The SQLite C/C++ Interface</a>,
|
|
provides detailed
|
|
specifications for all C/C++ APIs for SQLite. Once
|
|
the reader
|
|
understands the basic principles of operation for SQLite,
|
|
<a href="c3ref/intro.html">that document</a> should be used as a reference
|
|
guide. This article is intended as introduction only and is neither a
|
|
complete nor authoritative reference for the SQLite API.
|
|
</p>
|
|
|
|
<h1 id="core_objects_and_interfaces"><span>3. </span>Core Objects And Interfaces</h1>
|
|
|
|
<p>
|
|
The principal task of an SQL database engine is to evaluate SQL statements
|
|
of SQL. To accomplish this, the developer needs two objects:
|
|
</p>
|
|
|
|
<p></p><ul>
|
|
<li> The <a href="c3ref/sqlite3.html">database connection</a> object: sqlite3 </li>
|
|
<li> The <a href="c3ref/stmt.html">prepared statement</a> object: sqlite3_stmt </li>
|
|
</ul>
|
|
|
|
<p>
|
|
Strictly speaking, the <a href="c3ref/stmt.html">prepared statement</a> object is not required since
|
|
the convenience wrapper interfaces, <a href="c3ref/exec.html">sqlite3_exec</a> or
|
|
<a href="c3ref/free_table.html">sqlite3_get_table</a>, can be used and these convenience wrappers
|
|
encapsulate and hide the <a href="c3ref/stmt.html">prepared statement</a> object.
|
|
Nevertheless, an understanding of
|
|
<a href="c3ref/stmt.html">prepared statements</a> is needed to make full use of SQLite.
|
|
</p>
|
|
|
|
<p>
|
|
The <a href="c3ref/sqlite3.html">database connection</a> and <a href="c3ref/stmt.html">prepared statement</a> objects are controlled
|
|
by a small set of C/C++ interface routine listed below.
|
|
</p>
|
|
|
|
<p></p><ul>
|
|
<li> <a href="c3ref/open.html">sqlite3_open()</a> </li>
|
|
<li> <a href="c3ref/prepare.html">sqlite3_prepare()</a> </li>
|
|
<li> <a href="c3ref/step.html">sqlite3_step()</a> </li>
|
|
<li> <a href="c3ref/column_blob.html">sqlite3_column()</a> </li>
|
|
<li> <a href="c3ref/finalize.html">sqlite3_finalize()</a> </li>
|
|
<li> <a href="c3ref/close.html">sqlite3_close()</a> </li>
|
|
</ul>
|
|
|
|
<p>
|
|
Note that the list of routines above is conceptual rather than actual.
|
|
Many of these routines come in multiple versions.
|
|
For example, the list above shows a single routine
|
|
named <a href="c3ref/open.html">sqlite3_open()</a> when in fact there are three separate routines
|
|
that accomplish the same thing in slightly different ways:
|
|
<a href="c3ref/open.html">sqlite3_open()</a>, <a href="c3ref/open.html">sqlite3_open16()</a> and <a href="c3ref/open.html">sqlite3_open_v2()</a>.
|
|
The list mentions <a href="c3ref/column_blob.html">sqlite3_column()</a>
|
|
when in fact no such routine exists.
|
|
The "sqlite3_column()" shown in the list is a placeholder for
|
|
an entire family of routines that extra column
|
|
data in various datatypes.
|
|
</p>
|
|
|
|
<p>
|
|
Here is a summary of what the core interfaces do:
|
|
</p>
|
|
|
|
<ul>
|
|
|
|
<li><p><b><a href="c3ref/open.html">sqlite3_open()</a></b>
|
|
</p><p>
|
|
This routine
|
|
opens a connection to an SQLite database file and returns a
|
|
<a href="c3ref/sqlite3.html">database connection</a> object. This is often the first SQLite API
|
|
call that an application makes and is a prerequisite for most other
|
|
SQLite APIs. Many SQLite interfaces require a pointer to
|
|
the <a href="c3ref/sqlite3.html">database connection</a> object as their first parameter and can
|
|
be thought of as methods on the <a href="c3ref/sqlite3.html">database connection</a> object.
|
|
This routine is the constructor for the <a href="c3ref/sqlite3.html">database connection</a> object.
|
|
</p>
|
|
|
|
</li><li><p><b><a href="c3ref/prepare.html">sqlite3_prepare()</a></b>
|
|
</p><p>
|
|
This routine
|
|
converts SQL text into a <a href="c3ref/stmt.html">prepared statement</a> object and returns a pointer
|
|
to that object. This interface requires a <a href="c3ref/sqlite3.html">database connection</a> pointer
|
|
created by a prior call to <a href="c3ref/open.html">sqlite3_open()</a> 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><p>Think of each SQL statement as a small computer program. The purpose
|
|
of <a href="c3ref/prepare.html">sqlite3_prepare()</a> is to compile that program into object code.
|
|
The <a href="c3ref/stmt.html">prepared statement</a> is the object code. The <a href="c3ref/step.html">sqlite3_step()</a> interface
|
|
then runs the object code to get a result.
|
|
|
|
</p><p>New applications should always invoke <a href="c3ref/prepare.html">sqlite3_prepare_v2()</a> instead
|
|
of <a href="c3ref/prepare.html">sqlite3_prepare()</a>. The older <a href="c3ref/prepare.html">sqlite3_prepare()</a> is retained for
|
|
backwards compatibility. But <a href="c3ref/prepare.html">sqlite3_prepare_v2()</a> provides a much
|
|
better interface.</p>
|
|
|
|
</li><li><p><b><a href="c3ref/step.html">sqlite3_step()</a></b>
|
|
</p><p>
|
|
This routine is used to evaluate a <a href="c3ref/stmt.html">prepared statement</a> that has been
|
|
previously created by the <a href="c3ref/prepare.html">sqlite3_prepare()</a> interface. The statement
|
|
is evaluated up to the point where the first row of results are available.
|
|
To advance to the second row of results, invoke <a href="c3ref/step.html">sqlite3_step()</a> again.
|
|
Continue invoking <a href="c3ref/step.html">sqlite3_step()</a> until the statement is complete.
|
|
Statements that do not return results (ex: INSERT, UPDATE, or DELETE
|
|
statements) run to completion on a single call to <a href="c3ref/step.html">sqlite3_step()</a>.
|
|
|
|
</p></li><li><p><b><a href="c3ref/column_blob.html">sqlite3_column()</a></b>
|
|
</p><p>
|
|
This routine returns a single column from the current row of a result
|
|
set for a <a href="c3ref/stmt.html">prepared statement</a> that is being evaluated by <a href="c3ref/step.html">sqlite3_step()</a>.
|
|
Each time <a href="c3ref/step.html">sqlite3_step()</a> stops with a new result set row, this routine
|
|
can be called multiple times to find the values of all columns in that row.
|
|
|
|
</p><p>As noted above, there really is no such thing as a "sqlite3_column()"
|
|
function in the SQLite API. Instead, what we here call "sqlite3_column()"
|
|
is a place-holder for an entire family of functions that return
|
|
a value from the result set in various data types. There are also routines
|
|
in this family that return the size of the result (if it is a string or
|
|
BLOB) and the number of columns in the result set.
|
|
|
|
</p><p></p><ul>
|
|
<li> <a href="c3ref/column_blob.html">sqlite3_column_blob()</a> </li>
|
|
<li> <a href="c3ref/column_blob.html">sqlite3_column_bytes()</a> </li>
|
|
<li> <a href="c3ref/column_blob.html">sqlite3_column_bytes16()</a> </li>
|
|
<li> <a href="c3ref/column_count.html">sqlite3_column_count()</a> </li>
|
|
<li> <a href="c3ref/column_blob.html">sqlite3_column_double()</a> </li>
|
|
<li> <a href="c3ref/column_blob.html">sqlite3_column_int()</a> </li>
|
|
<li> <a href="c3ref/column_blob.html">sqlite3_column_int64()</a> </li>
|
|
<li> <a href="c3ref/column_blob.html">sqlite3_column_text()</a> </li>
|
|
<li> <a href="c3ref/column_blob.html">sqlite3_column_text16()</a> </li>
|
|
<li> <a href="c3ref/column_blob.html">sqlite3_column_type()</a> </li>
|
|
<li> <a href="c3ref/column_blob.html">sqlite3_column_value()</a> </li>
|
|
</ul>
|
|
|
|
|
|
</li><li><p><b><a href="c3ref/finalize.html">sqlite3_finalize()</a></b>
|
|
</p><p>
|
|
This routine destroys a <a href="c3ref/stmt.html">prepared statement</a> created by a prior call
|
|
to <a href="c3ref/prepare.html">sqlite3_prepare()</a>. Every prepared statement must be destroyed using
|
|
a call to this routine in order to avoid memory leaks.
|
|
|
|
</p></li><li><p><b><a href="c3ref/close.html">sqlite3_close()</a></b>
|
|
</p><p>
|
|
This routine closes a <a href="c3ref/sqlite3.html">database connection</a> previously opened by a call
|
|
to <a href="c3ref/open.html">sqlite3_open()</a>. All <a href="c3ref/stmt.html">prepared statements</a> associated with the
|
|
connection should be <a href="c3ref/finalize.html">finalized</a> prior to closing the
|
|
connection.
|
|
</p></li></ul>
|
|
|
|
<h1 id="typical_usage_of_core_routines_and_objects"><span>4. </span>Typical Usage Of Core Routines And Objects</h1>
|
|
|
|
<p>
|
|
An application will typically use
|
|
<a href="c3ref/open.html">sqlite3_open()</a> to create a single <a href="c3ref/sqlite3.html">database connection</a>
|
|
during initialization.
|
|
Note that <a href="c3ref/open.html">sqlite3_open()</a> can be used to either open existing database
|
|
files or to create and open new database files.
|
|
While many applications use only a single <a href="c3ref/sqlite3.html">database connection</a>, there is
|
|
no reason why an application cannot call <a href="c3ref/open.html">sqlite3_open()</a> multiple times
|
|
in order to open multiple <a href="c3ref/sqlite3.html">database connections</a> - either to the same
|
|
database or to different databases. Sometimes a multi-threaded application
|
|
will create separate <a href="c3ref/sqlite3.html">database connections</a> for each thread.
|
|
Note that a single <a href="c3ref/sqlite3.html">database connection</a> can access two or more
|
|
databases using the <a href="lang_attach.html">ATTACH</a> SQL command, so it is not necessary to
|
|
have a separate database connection for each database file.
|
|
</p>
|
|
|
|
<p>
|
|
Many applications destroy their <a href="c3ref/sqlite3.html">database connections</a> using calls to
|
|
<a href="c3ref/close.html">sqlite3_close()</a> at shutdown. Or, for example, an application that
|
|
uses SQLite as its <a href="appfileformat.html">application file format</a> might
|
|
open <a href="c3ref/sqlite3.html">database connections</a> in response to a File/Open menu action
|
|
and then destroy the corresponding <a href="c3ref/sqlite3.html">database connection</a> in response
|
|
to the File/Close menu.
|
|
</p>
|
|
|
|
<p>
|
|
To run an SQL statement, the application follows these steps:
|
|
</p>
|
|
|
|
<p></p><ol>
|
|
<li> Create a <a href="c3ref/stmt.html">prepared statement</a> using <a href="c3ref/prepare.html">sqlite3_prepare()</a>. </li>
|
|
<li> Evaluate the <a href="c3ref/stmt.html">prepared statement</a> by calling <a href="c3ref/step.html">sqlite3_step()</a> one
|
|
or more times. </li>
|
|
<li> For queries, extract results by calling
|
|
<a href="c3ref/column_blob.html">sqlite3_column()</a> in between
|
|
two calls to <a href="c3ref/step.html">sqlite3_step()</a>. </li>
|
|
<li> Destroy the <a href="c3ref/stmt.html">prepared statement</a> using <a href="c3ref/finalize.html">sqlite3_finalize()</a>. </li>
|
|
</ol>
|
|
|
|
<p>
|
|
The foregoing is all one really needs to know in order to use SQLite
|
|
effectively. All the rest is optimization and detail.
|
|
</p>
|
|
|
|
<h1 id="convenience_wrappers_around_core_routines"><span>5. </span>Convenience Wrappers Around Core Routines</h1>
|
|
|
|
<p>
|
|
The <a href="c3ref/exec.html">sqlite3_exec()</a> interface is a convenience wrapper that carries out
|
|
all four of the above steps with a single function call. A callback
|
|
function passed into <a href="c3ref/exec.html">sqlite3_exec()</a> is used to process each row of
|
|
the result set. The <a href="c3ref/free_table.html">sqlite3_get_table()</a> is another convenience wrapper
|
|
that does all four of the above steps. The <a href="c3ref/free_table.html">sqlite3_get_table()</a> interface
|
|
differs from <a href="c3ref/exec.html">sqlite3_exec()</a> in that it stores the results of queries
|
|
in heap memory rather than invoking a callback.
|
|
</p>
|
|
|
|
<p>
|
|
It is important to realize that neither <a href="c3ref/exec.html">sqlite3_exec()</a> nor
|
|
<a href="c3ref/free_table.html">sqlite3_get_table()</a> do anything that cannot be accomplished using
|
|
the core routines. In fact, these wrappers are implemented purely in
|
|
terms of the core routines.
|
|
</p>
|
|
|
|
|
|
<h1 id="binding_parameters_and_reusing_prepared_statements"><span>6. </span>Binding Parameters and Reusing Prepared Statements</h1>
|
|
|
|
<p>
|
|
In prior discussion, it was assumed that each SQL statement is prepared
|
|
once, evaluated, then destroyed. However, SQLite allows the same
|
|
<a href="c3ref/stmt.html">prepared statement</a> to be evaluated multiple times. This is accomplished
|
|
using the following routines:
|
|
</p>
|
|
|
|
<p></p><ul>
|
|
<li> <a href="c3ref/reset.html">sqlite3_reset()</a> </li>
|
|
<li> <a href="c3ref/bind_blob.html">sqlite3_bind()</a> </li>
|
|
</ul>
|
|
|
|
<p>
|
|
After a <a href="c3ref/stmt.html">prepared statement</a> has been evaluated by one or more calls to
|
|
<a href="c3ref/step.html">sqlite3_step()</a>, it can be reset in order to be evaluated again by a
|
|
call to <a href="c3ref/reset.html">sqlite3_reset()</a>.
|
|
Think of <a href="c3ref/reset.html">sqlite3_reset()</a> as rewinding the <a href="c3ref/stmt.html">prepared statement</a> program
|
|
back to the beginning.
|
|
Using <a href="c3ref/reset.html">sqlite3_reset()</a> on an existing <a href="c3ref/stmt.html">prepared statement</a> rather than
|
|
creating a new <a href="c3ref/stmt.html">prepared statement</a> avoids unnecessary calls to
|
|
<a href="c3ref/prepare.html">sqlite3_prepare()</a>.
|
|
For many SQL statements, the time needed
|
|
to run <a href="c3ref/prepare.html">sqlite3_prepare()</a> equals or exceeds the time needed by
|
|
<a href="c3ref/step.html">sqlite3_step()</a>. So avoiding calls to <a href="c3ref/prepare.html">sqlite3_prepare()</a> can give
|
|
a significant performance improvement.
|
|
</p>
|
|
|
|
<p>
|
|
It is not commonly useful to evaluate the <em>exact</em> same SQL
|
|
statement more than once. More often, one wants to evaluate similar
|
|
statements. For example, you might want to evaluate an INSERT statement
|
|
multiple times with different values. Or you might want to evaluate
|
|
the same query multiple times using a different key in the WHERE clause.
|
|
To accommodate
|
|
this, SQLite allows SQL statements to contain <a href="lang_expr.html#varparam">parameters</a>
|
|
which are "bound" to values prior to being evaluated. These values can
|
|
later be changed and the same <a href="c3ref/stmt.html">prepared statement</a> can be evaluated
|
|
a second time using the new values.
|
|
</p>
|
|
|
|
<p>
|
|
SQLite allows a <a href="lang_expr.html#varparam">parameter</a> wherever
|
|
a string literal, numeric constant, or NULL is allowed.
|
|
(Parameters may not be used for column or table names.)
|
|
A <a href="lang_expr.html#varparam">parameter</a> takes one of the following forms:
|
|
</p>
|
|
|
|
<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> <b>@</b><i>AAA</i> </li>
|
|
</ul>
|
|
|
|
<p>
|
|
In the examples above, <i>NNN</i> is an integer value and
|
|
<i>AAA</i> is an identifier.
|
|
A parameter initially has a value of NULL.
|
|
Prior to calling <a href="c3ref/step.html">sqlite3_step()</a> for the first time or immediately
|
|
after <a href="c3ref/reset.html">sqlite3_reset()</a>, the application can invoke the
|
|
<a href="c3ref/bind_blob.html">sqlite3_bind()</a> interfaces to attach values
|
|
to the parameters. Each call to <a href="c3ref/bind_blob.html">sqlite3_bind()</a>
|
|
overrides prior bindings on the same parameter.
|
|
</p>
|
|
|
|
<p>
|
|
An application is allowed to prepare multiple SQL statements in advance
|
|
and evaluate them as needed.
|
|
There is no arbitrary limit to the number of outstanding
|
|
<a href="c3ref/stmt.html">prepared statements</a>.
|
|
Some applications call <a href="c3ref/prepare.html">sqlite3_prepare()</a> multiple times at start-up to
|
|
create all of the <a href="c3ref/stmt.html">prepared statements</a> they will ever need. Other
|
|
applications keep a cache of the most recently used <a href="c3ref/stmt.html">prepared statements</a>
|
|
and then reuse <a href="c3ref/stmt.html">prepared statements</a> out of the cache when available.
|
|
Another approach is to only reuse <a href="c3ref/stmt.html">prepared statements</a> when they are
|
|
inside of a loop.
|
|
</p>
|
|
|
|
<h1 id="configuring_sqlite"><span>7. </span>Configuring SQLite</h1>
|
|
|
|
<p>
|
|
The default configuration for SQLite works great for most applications.
|
|
But sometimes developers want to tweak the setup to try to squeeze out
|
|
a little more performance, or take advantage of some obscure feature.
|
|
</p><p>
|
|
The <a href="c3ref/config.html">sqlite3_config()</a> interface is used to make global, process-wide
|
|
configuration changes for SQLite. The <a href="c3ref/config.html">sqlite3_config()</a> interface must
|
|
be called before any <a href="c3ref/sqlite3.html">database connections</a> are created. The
|
|
<a href="c3ref/config.html">sqlite3_config()</a> interface allows the programmer to do things like:
|
|
</p><ul>
|
|
<li>Adjust how SQLite does <a href="malloc.html">memory allocation</a>, including setting up
|
|
alternative memory allocators appropriate for safety-critical
|
|
real-time embedded systems and application-defined memory allocators.
|
|
</li><li>Set up a process-wide <a href="errlog.html">error log</a>.
|
|
</li><li>Specify an application-defined page cache.
|
|
</li><li>Adjust the use of mutexes so that they are appropriate for various
|
|
<a href="threadsafe.html">threading models</a>, or substitute an
|
|
application-defined mutex system.
|
|
</li></ul>
|
|
<p>
|
|
After process-wide configuration is complete and <a href="c3ref/sqlite3.html">database connections</a>
|
|
have been created, individual database connections can be configured using
|
|
calls to <a href="c3ref/limit.html">sqlite3_limit()</a> and <a href="c3ref/db_config.html">sqlite3_db_config()</a>.
|
|
|
|
</p><h1 id="extending_sqlite"><span>8. </span>Extending SQLite</h1>
|
|
|
|
<p>
|
|
SQLite includes interfaces that can be used to extend its functionality.
|
|
Such routines include:
|
|
</p>
|
|
|
|
<p></p><ul>
|
|
<li> <a href="c3ref/create_collation.html">sqlite3_create_collation()</a> </li>
|
|
<li> <a href="c3ref/create_function.html">sqlite3_create_function()</a> </li>
|
|
<li> <a href="c3ref/create_module.html">sqlite3_create_module()</a> </li>
|
|
<li> <a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a> </li>
|
|
</ul>
|
|
|
|
<p>
|
|
The <a href="c3ref/create_collation.html">sqlite3_create_collation()</a> interface is used to create new
|
|
<a href="datatype3.html#collation">collating sequences</a> for sorting text.
|
|
The <a href="c3ref/create_module.html">sqlite3_create_module()</a> interface is used to register new
|
|
<a href="vtab.html">virtual table</a> implementations.
|
|
The <a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a> interface creates new <a href="vfs.html">VFSes</a>.
|
|
</p>
|
|
|
|
<p>
|
|
The <a href="c3ref/create_function.html">sqlite3_create_function()</a> interface creates new SQL functions -
|
|
either scalar or aggregate. The new function implementation typically
|
|
makes use of the following additional interfaces:
|
|
</p>
|
|
|
|
<p></p><ul>
|
|
<li> <a href="c3ref/aggregate_context.html">sqlite3_aggregate_context()</a> </li>
|
|
<li> <a href="c3ref/result_blob.html">sqlite3_result()</a> </li>
|
|
<li> <a href="c3ref/user_data.html">sqlite3_user_data()</a> </li>
|
|
<li> <a href="c3ref/value_blob.html">sqlite3_value()</a> </li>
|
|
</ul>
|
|
|
|
<p>
|
|
All of the built-in SQL functions of SQLite are created using exactly
|
|
these same interfaces. Refer to the SQLite source code, and in particular
|
|
the
|
|
<a href="http://www.sqlite.org/src/doc/trunk/src/date.c">date.c</a> and
|
|
<a href="http://www.sqlite.org/src/doc/trunk/src/func.c">func.c</a> source files
|
|
for examples.
|
|
</p>
|
|
|
|
<p>
|
|
Shared libraries or DLLs can be used as <a href="loadext.html">loadable extensions</a> to SQLite.
|
|
|
|
</p><h1 id="other_interfaces"><span>9. </span>Other Interfaces</h1>
|
|
|
|
<p>
|
|
This article only mentions the most important and most commonly
|
|
used SQLite interfaces.
|
|
The SQLite library includes many other APIs implementing useful
|
|
features that are not described here.
|
|
A <a href="c3ref/funclist.html">complete list of functions</a> that form the SQLite
|
|
application programming interface is found at the
|
|
<a href="c3ref/intro.html">C/C++ Interface Specification</a>.
|
|
Refer to that document for complete and authoritative information about
|
|
all SQLite interfaces.
|
|
</p>
|
|
|