| 1 |
<!DOCTYPE html> |
| 2 |
<html><head> |
| 3 |
<meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| 4 |
<meta http-equiv="content-type" content="text/html; charset=UTF-8"> |
| 5 |
<link href="sqlite.css" rel="stylesheet"> |
| 6 |
<title>Compile-time Options</title> |
| 7 |
<!-- path= --> |
| 8 |
</head> |
| 9 |
<body> |
| 10 |
<div class=nosearch> |
| 11 |
<a href="index.html"> |
| 12 |
<img class="logo" src="images/sqlite370_banner.svg" alt="SQLite" border="0"> |
| 13 |
</a> |
| 14 |
<div><!-- IE hack to prevent disappearing logo --></div> |
| 15 |
<div class="tagline desktoponly"> |
| 16 |
Small. Fast. Reliable.<br>Choose any three. |
| 17 |
</div> |
| 18 |
<div class="menu mainmenu"> |
| 19 |
<ul> |
| 20 |
<li><a href="index.html">Home</a> |
| 21 |
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a> |
| 22 |
<li class='wideonly'><a href='about.html'>About</a> |
| 23 |
<li class='desktoponly'><a href="docs.html">Documentation</a> |
| 24 |
<li class='desktoponly'><a href="download.html">Download</a> |
| 25 |
<li class='wideonly'><a href='copyright.html'>License</a> |
| 26 |
<li class='desktoponly'><a href="support.html">Support</a> |
| 27 |
<li class='desktoponly'><a href="prosupport.html">Purchase</a> |
| 28 |
<li class='search' id='search_menubutton'> |
| 29 |
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a> |
| 30 |
</ul> |
| 31 |
</div> |
| 32 |
<div class="menu submenu" id="submenu"> |
| 33 |
<ul> |
| 34 |
<li><a href='about.html'>About</a> |
| 35 |
<li><a href='docs.html'>Documentation</a> |
| 36 |
<li><a href='download.html'>Download</a> |
| 37 |
<li><a href='support.html'>Support</a> |
| 38 |
<li><a href='prosupport.html'>Purchase</a> |
| 39 |
</ul> |
| 40 |
</div> |
| 41 |
<div class="searchmenu" id="searchmenu"> |
| 42 |
<form method="GET" action="search"> |
| 43 |
<select name="s" id="searchtype"> |
| 44 |
<option value="d">Search Documentation</option> |
| 45 |
<option value="c">Search Changelog</option> |
| 46 |
</select> |
| 47 |
<input type="text" name="q" id="searchbox" value=""> |
| 48 |
<input type="submit" value="Go"> |
| 49 |
</form> |
| 50 |
</div> |
| 51 |
</div> |
| 52 |
<script> |
| 53 |
function toggle_div(nm) { |
| 54 |
var w = document.getElementById(nm); |
| 55 |
if( w.style.display=="block" ){ |
| 56 |
w.style.display = "none"; |
| 57 |
}else{ |
| 58 |
w.style.display = "block"; |
| 59 |
} |
| 60 |
} |
| 61 |
function toggle_search() { |
| 62 |
var w = document.getElementById("searchmenu"); |
| 63 |
if( w.style.display=="block" ){ |
| 64 |
w.style.display = "none"; |
| 65 |
} else { |
| 66 |
w.style.display = "block"; |
| 67 |
setTimeout(function(){ |
| 68 |
document.getElementById("searchbox").focus() |
| 69 |
}, 30); |
| 70 |
} |
| 71 |
} |
| 72 |
function div_off(nm){document.getElementById(nm).style.display="none";} |
| 73 |
window.onbeforeunload = function(e){div_off("submenu");} |
| 74 |
/* Disable the Search feature if we are not operating from CGI, since */ |
| 75 |
/* Search is accomplished using CGI and will not work without it. */ |
| 76 |
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){ |
| 77 |
document.getElementById("search_menubutton").style.display = "none"; |
| 78 |
} |
| 79 |
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */ |
| 80 |
function hideorshow(btn,obj){ |
| 81 |
var x = document.getElementById(obj); |
| 82 |
var b = document.getElementById(btn); |
| 83 |
if( x.style.display!='none' ){ |
| 84 |
x.style.display = 'none'; |
| 85 |
b.innerHTML='show'; |
| 86 |
}else{ |
| 87 |
x.style.display = ''; |
| 88 |
b.innerHTML='hide'; |
| 89 |
} |
| 90 |
return false; |
| 91 |
} |
| 92 |
var antiRobot = 0; |
| 93 |
function antiRobotGo(){ |
| 94 |
if( antiRobot!=3 ) return; |
| 95 |
antiRobot = 7; |
| 96 |
var j = document.getElementById("mtimelink"); |
| 97 |
if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href"); |
| 98 |
} |
| 99 |
function antiRobotDefense(){ |
| 100 |
document.body.onmousedown=function(){ |
| 101 |
antiRobot |= 2; |
| 102 |
antiRobotGo(); |
| 103 |
document.body.onmousedown=null; |
| 104 |
} |
| 105 |
document.body.onmousemove=function(){ |
| 106 |
antiRobot |= 2; |
| 107 |
antiRobotGo(); |
| 108 |
document.body.onmousemove=null; |
| 109 |
} |
| 110 |
setTimeout(function(){ |
| 111 |
antiRobot |= 1; |
| 112 |
antiRobotGo(); |
| 113 |
}, 100) |
| 114 |
antiRobotGo(); |
| 115 |
} |
| 116 |
antiRobotDefense(); |
| 117 |
</script> |
| 118 |
<div class=fancy> |
| 119 |
<div class=nosearch> |
| 120 |
<div class="fancy_title"> |
| 121 |
Compile-time Options |
| 122 |
</div> |
| 123 |
<details class="fancy_toc"> |
| 124 |
<summary>Table Of Contents</summary> |
| 125 |
<div id="toc_sub"><div class="fancy-toc1"><a href="#overview">1. Overview</a></div> |
| 126 |
<div class="fancy-toc1"><a href="#recommended_compile_time_options">2. Recommended Compile-time Options</a></div> |
| 127 |
<div class="fancy-toc1"><a href="#_platform_configuration">3. Platform Configuration</a></div> |
| 128 |
<div class="fancy-toc1"><a href="#_options_to_set_default_parameter_values">4. Options To Set Default Parameter Values</a></div> |
| 129 |
<div class="fancy-toc1"><a href="#_options_to_set_size_limits">5. Options To Set Size Limits</a></div> |
| 130 |
<div class="fancy-toc1"><a href="#_options_to_control_operating_characteristics">6. Options To Control Operating Characteristics</a></div> |
| 131 |
<div class="fancy-toc1"><a href="#_options_to_enable_features_normally_turned_off">7. Options To Enable Features Normally Turned Off</a></div> |
| 132 |
<div class="fancy-toc1"><a href="#_options_to_disable_features_normally_turned_on">8. Options To Disable Features Normally Turned On</a></div> |
| 133 |
<div class="fancy-toc1"><a href="#_options_to_omit_features">9. Options To Omit Features</a></div> |
| 134 |
<div class="fancy-toc1"><a href="#_analysis_and_debugging_options">10. Analysis and Debugging Options</a></div> |
| 135 |
<div class="fancy-toc1"><a href="#_windows_specific_options">11. Windows-Specific Options</a></div> |
| 136 |
<div class="fancy-toc1"><a href="#compiler_linkage_and_calling_convention_control">12. Compiler Linkage and Calling Convention Control</a></div> |
| 137 |
</div> |
| 138 |
</details> |
| 139 |
</div> |
| 140 |
|
| 141 |
|
| 142 |
|
| 143 |
|
| 144 |
|
| 145 |
<h1 id="overview"><span>1. </span>Overview</h1> |
| 146 |
|
| 147 |
<p> |
| 148 |
For most purposes, SQLite can be built just fine using the default |
| 149 |
compilation options. However, if required, the compile-time options |
| 150 |
documented below can be used to |
| 151 |
<a href="#omitfeatures">omit SQLite features</a> (resulting in |
| 152 |
a <a href="footprint.html">smaller compiled library size</a>) or to change the |
| 153 |
<a href="#defaults">default values</a> of some parameters. |
| 154 |
</p> |
| 155 |
|
| 156 |
<p> |
| 157 |
Every effort has been made to ensure that the various combinations |
| 158 |
of compilation options work harmoniously and produce a working library. |
| 159 |
Nevertheless, it is strongly recommended that the SQLite test-suite |
| 160 |
be executed to check for errors before using an SQLite library built |
| 161 |
with non-standard compilation options. |
| 162 |
</p> |
| 163 |
|
| 164 |
<p> |
| 165 |
The <a href="pragma.html#pragma_compile_options">compile_options |
| 166 |
pragma</a> can be used to determine which of the options listed below |
| 167 |
were used in building a given copy of SQLite. |
| 168 |
</p> |
| 169 |
|
| 170 |
<a name="rcmd"></a> |
| 171 |
|
| 172 |
|
| 173 |
<h1 id="recommended_compile_time_options"><span>2. </span>Recommended Compile-time Options</h1> |
| 174 |
|
| 175 |
<p>The following compile-time options are recommended for applications that |
| 176 |
are able to use them, in order to minimized the number of CPU cycles and |
| 177 |
the bytes of memory used by SQLite. |
| 178 |
Not all of these compile-time options are usable by every application. |
| 179 |
For example, the SQLITE_THREADSAFE=0 option is only usable by applications |
| 180 |
that never access SQLite from more than one thread at a time. And the |
| 181 |
SQLITE_OMIT_PROGRESS_CALLBACK option is only usable by applications that |
| 182 |
do not use the <a href="c3ref/progress_handler.html">sqlite3_progress_handler()</a> interface. And so forth. |
| 183 |
|
| 184 |
</p><p>It is impossible to test every possible combination of compile-time |
| 185 |
options for SQLite. But the following set of compile-time options is |
| 186 |
one configuration that is always fully tested. |
| 187 |
|
| 188 |
</p><ol> |
| 189 |
<li><p><b><a href="compile.html#dqs">SQLITE_DQS=0</a></b>. |
| 190 |
This setting disables the <a href="quirks.html#dblquote">double-quoted string literal</a> misfeature. |
| 191 |
|
| 192 |
</p></li><li><p><b><a href="compile.html#threadsafe">SQLITE_THREADSAFE=0</a></b>. |
| 193 |
Setting -DSQLITE_THREADSAFE=0 causes all of the mutex and thread-safety logic |
| 194 |
in SQLite to be omitted. This is the single compile-time option causes SQLite |
| 195 |
to run about 2% faster and also reduces the size of the library by about 2%. |
| 196 |
But the downside is that using the compile-time option means that SQLite can never |
| 197 |
be used by more than a single thread at a time, even if each thread has its own |
| 198 |
database connection. |
| 199 |
|
| 200 |
</p></li><li><p><b><a href="compile.html#default_memstatus">SQLITE_DEFAULT_MEMSTATUS=0</a></b>. |
| 201 |
This setting causes the <a href="c3ref/status.html">sqlite3_status()</a> interfaces that track memory usage |
| 202 |
to be disabled. This helps the <a href="c3ref/free.html">sqlite3_malloc()</a> routines run much faster, |
| 203 |
and since SQLite uses <a href="c3ref/free.html">sqlite3_malloc()</a> internally, this helps to make the |
| 204 |
entire library faster. |
| 205 |
|
| 206 |
</p></li><li><p><b><a href="compile.html#default_wal_synchronous">SQLITE_DEFAULT_WAL_SYNCHRONOUS=1</a></b>. |
| 207 |
For maximum database safety following a power loss, the setting of |
| 208 |
<a href="pragma.html#pragma_synchronous">PRAGMA synchronous=FULL</a> is recommended. However, in <a href="wal.html">WAL mode</a>, complete |
| 209 |
database integrity is guaranteed with <a href="pragma.html#pragma_synchronous">PRAGMA synchronous=NORMAL</a>. With |
| 210 |
<a href="pragma.html#pragma_synchronous">PRAGMA synchronous=NORMAL</a> in <a href="wal.html">WAL mode</a>, recent changes to the database might |
| 211 |
be rolled back by a power loss, but the database will not be corrupted. |
| 212 |
Furthermore, transaction commit is much faster in WAL mode using |
| 213 |
synchronous=NORMAL than with the default synchronous=FULL. For these |
| 214 |
reasons, it is recommended that the synchronous setting be changed from |
| 215 |
FULL to NORMAL when switching to WAL mode. This compile-time option will |
| 216 |
accomplish that. |
| 217 |
|
| 218 |
</p></li><li><p><b><a href="compile.html#like_doesnt_match_blobs">SQLITE_LIKE_DOESNT_MATCH_BLOBS</a></b>. |
| 219 |
Historically, SQLite has allowed BLOB operands to the <a href="lang_expr.html#like">LIKE</a> and <a href="lang_expr.html#glob">GLOB</a> |
| 220 |
operators. But having a BLOB as an operand of <a href="lang_expr.html#like">LIKE</a> or <a href="lang_expr.html#glob">GLOB</a> complicates |
| 221 |
and slows the <a href="optoverview.html#like_opt">LIKE optimization</a>. When this option is set, it means that |
| 222 |
the LIKE and GLOB operators always return FALSE if either operand is a BLOB. |
| 223 |
That simplifies the implementation of the <a href="optoverview.html#like_opt">LIKE optimization</a> and allows |
| 224 |
queries that use the <a href="optoverview.html#like_opt">LIKE optimization</a> to run faster. |
| 225 |
|
| 226 |
</p></li><li><p><b><a href="limits.html#max_expr_depth">SQLITE_MAX_EXPR_DEPTH=0</a></b>. |
| 227 |
Setting the maximum expression parse-tree depth to zero disables all checking |
| 228 |
of the expression parse-tree depth, which simplifies the code resulting in |
| 229 |
faster execution, and helps the parse tree to use less memory. |
| 230 |
|
| 231 |
</p></li><li><p><b><a href="compile.html#omit_decltype">SQLITE_OMIT_DECLTYPE</a></b>. |
| 232 |
By omitting the (seldom-needed) ability to return the declared type of |
| 233 |
columns from the result set of query, <a href="c3ref/stmt.html">prepared statements</a> can be made |
| 234 |
to consume less memory. |
| 235 |
|
| 236 |
</p></li><li><p><b><a href="compile.html#omit_deprecated">SQLITE_OMIT_DEPRECATED</a></b>. |
| 237 |
Omitting deprecated interfaces and features will not help SQLite to |
| 238 |
run any faster. It will reduce the library footprint, however. And |
| 239 |
it is the right thing to do. |
| 240 |
|
| 241 |
</p></li><li><p><b><a href="compile.html#omit_progress_callback">SQLITE_OMIT_PROGRESS_CALLBACK</a></b>. |
| 242 |
The progress handler callback counter must be checked in the inner loop |
| 243 |
of the <a href="opcode.html">bytecode engine</a>. By omitting this interface, a single conditional |
| 244 |
is removed from the inner loop of the <a href="opcode.html">bytecode engine</a>, helping SQL statements |
| 245 |
to run slightly faster. |
| 246 |
|
| 247 |
</p></li><li><p><b><a href="compile.html#omit_shared_cache">SQLITE_OMIT_SHARED_CACHE</a></b>. |
| 248 |
Omitting the possibility of using <a href="sharedcache.html">shared cache</a> allows many conditionals |
| 249 |
in performance-critical sections of the code to be eliminated. This can |
| 250 |
give a noticeable improvement in performance. |
| 251 |
|
| 252 |
</p></li><li><p><b><a href="compile.html#omit_autoinit">SQLITE_OMIT_AUTOINIT</a></b>. |
| 253 |
The SQLite library needs to be initialized using a call to |
| 254 |
<a href="c3ref/initialize.html">sqlite3_initialize()</a> before certain interfaces are used. |
| 255 |
This initialization normally happens automatically the first time |
| 256 |
it is needed. However, with the SQLITE_OMIT_AUTOINIT option, the automatic |
| 257 |
initialization is omitted. This helps many API calls to run a little faster |
| 258 |
(since they do not have to check to see if initialization has already occurred |
| 259 |
and then run initialization if it has not previously been invoked) but it |
| 260 |
also means that the application must call <a href="c3ref/initialize.html">sqlite3_initialize()</a> manually. |
| 261 |
If SQLite is compiled with -DSQLITE_OMIT_AUTOINIT and a routine like |
| 262 |
<a href="c3ref/free.html">sqlite3_malloc()</a> or <a href="c3ref/vfs_find.html">sqlite3_vfs_find()</a> or <a href="c3ref/open.html">sqlite3_open()</a> is invoked |
| 263 |
without first calling <a href="c3ref/initialize.html">sqlite3_initialize()</a>, the likely result will be |
| 264 |
a segfault. |
| 265 |
|
| 266 |
</p></li><li><p><b><a href="compile.html#strict_subtype">SQLITE_STRICT_SUBTYPE=1</a></b>. |
| 267 |
This option causes an error to be raised if an application defined |
| 268 |
function that does not have the <a href="c3ref/c_deterministic.html#sqliteresultsubtype">SQLITE_RESULT_SUBTYPE</a> property |
| 269 |
invokes the <a href="c3ref/result_subtype.html">sqlite3_result_subtype()</a> interface. The sqlite3_result_subtype() |
| 270 |
interface does not work reliably unless the function is registered |
| 271 |
with the SQLITE_RESULT_SUBTYPE property. This compile-time option |
| 272 |
is designed to bring this problem to the attention of developers |
| 273 |
early. |
| 274 |
</p></li></ol> |
| 275 |
|
| 276 |
<p>When all of the recommended compile-time options above are used, |
| 277 |
the SQLite library will be approximately 3% smaller and use about 5% fewer |
| 278 |
CPU cycles. So these options do not make a huge difference. But in |
| 279 |
some design situations, every little bit helps. |
| 280 |
|
| 281 |
</p><p>Library-level configuration options, such as those listed above, |
| 282 |
may optionally be defined in a client-side header file. Defining |
| 283 |
SQLITE_CUSTOM_INCLUDE=myconfig.h (with no quotes) will cause sqlite3.c |
| 284 |
to include myconfig.h early on in the compilation process, enabling |
| 285 |
the client to customize the flags without having to explicitly pass |
| 286 |
all of them to the compiler. |
| 287 |
|
| 288 |
<a name="osconfig"></a> |
| 289 |
</p><h1 id="_platform_configuration"><span>3. </span> Platform Configuration</h1> |
| 290 |
|
| 291 |
<a name="sqlite_config_h"></a> |
| 292 |
<p><b>_HAVE_SQLITE_CONFIG_H</b></p><blockquote><p> |
| 293 |
If the _HAVE_SQLITE_CONFIG_H macro is defined |
| 294 |
then the SQLite source code will attempt to #include a file named "sqlite_cfg.h". |
| 295 |
The "sqlite_cfg.h" file usually contains other configuration options, especially |
| 296 |
"HAVE_<i>INTERFACE</i>" type options generated by the configure process. Note that this |
| 297 |
header is intended only for use for platform-level configuration, not library-level |
| 298 |
configuration. To set SQLite-level configuration flags in a custom header, define |
| 299 |
SQLITE_CUSTOM_INCLUDE=myconfig.h, as described in the previous section. |
| 300 |
</p></blockquote><a name="fdatasync"></a> |
| 301 |
<p><b>HAVE_FDATASYNC</b></p><blockquote><p> |
| 302 |
If the HAVE_FDATASYNC compile-time option is true, then the default <a href="vfs.html">VFS</a> |
| 303 |
for unix systems will attempt to use fdatasync() instead of fsync() where |
| 304 |
appropriate. If this flag is missing or false, then fsync() is always used. |
| 305 |
</p></blockquote><a name="gmtime_r"></a> |
| 306 |
<p><b>HAVE_GMTIME_R</b></p><blockquote><p> |
| 307 |
If the HAVE_GMTIME_R option is true and if <a href="compile.html#omit_datetime_funcs">SQLITE_OMIT_DATETIME_FUNCS</a> is true, |
| 308 |
then the CURRENT_TIME, CURRENT_DATE, and CURRENT_TIMESTAMP keywords will use |
| 309 |
the threadsafe "gmtime_r()" interface rather than "gmtime()". In the usual case |
| 310 |
where <a href="compile.html#omit_datetime_funcs">SQLITE_OMIT_DATETIME_FUNCS</a> is not defined or is false, then the |
| 311 |
built-in <a href="lang_datefunc.html">date and time functions</a> are used to implement the CURRENT_TIME, |
| 312 |
CURRENT_DATE, and CURRENT_TIMESTAMP keywords and neither gmtime_r() nor |
| 313 |
gmtime() is ever called. |
| 314 |
</p></blockquote><a name="isnan"></a> |
| 315 |
<p><b>HAVE_ISNAN</b></p><blockquote><p> |
| 316 |
If the HAVE_ISNAN option is true, then SQLite invokes the system library isnan() |
| 317 |
function to determine if a double-precision floating point value is a NaN. |
| 318 |
If HAVE_ISNAN is undefined or false, then SQLite substitutes its own home-grown |
| 319 |
implementation of isnan(). |
| 320 |
</p></blockquote><a name="localtime_r"></a> |
| 321 |
<p><b>HAVE_LOCALTIME_R</b></p><blockquote><p> |
| 322 |
If the HAVE_LOCALTIME_R option is true, then SQLite uses the threadsafe |
| 323 |
localtime_r() library routine instead of localtime() |
| 324 |
to help implement the <a href="lang_datefunc.html#localtime">localtime modifier</a> |
| 325 |
to the built-in <a href="lang_datefunc.html">date and time functions</a>. |
| 326 |
</p></blockquote><a name="localtime_s"></a> |
| 327 |
<p><b>HAVE_LOCALTIME_S</b></p><blockquote><p> |
| 328 |
If the HAVE_LOCALTIME_S option is true, then SQLite uses the threadsafe |
| 329 |
localtime_s() library routine instead of localtime() |
| 330 |
to help implement the <a href="lang_datefunc.html#localtime">localtime modifier</a> |
| 331 |
to the built-in <a href="lang_datefunc.html">date and time functions</a>. |
| 332 |
</p></blockquote><a name="malloc_usable_size"></a> |
| 333 |
<p><b>HAVE_MALLOC_USABLE_SIZE</b></p><blockquote><p> |
| 334 |
If the HAVE_MALLOC_USABLE_SIZE option is true, then SQLite uses the |
| 335 |
malloc_usable_size() interface to find the size of a memory allocation obtained |
| 336 |
from the standard-library malloc() or realloc() routines. This option is only |
| 337 |
applicable if the standard-library malloc() is used. On Apple systems, |
| 338 |
"zone malloc" is used instead, and so this option is not applicable. And, of |
| 339 |
course, if the application supplies its own malloc implementation using |
| 340 |
<a href="c3ref/c_config_covering_index_scan.html#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a> then this option has no effect. |
| 341 |
<p> |
| 342 |
If the HAVE_MALLOC_USABLE_SIZE option is omitted or is false, then SQLite |
| 343 |
uses a wrapper around system malloc() and realloc() that enlarges each allocation |
| 344 |
by 8 bytes and writes the size of the allocation in the initial 8 bytes, and |
| 345 |
then SQLite also implements its own home-grown version of malloc_usable_size() |
| 346 |
that consults that 8-byte prefix to find the allocation size. This approach |
| 347 |
works but it is suboptimal. Applications are encouraged to use |
| 348 |
HAVE_MALLOC_USABLE_SIZE whenever possible. |
| 349 |
</p></blockquote><a name="strchrnul"></a> |
| 350 |
<p><b>HAVE_STRCHRNUL</b></p><blockquote><p> |
| 351 |
If the HAVE_STRCHRNUL option is true, then SQLite uses the strchrnul() library |
| 352 |
function. If this option is missing or false, then SQLite substitutes its own |
| 353 |
home-grown implementation of strchrnul(). |
| 354 |
</p></blockquote><a name="utime"></a> |
| 355 |
<p><b>HAVE_UTIME</b></p><blockquote><p> |
| 356 |
If the HAVE_UTIME option is true, then the built-in but non-standard |
| 357 |
"unix-dotfile" VFS will use the utime() system call, instead of utimes(), |
| 358 |
to set the last access time on the lock file. |
| 359 |
</p></blockquote><a name="byteorder"></a> |
| 360 |
<p><b>SQLITE_BYTEORDER=<i>(0|1234|4321)</i></b></p><blockquote><p> |
| 361 |
SQLite needs to know if the native byte order of the target CPU is |
| 362 |
big-endian or little-endian. The SQLITE_BYTEORDER preprocessor is set |
| 363 |
to 4321 for big-endian machines and 1234 for little-endian machines, or |
| 364 |
it can be 0 to mean that the byte order must be determined at run-time. |
| 365 |
There are #ifdefs in the code that set SQLITE_BYTEORDER automatically |
| 366 |
for all common platforms and compilers. However, it may be advantageous |
| 367 |
to set SQLITE_BYTEORDER appropriately when compiling SQLite for obscure |
| 368 |
targets. If the target byte order cannot be determined at compile-time, |
| 369 |
then SQLite falls back to doing run-time checks, which always work, though |
| 370 |
with a small performance penalty. |
| 371 |
</p></blockquote> |
| 372 |
|
| 373 |
<a name="defaults"></a> |
| 374 |
<h1 id="_options_to_set_default_parameter_values"><span>4. </span> Options To Set Default Parameter Values</h1> |
| 375 |
|
| 376 |
<a name="default_automatic_index"></a> |
| 377 |
<p><b>SQLITE_DEFAULT_AUTOMATIC_INDEX=<i><0 or 1></i></b></p><blockquote><p> |
| 378 |
This macro determines the initial setting for <a href="pragma.html#pragma_automatic_index">PRAGMA automatic_index</a> |
| 379 |
for newly opened <a href="c3ref/sqlite3.html">database connections</a>. |
| 380 |
For all versions of SQLite through 3.7.17, |
| 381 |
automatic indices are normally enabled for new database connections if |
| 382 |
this compile-time option is omitted. |
| 383 |
However, that might change in future releases of SQLite. |
| 384 |
<p>See also: <a href="compile.html#omit_automatic_index">SQLITE_OMIT_AUTOMATIC_INDEX</a> |
| 385 |
</p></blockquote><a name="default_autovacuum"></a> |
| 386 |
<p><b>SQLITE_DEFAULT_AUTOVACUUM=<i><0 or 1 or 2></i></b></p><blockquote><p> |
| 387 |
This macro determines if SQLite creates databases with the |
| 388 |
<a href="pragma.html#pragma_auto_vacuum">auto_vacuum</a> flag set by default to OFF (0), FULL (1), or |
| 389 |
INCREMENTAL (2). The default value is 0 meaning that databases |
| 390 |
are created with auto-vacuum turned off. |
| 391 |
In any case the compile-time default may be overridden by the |
| 392 |
<a href="pragma.html#pragma_auto_vacuum">PRAGMA auto_vacuum</a> command. |
| 393 |
</p></blockquote><a name="default_cache_size"></a> |
| 394 |
<p><b>SQLITE_DEFAULT_CACHE_SIZE=<i><N></i></b></p><blockquote><p> |
| 395 |
This macro sets the default maximum size of the page-cache for each attached |
| 396 |
database. A positive value means that the limit is N page. If N is negative |
| 397 |
that means to limit the cache size to -N*1024 bytes. |
| 398 |
The suggested maximum cache size can be overridden by the |
| 399 |
<a href="pragma.html#pragma_cache_size">PRAGMA cache_size</a> command. The default value is -2000, which translates |
| 400 |
into a maximum of 2048000 bytes per cache. |
| 401 |
</p></blockquote><a name="default_file_format"></a> |
| 402 |
<p><b>SQLITE_DEFAULT_FILE_FORMAT=<i><1 or 4></i></b></p><blockquote><p> |
| 403 |
The default <a href="fileformat2.html#schemaformat">schema format number</a> used by SQLite when creating |
| 404 |
new database files is set by this macro. The schema formats are all |
| 405 |
very similar. The difference between formats 1 and 4 is that format |
| 406 |
4 understands <a href="lang_createindex.html#descidx">descending indices</a> and has a tighter encoding for |
| 407 |
boolean values.</p> |
| 408 |
|
| 409 |
<p> All versions of SQLite since 3.3.0 (2006-01-10) |
| 410 |
can read and write any schema format |
| 411 |
between 1 and 4. But older versions of SQLite might not be able to |
| 412 |
read formats greater than 1. So that older versions of SQLite will |
| 413 |
be able to read and write database files created by newer versions |
| 414 |
of SQLite, the default schema format was set to 1 for SQLite versions |
| 415 |
through 3.7.9 (2011-11-01). Beginning with |
| 416 |
<a href="releaselog/3_7_10.html">version 3.7.10</a> (2012-01-16), the default |
| 417 |
schema format is 4.</p> |
| 418 |
|
| 419 |
<p> The schema format number for a new database can be set at runtime using |
| 420 |
the <a href="pragma.html#pragma_legacy_file_format">PRAGMA legacy_file_format</a> command. |
| 421 |
</p></blockquote><a name="default_file_permissions"></a> |
| 422 |
<p><b>SQLITE_DEFAULT_FILE_PERMISSIONS=<i>N</i></b></p><blockquote><p> |
| 423 |
The default numeric file permissions for newly created database files |
| 424 |
under unix. If not specified, the default is 0644 which means that |
| 425 |
the files is globally readable but only writable by the creator. |
| 426 |
</p></blockquote><a name="default_foreign_keys"></a> |
| 427 |
<p><b>SQLITE_DEFAULT_FOREIGN_KEYS=<i><0 or 1></i></b></p><blockquote><p> |
| 428 |
This macro determines whether enforcement of |
| 429 |
<a href="foreignkeys.html">foreign key constraints</a> is enabled or disabled by default for |
| 430 |
new database connections. Each database connection can always turn |
| 431 |
enforcement of foreign key constraints on and off at run-time using |
| 432 |
the <a href="pragma.html#pragma_foreign_keys">foreign_keys pragma</a>. Enforcement of foreign key constraints |
| 433 |
is normally off by default, but if this compile-time parameter is |
| 434 |
set to 1, enforcement of foreign key constraints will be on by default. |
| 435 |
</p></blockquote><a name="default_mmap_size"></a> |
| 436 |
<p><b>SQLITE_DEFAULT_MMAP_SIZE=<i>N</i></b></p><blockquote><p> |
| 437 |
This macro sets the default limit on the amount of memory that |
| 438 |
will be used for memory-mapped I/O |
| 439 |
for each open database file. If <i>N</i> |
| 440 |
is zero, then memory mapped I/O is disabled by default. This |
| 441 |
compile-time limit and the <a href="compile.html#max_mmap_size">SQLITE_MAX_MMAP_SIZE</a> can be modified |
| 442 |
at start-time using the |
| 443 |
<a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_covering_index_scan.html#sqliteconfigmmapsize">SQLITE_CONFIG_MMAP_SIZE</a>) call, or at run-time |
| 444 |
using the <a href="pragma.html#pragma_mmap_size">mmap_size pragma</a>. |
| 445 |
</p></blockquote><a name="default_journal_size_limit"></a> |
| 446 |
<p><b>SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT=<i><bytes></i></b></p><blockquote><p> |
| 447 |
This option sets the size limit on <a href="lockingv3.html#rollback">rollback journal</a> files in |
| 448 |
<a href="pragma.html#pragma_journal_mode">persistent journal mode</a> and |
| 449 |
<a href="pragma.html#pragma_locking_mode">exclusive locking mode</a> or sets the size of the |
| 450 |
write-ahead log file in <a href="wal.html">WAL mode</a>. When this |
| 451 |
compile-time option is omitted there is no upper bound on the |
| 452 |
size of the rollback journals or write-ahead logs. |
| 453 |
The journal file size limit |
| 454 |
can be changed at run-time using the <a href="pragma.html#pragma_journal_size_limit">journal_size_limit pragma</a>. |
| 455 |
</p></blockquote><a name="default_locking_mode"></a> |
| 456 |
<p><b>SQLITE_DEFAULT_LOCKING_MODE=<i><1 or 0></i></b></p><blockquote><p> |
| 457 |
If set to 1, then the default <a href="pragma.html#pragma_locking_mode">locking_mode</a> is set to EXCLUSIVE. |
| 458 |
If omitted or set to 0 then the default <a href="pragma.html#pragma_locking_mode">locking_mode</a> is NORMAL. |
| 459 |
</p></blockquote><a name="default_lookaside"></a> |
| 460 |
<p><b>SQLITE_DEFAULT_LOOKASIDE=<i>SZ,N</i></b></p><blockquote><p> |
| 461 |
Sets the default size of the <a href="malloc.html#lookaside">lookaside memory allocator</a> memory pool |
| 462 |
to N entries of SZ bytes each. This setting can be modified at |
| 463 |
start-time using <a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_covering_index_scan.html#sqliteconfiglookaside">SQLITE_CONFIG_LOOKASIDE</a>) and/or |
| 464 |
as each <a href="c3ref/sqlite3.html">database connection</a> is opened using |
| 465 |
<a href="c3ref/db_config.html">sqlite3_db_config</a>(db, <a href="c3ref/c_dbconfig_defensive.html#sqlitedbconfiglookaside">SQLITE_DBCONFIG_LOOKASIDE</a>). |
| 466 |
</p></blockquote><a name="default_memstatus"></a> |
| 467 |
<p><b>SQLITE_DEFAULT_MEMSTATUS=<i><1 or 0></i></b></p><blockquote><p> |
| 468 |
This macro is used to determine whether or not the features enabled and |
| 469 |
disabled using the SQLITE_CONFIG_MEMSTATUS argument to <a href="c3ref/config.html">sqlite3_config()</a> |
| 470 |
are available by default. The default value is 1 (<a href="c3ref/c_config_covering_index_scan.html#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a> |
| 471 |
related features enabled). |
| 472 |
<p> |
| 473 |
The <a href="c3ref/memory_highwater.html">sqlite3_memory_used()</a> and <a href="c3ref/memory_highwater.html">sqlite3_memory_highwater()</a> interfaces, |
| 474 |
the <a href="c3ref/status.html">sqlite3_status64</a>(<a href="c3ref/c_status_malloc_count.html#sqlitestatusmemoryused">SQLITE_STATUS_MEMORY_USED</a>) interface, |
| 475 |
and the <a href="compile.html#max_memory">SQLITE_MAX_MEMORY</a> compile-time option are all non-functional |
| 476 |
when memory usage tracking is disabled. |
| 477 |
</p></blockquote><a name="default_pcache_initsz"></a> |
| 478 |
<p><b>SQLITE_DEFAULT_PCACHE_INITSZ=<i>N</i></b></p><blockquote><p> |
| 479 |
This macro determines the number of pages initially allocated by the |
| 480 |
page cache module when <a href="c3ref/c_config_covering_index_scan.html#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a> configuration option is |
| 481 |
not used and memory for the page cache is obtained from <a href="c3ref/free.html">sqlite3_malloc()</a> |
| 482 |
instead. The number of pages set by this macro are allocated in a single |
| 483 |
allocation, which reduces the load on the memory allocator. |
| 484 |
</p></blockquote><a name="default_page_size"></a> |
| 485 |
<p><b>SQLITE_DEFAULT_PAGE_SIZE=<i><bytes></i></b></p><blockquote><p> |
| 486 |
This macro is used to set the default page-size used when a |
| 487 |
database is created. The value assigned must be a power of 2. The |
| 488 |
default value is 4096. The compile-time default may be overridden at |
| 489 |
runtime by the <a href="pragma.html#pragma_page_size">PRAGMA page_size</a> command. |
| 490 |
</p></blockquote><a name="default_synchronous"></a> |
| 491 |
<p><b>SQLITE_DEFAULT_SYNCHRONOUS=<i><0-3></i></b></p><blockquote><p> |
| 492 |
This macro determines the default value of the |
| 493 |
<a href="pragma.html#pragma_synchronous">PRAGMA synchronous</a> setting. If not overridden at compile-time, |
| 494 |
the default setting is 2 (FULL). |
| 495 |
</p></blockquote><a name="default_wal_synchronous"></a> |
| 496 |
<p><b>SQLITE_DEFAULT_WAL_SYNCHRONOUS=<i><0-3></i></b></p><blockquote><p> |
| 497 |
This macro determines the default value of the |
| 498 |
<a href="pragma.html#pragma_synchronous">PRAGMA synchronous</a> setting for database files that open in |
| 499 |
<a href="wal.html">WAL mode</a>. If not overridden at compile-time, this value is the |
| 500 |
same as <a href="compile.html#default_synchronous">SQLITE_DEFAULT_SYNCHRONOUS</a>. |
| 501 |
<p> |
| 502 |
If SQLITE_DEFAULT_WAL_SYNCHRONOUS differs from SQLITE_DEFAULT_SYNCHRONOUS, |
| 503 |
and if the application has not modified the synchronous setting for |
| 504 |
the database file using the <a href="pragma.html#pragma_synchronous">PRAGMA synchronous</a> statement, then |
| 505 |
the synchronous setting is changed to the value defined by |
| 506 |
SQLITE_DEFAULT_WAL_SYNCHRONOUS when the database connection switches |
| 507 |
into WAL mode for the first time. |
| 508 |
If the SQLITE_DEFAULT_WAL_SYNCHRONOUS value is not overridden at |
| 509 |
compile-time, then it will always be the same as |
| 510 |
<a href="compile.html#default_synchronous">SQLITE_DEFAULT_SYNCHRONOUS</a> and so no automatic synchronous setting |
| 511 |
changes will ever occur. |
| 512 |
</p></blockquote><a name="default_wal_autocheckpoint"></a> |
| 513 |
<p><b>SQLITE_DEFAULT_WAL_AUTOCHECKPOINT=<i><pages></i></b></p><blockquote><p> |
| 514 |
This macro sets the default page count for the <a href="wal.html">WAL</a> |
| 515 |
<a href="wal.html#ckpt">automatic checkpointing</a> feature. If unspecified, |
| 516 |
the default page count is 1000. |
| 517 |
</p></blockquote><a name="default_worker_threads"></a> |
| 518 |
<p><b>SQLITE_DEFAULT_WORKER_THREADS=<i>N</i></b></p><blockquote><p> |
| 519 |
This macro sets the default value for |
| 520 |
the maximum number of auxiliary threads that a single |
| 521 |
<a href="c3ref/stmt.html">prepared statement</a> will launch to assist it with a query. If not specified, |
| 522 |
the default maximum is 0. |
| 523 |
The value set here cannot be more than <a href="compile.html#max_worker_threads">SQLITE_MAX_WORKER_THREADS</a>. |
| 524 |
</p></blockquote><a name="dqs"></a> |
| 525 |
<p><b>SQLITE_DQS=<i>N</i></b></p><blockquote><p> |
| 526 |
This macro determines the default values for |
| 527 |
<a href="c3ref/c_dbconfig_defensive.html#sqlitedbconfigdqsddl">SQLITE_DBCONFIG_DQS_DDL</a> and <a href="c3ref/c_dbconfig_defensive.html#sqlitedbconfigdqsdml">SQLITE_DBCONFIG_DQS_DML</a>, which |
| 528 |
in turn determine how SQLite handles each <a href="quirks.html#dblquote">double-quoted string literal</a>. |
| 529 |
The "DQS" name stands for |
| 530 |
"<u>D</u>ouble-<u>Q</u>uoted <u>S</u>tring". |
| 531 |
The <i>N</i> argument should be an integer 0, 1, 2, or 3. |
| 532 |
<blockquote><table border=1 cellpadding="0" cellspacing="0"> |
| 533 |
<tr><th rowspan="2">SQLITE_DQS<th colspan="2">Double-Quoted Strings Allowed |
| 534 |
<th rowspan="2">Remarks |
| 535 |
<tr><th>In DDL<th>In DML |
| 536 |
<tr><td>3<td>yes<td>yes<td>default |
| 537 |
<tr><td>2<td>yes<td>no<td> |
| 538 |
<tr><td>1<td>no<td>yes<td> |
| 539 |
<tr><td>0<td>no<td>no<td>recommended |
| 540 |
</table></blockquote> |
| 541 |
<p>The recommended setting is 0, meaning that double-quoted |
| 542 |
strings are disallowed in all contexts. However, the default |
| 543 |
setting is 3 for maximum compatibility with legacy applications. |
| 544 |
</p></blockquote><a name="extra_durable"></a> |
| 545 |
<p><b>SQLITE_EXTRA_DURABLE</b></p><blockquote><p> |
| 546 |
The SQLITE_EXTRA_DURABLE compile-time option that used to cause the default |
| 547 |
<a href="pragma.html#pragma_synchronous">PRAGMA synchronous</a> setting to be EXTRA, rather than FULL. This option |
| 548 |
is no longer supported. Use |
| 549 |
<a href="compile.html#default_synchronous">SQLITE_DEFAULT_SYNCHRONOUS=3</a> instead. |
| 550 |
</p></blockquote><a name="fts3_max_expr_depth"></a> |
| 551 |
<p><b>SQLITE_FTS3_MAX_EXPR_DEPTH=<i>N</i></b></p><blockquote><p> |
| 552 |
This macro sets the maximum depth of the search tree that corresponds to |
| 553 |
the right-hand side of the MATCH operator in an <a href="fts3.html">FTS3</a> or <a href="fts3.html#fts4">FTS4</a> full-text |
| 554 |
index. The full-text search uses a recursive algorithm, so the depth of |
| 555 |
the tree is limited to prevent using too much stack space. The default |
| 556 |
limit is 12. This limit is sufficient for up to 4095 search terms on the |
| 557 |
right-hand side of the MATCH operator and it holds stack space usage to |
| 558 |
less than 2000 bytes. |
| 559 |
<p> |
| 560 |
For ordinary FTS3/FTS4 queries, the search tree depth is approximately |
| 561 |
the base-2 logarithm of the number of terms in the right-hand side of the |
| 562 |
MATCH operator. However, for <a href="fts3.html#phrase">phrase queries</a> and <a href="fts3.html#near">NEAR queries</a> the |
| 563 |
search tree depth is linear in the number of right-hand side terms. |
| 564 |
So the default depth limit of 12 is sufficient for up to 4095 ordinary |
| 565 |
terms on a MATCH, it is only sufficient for 11 or 12 phrase or NEAR |
| 566 |
terms. Even so, the default is more than enough for most application. |
| 567 |
</p></blockquote><a name="json_max_depth"></a> |
| 568 |
<p><b>SQLITE_JSON_MAX_DEPTH=<i>N</i></b></p><blockquote><p> |
| 569 |
This macro sets the maximum nesting depth for JSON objects and arrays. |
| 570 |
The default value is 1000. |
| 571 |
<p> |
| 572 |
The <a href="json1.html">JSON SQL functions</a> use a |
| 573 |
<a href="https://en.wikipedia.org/wiki/Recursive_descent_parser">recursive descent parser</a>. |
| 574 |
This means that deeply nested JSON might require a lot of stack space to |
| 575 |
parse. On systems with limited stack space, SQLite can be compiled with |
| 576 |
a greatly reduced maximum JSON nesting depth to avoid the possibility of |
| 577 |
a stack overflow, even from hostile inputs. A value of 10 or 20 is normally |
| 578 |
sufficient even for the most complex real-world JSON. |
| 579 |
</p></blockquote><a name="like_doesnt_match_blobs"></a> |
| 580 |
<p><b>SQLITE_LIKE_DOESNT_MATCH_BLOBS</b></p><blockquote><p> |
| 581 |
This compile-time option causes the <a href="lang_expr.html#like">LIKE</a> operator to always return |
| 582 |
False if either operand is a BLOB. The default behavior of <a href="lang_expr.html#like">LIKE</a> |
| 583 |
is that BLOB operands are cast to TEXT before the comparison is done. |
| 584 |
<p> |
| 585 |
This compile-time option makes SQLite run more efficiently when processing |
| 586 |
queries that use the <a href="lang_expr.html#like">LIKE</a> operator, at the expense of breaking backwards |
| 587 |
compatibility. However, the backwards compatibility break may be only |
| 588 |
a technicality. There was a long-standing bug in the <a href="lang_expr.html#like">LIKE</a> processing logic |
| 589 |
(see <a href="https://sqlite.org/src/info/05f43be8fdda9f">https://sqlite.org/src/info/05f43be8fdda9f</a>) that caused it to |
| 590 |
misbehave for BLOB operands and nobody observed that bug in nearly |
| 591 |
10 years of active use. So for more users, it is probably safe to |
| 592 |
enable this compile-time option and thereby save a little CPU time |
| 593 |
on LIKE queries. |
| 594 |
<p> |
| 595 |
This compile-time option affects the SQL <a href="lang_expr.html#like">LIKE</a> operator only and has |
| 596 |
no impact on the <a href="c3ref/strlike.html">sqlite3_strlike()</a> C-language interface. |
| 597 |
</p></blockquote><a name="max_memory"></a> |
| 598 |
<p><b>SQLITE_MAX_MEMORY=<i>N</i></b></p><blockquote><p> |
| 599 |
This option limits the total amount of memory that SQLite will request |
| 600 |
from malloc() to <i>N</i> bytes. Any attempt by SQLite to allocate |
| 601 |
new memory that would cause the sum of all allocations held by SQLite to exceed |
| 602 |
<i>N</i> bytes will result in an out-of-memory error. |
| 603 |
This is a hard upper limit. See also the <a href="c3ref/soft_heap_limit.html">sqlite3_soft_heap_limit()</a> |
| 604 |
interface. |
| 605 |
<p> |
| 606 |
This option is a limit on the <i>total</i> amount of memory allocated. |
| 607 |
See the <a href="compile.html#max_allocation_size">SQLITE_MAX_ALLOCATION_SIZE</a> option for a limitation on the amount |
| 608 |
of memory allowed in any single memory allocation. |
| 609 |
<p> |
| 610 |
This limit is only functional if memory usage statistics are available via |
| 611 |
the <a href="c3ref/memory_highwater.html">sqlite3_memory_used()</a> and <a href="c3ref/status.html">sqlite3_status64</a>(<a href="c3ref/c_status_malloc_count.html#sqlitestatusmemoryused">SQLITE_STATUS_MEMORY_USED</a>) |
| 612 |
interfaces. Without that memory usage information, SQLite has no way of |
| 613 |
knowing when it is about to go over the limit, and thus is unable to prevent |
| 614 |
the excess memory allocation. Memory usage tracking is turned on by default, |
| 615 |
but can be disabled at compile-time using the <a href="compile.html#default_memstatus">SQLITE_DEFAULT_MEMSTATUS</a> option, |
| 616 |
or at start-time using <a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_covering_index_scan.html#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a>). |
| 617 |
</p></blockquote><a name="max_mmap_size"></a> |
| 618 |
<p><b>SQLITE_MAX_MMAP_SIZE=<i>N</i></b></p><blockquote><p> |
| 619 |
This macro sets a hard upper bound on the amount of address space that |
| 620 |
can be used by any single database for memory-mapped I/O. |
| 621 |
Setting this value to 0 completely disables memory-mapped I/O and |
| 622 |
causes logic associated with memory-mapped I/O to be omitted from the |
| 623 |
build. This option does change the default memory-mapped I/O address |
| 624 |
space size (set by <a href="compile.html#default_mmap_size">SQLITE_DEFAULT_MMAP_SIZE</a> or |
| 625 |
sqlite3_config(<a href="c3ref/c_config_covering_index_scan.html#sqliteconfigmmapsize">SQLITE_CONFIG_MMAP_SIZE</a>)) or the |
| 626 |
run-time memory-mapped I/O address space size (set by |
| 627 |
sqlite3_file_control(<a href="c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlmmapsize">SQLITE_FCNTL_MMAP_SIZE</a>) or |
| 628 |
<a href="pragma.html#pragma_mmap_size">PRAGMA mmap_size</a>) as long as those other settings are less than the |
| 629 |
maximum value defined here. |
| 630 |
</p></blockquote><a name="max_schema_retry"></a> |
| 631 |
<p><b>SQLITE_MAX_SCHEMA_RETRY=<i>N</i></b></p><blockquote><p> |
| 632 |
Whenever the database schema changes, prepared statements are automatically |
| 633 |
reprepared to accommodate the new schema. There is a race condition here |
| 634 |
in that if one thread is constantly changing the schema, another thread |
| 635 |
might spin on reparses and repreparations of a prepared statement and |
| 636 |
never get any real work done. This parameter prevents an infinite loop |
| 637 |
by forcing the spinning thread to give up after a fixed number of attempts |
| 638 |
at recompiling the prepared statement. The default setting is 50 which is |
| 639 |
more than adequate for most applications. |
| 640 |
</p></blockquote><a name="max_worker_threads"></a> |
| 641 |
<p><b>SQLITE_MAX_WORKER_THREADS=<i>N</i></b></p><blockquote><p> |
| 642 |
Set an upper bound on the <a href="c3ref/limit.html">sqlite3_limit</a>(db,<a href="c3ref/c_limit_attached.html#sqlitelimitworkerthreads">SQLITE_LIMIT_WORKER_THREADS</a>,N) |
| 643 |
setting that determines the maximum number of auxiliary threads that a single |
| 644 |
<a href="c3ref/stmt.html">prepared statement</a> will use to aid with CPU-intensive computations |
| 645 |
(mostly sorting). See also the <a href="compile.html#default_worker_threads">SQLITE_DEFAULT_WORKER_THREADS</a> options. |
| 646 |
</p></blockquote><a name="memdb_default_maxsize"></a> |
| 647 |
<p><b>SQLITE_MEMDB_DEFAULT_MAXSIZE=<i>N</i></b></p><blockquote><p> |
| 648 |
Set the default size limit (in bytes) for in-memory databases created using |
| 649 |
<a href="c3ref/deserialize.html">sqlite3_deserialize()</a>. This is just the default. The limit can be |
| 650 |
changed at start-time using |
| 651 |
<a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_covering_index_scan.html#sqliteconfigmemdbmaxsize">SQLITE_CONFIG_MEMDB_MAXSIZE</a>,N) |
| 652 |
or at run-time for individual databases using the |
| 653 |
<a href="c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlsizelimit">SQLITE_FCNTL_SIZE_LIMIT</a> <a href="c3ref/file_control.html">file-control</a>. |
| 654 |
If no default is specified, 1073741824 is used. |
| 655 |
</p></blockquote><a name="minimum_file_descriptor"></a> |
| 656 |
<p><b>SQLITE_MINIMUM_FILE_DESCRIPTOR=<i>N</i></b></p><blockquote><p> |
| 657 |
The unix <a href="vfs.html">VFS</a> will never use a file descriptor less than <i>N</i>. The |
| 658 |
default value of <i>N</i> is 3. |
| 659 |
<p> |
| 660 |
Avoiding the use of low-numbered file descriptors is a defense against |
| 661 |
accidental database corruption. If a database file was opened using |
| 662 |
file descriptor 2, for example, and then an assert() failed and invoked |
| 663 |
write(2,...), that would likely cause database corruption by overwriting |
| 664 |
part of the database file with the assertion error message. Using only |
| 665 |
higher-valued file descriptors avoids this potential problem. The |
| 666 |
protection against |
| 667 |
using low-numbered file descriptors can be disabled by setting this |
| 668 |
compile-time option to 0. |
| 669 |
</p></blockquote><a name="powersafe_overwrite"></a> |
| 670 |
<p><b>SQLITE_POWERSAFE_OVERWRITE=<i><0 or 1></i></b></p><blockquote><p> |
| 671 |
This option changes the default assumption about <a href="psow.html">powersafe overwrite</a> |
| 672 |
for the underlying filesystems for the unix and windows <a href="vfs.html">VFSes</a>. |
| 673 |
Setting SQLITE_POWERSAFE_OVERWRITE to 1 causes SQLite to assume that |
| 674 |
application-level writes cannot changes bytes outside the range of |
| 675 |
bytes written even if the write occurs just before a power loss. |
| 676 |
With SQLITE_POWERSAFE_OVERWRITE set to 0, SQLite assumes that other |
| 677 |
bytes in the same sector with a written byte might be changed or |
| 678 |
damaged by a power loss. |
| 679 |
</p></blockquote><a name="printf_precision_limit"></a> |
| 680 |
<p><b>SQLITE_PRINTF_PRECISION_LIMIT=<i>N</i></b></p><blockquote><p> |
| 681 |
This option limits the maximum width and precision of substitutions |
| 682 |
for the <a href="lang_corefunc.html#printf">printf() SQL function</a> and the other C-language string |
| 683 |
formatting functions such as <a href="c3ref/mprintf.html">sqlite3_mprintf()</a> and |
| 684 |
<a href="c3ref/str_append.html">sqlite3_str_appendf()</a>. This is turn can prevent a hostile or |
| 685 |
malfunctioning script from using excessive memory by invoking |
| 686 |
a format such as: "<tt>printf('%*s',2147483647,'hi')</tt>". |
| 687 |
A value for <i>N</i> of around 100000 is normally sufficient. |
| 688 |
<p> |
| 689 |
The <a href="lang_corefunc.html#printf">printf() SQL function</a> is subject to the <a href="c3ref/c_limit_attached.html#sqlitelimitlength">SQLITE_LIMIT_LENGTH</a> |
| 690 |
limit of <a href="c3ref/limit.html">sqlite3_limit()</a>. Hence any printf() result with a |
| 691 |
width or precision more than the SQLITE_LIMIT_LENGTH will cause |
| 692 |
an <a href="rescode.html#toobig">SQLITE_TOOBIG</a> error. However, the low-level formatting |
| 693 |
for the printf() function is done by a subroutine that does not |
| 694 |
have access to SQLITE_LIMIT_LENGTH. So the low-level formatting |
| 695 |
is done into a memory allocation that might be considerably larger |
| 696 |
than SQLITE_LIMIT_LENGTH and the SQLITE_LIMIT_LENGTH check is only |
| 697 |
performed after all formatting is complete. Thus there might be a |
| 698 |
transient buffer that exceeds SQLITE_LIMIT_LENGTH. The |
| 699 |
SQLITE_PRINTF_PRECISION_LIMIT option is an additional check |
| 700 |
that prevents excess sizes for the transient buffer used inside |
| 701 |
the low-level formatting subroutine, prior to the |
| 702 |
SQLITE_LIMIT_LENGTH check. |
| 703 |
<p> |
| 704 |
Be careful not to set SQLITE_PRINTF_PRECISION_LIMIT too low. |
| 705 |
SQLite uses its <a href="printf.html">built-in printf()</a> functionality to format the text |
| 706 |
of CREATE statements stored in the <a href="schematab.html">sqlite_schema table</a>. So |
| 707 |
SQLITE_PRINTF_PRECISION_LIMIT should be at least as big as the largest |
| 708 |
table, index, view, or trigger definition that you are likely to |
| 709 |
encounter. |
| 710 |
<p> |
| 711 |
No error is raised if a width or precision exceeds |
| 712 |
SQLITE_PRINTF_PRECISION_LIMIT. Instead, the large width or |
| 713 |
precision is silently truncated. |
| 714 |
<p> |
| 715 |
The default value for SQLITE_PRINTF_PRECISION_LIMIT is 2147483647 |
| 716 |
(0x7fffffff).</p> |
| 717 |
|
| 718 |
<p></p></blockquote><a name="query_planner_limit"></a> |
| 719 |
<p><b>SQLITE_QUERY_PLANNER_LIMIT=<i>N</i></b></p><blockquote><p> |
| 720 |
As part of the query planning process, SQLite enumerates all usable |
| 721 |
combinations of indexes and WHERE-clause constraints. For certain |
| 722 |
pathological queries, the number of these index-and-constraint combinations |
| 723 |
can be very large, resulting in slow performance by the query planner. |
| 724 |
The SQLITE_QUERY_PLANNER_LIMIT value (in conjunction with the |
| 725 |
related <a href="compile.html#query_planner_limit_incr">SQLITE_QUERY_PLANNER_LIMIT_INCR</a> setting) limits the number |
| 726 |
of index-and-constraint combinations that the query planner will |
| 727 |
consider, in order to prevent the query planner from using excess |
| 728 |
CPU time. The default value for SQLITE_QUERY_PLANNER_LIMIT is set |
| 729 |
high enough so that is never reached for real-world queries. The |
| 730 |
query planner search limit only applies to queries that are deliberately |
| 731 |
crafted to use excess planning time. |
| 732 |
</p></blockquote><a name="query_planner_limit_incr"></a> |
| 733 |
<p><b>SQLITE_QUERY_PLANNER_LIMIT_INCR=<i>N</i></b></p><blockquote><p> |
| 734 |
The <a href="compile.html#query_planner_limit">SQLITE_QUERY_PLANNER_LIMIT</a> option sets an initial baseline value |
| 735 |
for the maximum number of index-and-constraint combinations that the |
| 736 |
query planner will consider. The baseline query planner limit is increased |
| 737 |
by SQLITE_QUERY_PLANNER_LIMIT_INCR prior to processing each table of a |
| 738 |
join so that each table is guaranteed to be able to propose at least |
| 739 |
some index-and-constraint combinations to the optimizer even if prior |
| 740 |
tables of the join have exhausted the baseline limit. The default |
| 741 |
value for both this compile-time option and the |
| 742 |
<a href="compile.html#query_planner_limit">SQLITE_QUERY_PLANNER_LIMIT</a> option are set high enough so that they should |
| 743 |
never be reached for real-world queries. |
| 744 |
</p></blockquote><a name="reverse_unordered_selects"></a> |
| 745 |
<p><b>SQLITE_REVERSE_UNORDERED_SELECTS</b></p><blockquote><p> |
| 746 |
This option causes the <a href="pragma.html#pragma_reverse_unordered_selects">PRAGMA reverse_unordered_selects</a> setting to be |
| 747 |
enabled by default. When enabled, <a href="lang_select.html">SELECT</a> statements that lack an |
| 748 |
ORDER BY clause will run in reverse order.<p> |
| 749 |
This option is useful for detecting when applications (incorrectly) |
| 750 |
assume that the order of rows in a SELECT without an ORDER BY clause |
| 751 |
will always be the same. |
| 752 |
</p></blockquote><a name="sorter_pmasz"></a> |
| 753 |
<p><b>SQLITE_SORTER_PMASZ=<i>N</i></b></p><blockquote><p> |
| 754 |
If multi-threaded processing is enabled via the |
| 755 |
<a href="pragma.html#pragma_threads">PRAGMA threads</a> setting, then sort operations will |
| 756 |
attempt to start helper threads when the amount of content |
| 757 |
to be sorted exceeds the minimum of the <a href="pragma.html#pragma_cache_size">cache_size</a> and PMA Size |
| 758 |
determined by the <a href="c3ref/c_config_covering_index_scan.html#sqliteconfigpmasz">SQLITE_CONFIG_PMASZ</a> start-time option. |
| 759 |
This compile-time option sets the default value for the |
| 760 |
<a href="c3ref/c_config_covering_index_scan.html#sqliteconfigpmasz">SQLITE_CONFIG_PMASZ</a> start-time option. |
| 761 |
The default value is 250. |
| 762 |
</p></blockquote><a name="stmtjrnl_spill"></a> |
| 763 |
<p><b>SQLITE_STMTJRNL_SPILL=<i>N</i></b></p><blockquote><p> |
| 764 |
The SQLITE_STMTJRNL_SPILL compile-time option determines the |
| 765 |
default setting of the <a href="c3ref/c_config_covering_index_scan.html#sqliteconfigstmtjrnlspill">SQLITE_CONFIG_STMTJRNL_SPILL</a> start-time |
| 766 |
setting. That setting determines the size threshold above which |
| 767 |
<a href="tempfiles.html#stmtjrnl">statement journals</a> are moved from memory to disk. |
| 768 |
</p></blockquote><a name="win32_malloc"></a> |
| 769 |
<p><b>SQLITE_WIN32_MALLOC</b></p><blockquote><p> |
| 770 |
This option enables the use of the Windows Heap API functions for memory |
| 771 |
allocation instead of the standard library malloc() and free() routines. |
| 772 |
</p></blockquote><a name="yystackdepth"></a> |
| 773 |
<p><b>YYSTACKDEPTH=<i><max_depth></i></b></p><blockquote><p> |
| 774 |
This macro sets the maximum depth of the LALR(1) stack used by |
| 775 |
the SQL parser within SQLite. The default value is 100. A typical |
| 776 |
application will use less than about 20 levels of the stack. |
| 777 |
Developers whose applications contain SQL statements that |
| 778 |
need more than 100 LALR(1) stack entries should seriously |
| 779 |
consider refactoring their SQL as it is likely to be well beyond |
| 780 |
the ability of any human to comprehend. |
| 781 |
</p></blockquote> |
| 782 |
|
| 783 |
<h1 id="_options_to_set_size_limits"><span>5. </span> Options To Set Size Limits</h1> |
| 784 |
|
| 785 |
<p>There are compile-time options that will set upper bounds |
| 786 |
on the sizes of various structures in SQLite. The compile-time |
| 787 |
options normally set a hard upper bound that can be changed |
| 788 |
at run-time on individual <a href="c3ref/sqlite3.html">database connections</a> using the |
| 789 |
<a href="c3ref/limit.html">sqlite3_limit()</a> interface.</p> |
| 790 |
|
| 791 |
<p>The compile-time options for setting upper bounds are |
| 792 |
<a href="limits.html">documented separately</a>. The following is a list of |
| 793 |
the available settings:</p> |
| 794 |
|
| 795 |
<ul> |
| 796 |
<li> <a href="limits.html#max_attached">SQLITE_MAX_ATTACHED</a> </li> |
| 797 |
<li> <a href="limits.html#max_column">SQLITE_MAX_COLUMN</a> </li> |
| 798 |
<li> <a href="limits.html#max_compound_select">SQLITE_MAX_COMPOUND_SELECT</a> </li> |
| 799 |
<li> <a href="limits.html#max_expr_depth">SQLITE_MAX_EXPR_DEPTH</a> </li> |
| 800 |
<li> <a href="limits.html#max_function_arg">SQLITE_MAX_FUNCTION_ARG</a> </li> |
| 801 |
<li> <a href="limits.html#max_length">SQLITE_MAX_LENGTH</a> </li> |
| 802 |
<li> <a href="limits.html#max_like_pattern_length">SQLITE_MAX_LIKE_PATTERN_LENGTH</a> </li> |
| 803 |
<li> <a href="limits.html#max_page_count">SQLITE_MAX_PAGE_COUNT</a> </li> |
| 804 |
<li> <a href="limits.html#max_sql_length">SQLITE_MAX_SQL_LENGTH</a> </li> |
| 805 |
<li> <a href="limits.html#max_variable_number">SQLITE_MAX_VARIABLE_NUMBER</a> </li> |
| 806 |
</ul> |
| 807 |
|
| 808 |
<p>There are also some size limits that cannot be modified using |
| 809 |
<a href="c3ref/limit.html">sqlite3_limit()</a>. See, for example: |
| 810 |
|
| 811 |
</p><ul> |
| 812 |
<li> <a href="compile.html#fts3_max_expr_depth">SQLITE_FTS3_MAX_EXPR_DEPTH</a> </li> |
| 813 |
<li> <a href="compile.html#json_max_depth">SQLITE_JSON_MAX_DEPTH</a> </li> |
| 814 |
<li> <a href="compile.html#max_allocation_size">SQLITE_MAX_ALLOCATION_SIZE</a> </li> |
| 815 |
<li> <a href="compile.html#max_memory">SQLITE_MAX_MEMORY</a> </li> |
| 816 |
<li> <a href="compile.html#max_mmap_size">SQLITE_MAX_MMAP_SIZE</a> </li> |
| 817 |
<li> <a href="compile.html#printf_precision_limit">SQLITE_PRINTF_PRECISION_LIMIT</a> </li> |
| 818 |
<li> <a href="compile.html#trace_size_limit">SQLITE_TRACE_SIZE_LIMIT</a> </li> |
| 819 |
<li> <a href="compile.html#yystackdepth">YYSTACKDEPTH</a> </li> |
| 820 |
</ul> |
| 821 |
|
| 822 |
<a name="controlfeatures"></a> |
| 823 |
<h1 id="_options_to_control_operating_characteristics"><span>6. </span> Options To Control Operating Characteristics</h1> |
| 824 |
|
| 825 |
<a name="4_byte_aligned_malloc"></a> |
| 826 |
<p><b>SQLITE_4_BYTE_ALIGNED_MALLOC</b></p><blockquote><p> |
| 827 |
On most systems, the malloc() system call returns a buffer that is |
| 828 |
aligned to an 8-byte boundary. But on some systems (ex: windows) malloc() |
| 829 |
returns 4-byte aligned pointer. This compile-time option must be used |
| 830 |
on systems that return 4-byte aligned pointers from malloc(). |
| 831 |
</p></blockquote><a name="case_sensitive_like"></a> |
| 832 |
<p><b>SQLITE_CASE_SENSITIVE_LIKE</b></p><blockquote><p> |
| 833 |
If this option is present, then the built-in <a href="lang_expr.html#like">LIKE</a> operator will be |
| 834 |
case sensitive. This same effect can be achieved at run-time using |
| 835 |
the <a href="pragma.html#pragma_case_sensitive_like">case_sensitive_like pragma</a>. |
| 836 |
</p></blockquote><a name="direct_overflow_read"></a> |
| 837 |
<p><b>SQLITE_DIRECT_OVERFLOW_READ</b></p><blockquote><p> |
| 838 |
When this option is present, content contained in |
| 839 |
<a href="fileformat2.html#ovflpgs">overflow pages</a> of the database file is read directly from disk, |
| 840 |
bypassing the <a href="c3ref/pcache_methods2.html">page cache</a>, during read transactions. In applications |
| 841 |
that do a lot of reads of large BLOBs or strings, this option improves |
| 842 |
read performance. |
| 843 |
<p> |
| 844 |
As of version 3.45.0 (2024-01-15), this option is enabled by |
| 845 |
default. To disable it, using -DSQLITE_DIRECT_OVERFLOW_READ=0. |
| 846 |
</p></blockquote><a name="have_isnan"></a> |
| 847 |
<p><b>SQLITE_HAVE_ISNAN</b></p><blockquote><p> |
| 848 |
If this option is present, then SQLite will use the isnan() function from |
| 849 |
the system math library. This is an alias for the <a href="compile.html#isnan">HAVE_ISNAN</a> configuration |
| 850 |
option. |
| 851 |
</p></blockquote><a name="max_allocation_size"></a> |
| 852 |
<p><b>SQLITE_MAX_ALLOCATION_SIZE=<i>N</i></b></p><blockquote><p> |
| 853 |
This compile-time option sets an upper bound on the size of memory |
| 854 |
allocations that can be requested using <a href="c3ref/free.html">sqlite3_malloc64()</a>, |
| 855 |
<a href="c3ref/free.html">sqlite3_realloc64()</a>, and similar. The default value is |
| 856 |
2,147,483,391 (0x7ffffeff) and this should be considered an |
| 857 |
upper bound. Most applications can get by with a maximum allocation |
| 858 |
size of a few million bytes. |
| 859 |
<p> |
| 860 |
This is a limit on the maximum size of any single memory allocation. |
| 861 |
It is <i>not</i> a limit on the total amount of memory allocated. |
| 862 |
See <a href="compile.html#max_memory">SQLITE_MAX_MEMORY</a> for a limitation on the total amount of memory |
| 863 |
allocated. |
| 864 |
<p> |
| 865 |
Reducing the maximum size of individual memory allocations provides |
| 866 |
extra defense against denial-of-service attacks that attempt to exhaust |
| 867 |
system memory by doing many large allocations. It is also an extra layer |
| 868 |
of defense against application bugs where the size of a memory allocation |
| 869 |
is computed using a signed 32-bit integer that could overflow → |
| 870 |
with a small maximum allocation size, such buggy memory allocation size |
| 871 |
computations are likely to be spotted sooner due to out-of-memory errors |
| 872 |
and before the integer actually overflows. |
| 873 |
</p></blockquote><a name="os_other"></a> |
| 874 |
<p><b>SQLITE_OS_OTHER=<i><0 or 1></i></b></p><blockquote><p> |
| 875 |
The option causes SQLite to omit its built-in operating system interfaces |
| 876 |
for Unix, Windows, and OS/2. The resulting library will have no default |
| 877 |
<a href="c3ref/vfs.html">operating system interface</a>. Applications must use |
| 878 |
<a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a> to register an appropriate interface before |
| 879 |
using SQLite. Applications must also supply implementations for the |
| 880 |
<a href="c3ref/initialize.html">sqlite3_os_init()</a> and <a href="c3ref/initialize.html">sqlite3_os_end()</a> interfaces. The usual practice |
| 881 |
is for the supplied <a href="c3ref/initialize.html">sqlite3_os_init()</a> to invoke <a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a>. |
| 882 |
SQLite will automatically invoke <a href="c3ref/initialize.html">sqlite3_os_init()</a> when it initializes.</p> |
| 883 |
|
| 884 |
<p> This option is typically used when building SQLite for an embedded |
| 885 |
platform with a custom operating system. |
| 886 |
</p></blockquote><a name="secure_delete"></a> |
| 887 |
<p><b>SQLITE_SECURE_DELETE</b></p><blockquote><p> |
| 888 |
This compile-time option changes the default setting of the |
| 889 |
<a href="pragma.html#pragma_secure_delete">secure_delete pragma</a>. When this option is not used, secure_delete defaults |
| 890 |
to off. When this option is present, secure_delete defaults to on.</p> |
| 891 |
|
| 892 |
<p> The secure_delete setting causes deleted content to be overwritten with |
| 893 |
zeros. There is a small performance penalty since additional I/O |
| 894 |
must occur. On the other hand, secure_delete can prevent fragments of |
| 895 |
sensitive information from lingering in unused parts of the database file |
| 896 |
after it has been deleted. See the documentation on the |
| 897 |
<a href="pragma.html#pragma_secure_delete">secure_delete pragma</a> for additional information. |
| 898 |
</p></blockquote><a name="threadsafe"></a> |
| 899 |
<p><b>SQLITE_THREADSAFE=<i><0 or 1 or 2></i></b></p><blockquote><p> |
| 900 |
This option controls whether or not code is included in SQLite to |
| 901 |
enable it to operate safely in a multithreaded environment. The |
| 902 |
default is SQLITE_THREADSAFE=1 which is safe for use in a multithreaded |
| 903 |
environment. When compiled with SQLITE_THREADSAFE=0 all mutexing code |
| 904 |
is omitted and it is unsafe to use SQLite in a multithreaded program. |
| 905 |
When compiled with SQLITE_THREADSAFE=2, SQLite can be used in a multithreaded |
| 906 |
program so long as no two threads attempt to use the same |
| 907 |
<a href="c3ref/sqlite3.html">database connection</a> (or any <a href="c3ref/stmt.html">prepared statements</a> derived from |
| 908 |
that database connection) at the same time.</p> |
| 909 |
|
| 910 |
<p> To put it another way, SQLITE_THREADSAFE=1 sets the default |
| 911 |
<a href="threadsafe.html">threading mode</a> to Serialized. SQLITE_THREADSAFE=2 sets the default |
| 912 |
<a href="threadsafe.html">threading mode</a> to Multi-threaded. And SQLITE_THREADSAFE=0 sets the |
| 913 |
<a href="threadsafe.html">threading mode</a> to Single-threaded.</p> |
| 914 |
|
| 915 |
<p> The value of SQLITE_THREADSAFE can be determined at run-time |
| 916 |
using the <a href="c3ref/threadsafe.html">sqlite3_threadsafe()</a> interface.</p> |
| 917 |
|
| 918 |
<p> When SQLite has been compiled with SQLITE_THREADSAFE=1 or |
| 919 |
SQLITE_THREADSAFE=2 then the <a href="threadsafe.html">threading mode</a> |
| 920 |
can be altered at run-time using the <a href="c3ref/config.html">sqlite3_config()</a> interface together |
| 921 |
with one of these verbs:</p> |
| 922 |
|
| 923 |
<p> <ul> |
| 924 |
<li><a href="c3ref/c_config_covering_index_scan.html#sqliteconfigsinglethread">SQLITE_CONFIG_SINGLETHREAD</a> |
| 925 |
<li><a href="c3ref/c_config_covering_index_scan.html#sqliteconfigmultithread">SQLITE_CONFIG_MULTITHREAD</a> |
| 926 |
<li><a href="c3ref/c_config_covering_index_scan.html#sqliteconfigserialized">SQLITE_CONFIG_SERIALIZED</a> |
| 927 |
</ul></p> |
| 928 |
|
| 929 |
<p> The <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_NOMUTEX</a> and |
| 930 |
<a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_FULLMUTEX</a> flags to <a href="c3ref/open.html">sqlite3_open_v2()</a> can also be used |
| 931 |
to adjust the <a href="threadsafe.html">threading mode</a> of individual <a href="c3ref/sqlite3.html">database connections</a> |
| 932 |
at run-time.</p> |
| 933 |
|
| 934 |
<p> Note that when SQLite is compiled with SQLITE_THREADSAFE=0, the code |
| 935 |
to make SQLite threadsafe is omitted from the build. When this occurs, |
| 936 |
it is impossible to change the <a href="threadsafe.html">threading mode</a> at start-time or run-time.</p> |
| 937 |
|
| 938 |
<p> See the <a href="threadsafe.html">threading mode</a> documentation for additional information |
| 939 |
on aspects of using SQLite in a multithreaded environment. |
| 940 |
</p></blockquote><a name="temp_store"></a> |
| 941 |
<p><b>SQLITE_TEMP_STORE=<i><0 through 3></i></b></p><blockquote><p> |
| 942 |
This option controls whether temporary files are stored on disk or |
| 943 |
in memory. The meanings for various settings of this compile-time |
| 944 |
option are as follows:</p> |
| 945 |
|
| 946 |
<p> <table cellpadding="2" border="1"> |
| 947 |
<tr><th>SQLITE_TEMP_STORE</th><th>Meaning</th></tr> |
| 948 |
<tr><td align="center">0</td><td>Always use temporary files</td></tr> |
| 949 |
<tr><td align="center">1</td><td>Use files by default but allow the |
| 950 |
<a href="pragma.html#pragma_temp_store">PRAGMA temp_store</a> command to override</td></tr> |
| 951 |
<tr><td align="center">2</td><td>Use memory by default but allow the |
| 952 |
<a href="pragma.html#pragma_temp_store">PRAGMA temp_store</a> command to override</td></tr> |
| 953 |
<tr><td align="center">3</td><td>Always use memory</td></tr> |
| 954 |
</table></p> |
| 955 |
|
| 956 |
<p> The default setting is 1. |
| 957 |
Additional information can be found in <a href="tempfiles.html#tempstore">tempfiles.html</a>. |
| 958 |
</p></blockquote><a name="trace_size_limit"></a> |
| 959 |
<p><b>SQLITE_TRACE_SIZE_LIMIT=<i>N</i></b></p><blockquote><p> |
| 960 |
If this macro is defined to a positive integer <i>N</i>, then the length of |
| 961 |
strings and BLOBs that are expanded into parameters in the output of |
| 962 |
<a href="c3ref/profile.html">sqlite3_trace()</a> is limited to <i>N</i> bytes. |
| 963 |
</p></blockquote><a name="trusted_schema"></a> |
| 964 |
<p><b>SQLITE_TRUSTED_SCHEMA=<i><0 or 1></i></b></p><blockquote><p> |
| 965 |
This macro determines the default value for the |
| 966 |
<a href="c3ref/c_dbconfig_defensive.html#sqlitedbconfigtrustedschema">SQLITE_DBCONFIG_TRUSTED_SCHEMA</a> and <a href="pragma.html#pragma_trusted_schema">PRAGMA trusted_schema</a> setting. |
| 967 |
If no alternative is specified, the trusted-schema setting defaults |
| 968 |
to ON (a value of 1) for legacy compatibility. However, for best |
| 969 |
security, systems that implement |
| 970 |
<a href="appfunc.html">application-defined SQL functions</a> and/or <a href="vtab.html">virtual tables</a> should |
| 971 |
consider changing the default to OFF. |
| 972 |
</p></blockquote><a name="use_uri"></a> |
| 973 |
<p><b>SQLITE_USE_URI</b></p><blockquote><p> |
| 974 |
This option causes the <a href="uri.html">URI filename</a> process logic to be enabled by |
| 975 |
default. |
| 976 |
</p></blockquote> |
| 977 |
|
| 978 |
<a name="enablefeatures"></a> |
| 979 |
<h1 id="_options_to_enable_features_normally_turned_off"><span>7. </span> Options To Enable Features Normally Turned Off</h1> |
| 980 |
|
| 981 |
<a name="allow_uri_authority"></a> |
| 982 |
<p><b>SQLITE_ALLOW_URI_AUTHORITY</b></p><blockquote><p> |
| 983 |
<a href="uri.html">URI filenames</a> normally throws an error if the authority section is |
| 984 |
not either empty or "localhost". However, if SQLite is compiled with |
| 985 |
the SQLITE_ALLOW_URI_AUTHORITY compile-time option, then the URI is |
| 986 |
converted into a Uniform Naming Convention (UNC) filename and passed |
| 987 |
down to the underlying operating system that way. |
| 988 |
<p> |
| 989 |
Some future versions of SQLite may change to enable this feature |
| 990 |
by default. |
| 991 |
</p></blockquote><a name="allow_covering_index_scan"></a> |
| 992 |
<p><b>SQLITE_ALLOW_COVERING_INDEX_SCAN=<i><0 or 1></i></b></p><blockquote><p> |
| 993 |
This C-preprocess macro determines the default setting of the |
| 994 |
<a href="c3ref/c_config_covering_index_scan.html#sqliteconfigcoveringindexscan">SQLITE_CONFIG_COVERING_INDEX_SCAN</a> configuration setting. It defaults |
| 995 |
to 1 (on) which means that covering indices are used for full table |
| 996 |
scans where possible, in order to reduce I/O and improve performance. |
| 997 |
However, the use of a covering index for a full scan will cause results |
| 998 |
to appear in a different order from legacy, which could cause some |
| 999 |
(incorrectly-coded) legacy applications to break. Hence, the covering |
| 1000 |
index scan option can be disabled at compile-time on systems that want |
| 1001 |
to minimize their risk of exposing errors in legacy applications. |
| 1002 |
</p></blockquote><a name="enable_8_3_names"></a> |
| 1003 |
<p><b>SQLITE_ENABLE_8_3_NAMES=<i><1 or 2></i></b></p><blockquote><p> |
| 1004 |
If this C-preprocessor macro is defined, then extra code is |
| 1005 |
included that allows SQLite to function on a filesystem that |
| 1006 |
only supports 8+3 filenames. If the value of this macro is 1, |
| 1007 |
then the default behavior is to continue to use long filenames and |
| 1008 |
to only use 8+3 filenames if the |
| 1009 |
database connection is opened using <a href="uri.html">URI filenames</a> with |
| 1010 |
the "<tt>8_3_names=1</tt>" query parameter. If the value of |
| 1011 |
this macro is 2, then the use of 8+3 filenames becomes the default |
| 1012 |
but may be disabled on using the <tt>8_3_names=0</tt> query parameter. |
| 1013 |
</p></blockquote><a name="enable_api_armor"></a> |
| 1014 |
<p><b>SQLITE_ENABLE_API_ARMOR</b></p><blockquote><p> |
| 1015 |
When defined, this C-preprocessor macro activates extra code that |
| 1016 |
attempts to detect misuse of the SQLite API, such as passing in NULL |
| 1017 |
pointers to required parameters or using objects after they have been |
| 1018 |
destroyed. When this option is enabled and an illegal API usage |
| 1019 |
is detected, the interface will typically return SQLITE_MISUSE. |
| 1020 |
<p> |
| 1021 |
The SQLITE_ENABLE_API_ARMOR option does not guarantee that all |
| 1022 |
illegal API usages will be detected. Even when |
| 1023 |
SQLITE_ENABLE_API_ARMOR is enabled, passing incorrect values |
| 1024 |
into the C-language APIs can cause a process crash due to segmentation |
| 1025 |
fault or null-pointer deference or other reasons. The |
| 1026 |
SQLITE_ENABLE_API_ARMOR compile-time option is intended as an aid |
| 1027 |
for application testing and debugging option. Applications |
| 1028 |
should not depend on SQLITE_ENABLE_API_ARMOR for safety. |
| 1029 |
SQLITE_ENABLE_API_ARMOR is appropriate as a second line of |
| 1030 |
defense against application bugs, but it should not be the only |
| 1031 |
defense. If any SQLite interface returns SQLITE_MISUSE, that |
| 1032 |
indicates that the application is using SQLite contrary to |
| 1033 |
the spec and that the application contains a bug. The SQLITE_MISUSE |
| 1034 |
return provides the application with the opportunity to respond |
| 1035 |
gracefully to that bug, rather than simply crashing the process or |
| 1036 |
invoking undefined behavior, but nothing more. Applications should |
| 1037 |
neither make use of nor depend upon SQLITE_MISUSE for routine processing. |
| 1038 |
</p></blockquote><a name="enable_atomic_write"></a> |
| 1039 |
<p><b>SQLITE_ENABLE_ATOMIC_WRITE</b></p><blockquote><p> |
| 1040 |
If this C-preprocessor macro is defined and if the |
| 1041 |
xDeviceCharacteristics method of <a href="c3ref/io_methods.html">sqlite3_io_methods</a> object for |
| 1042 |
a database file reports (via one of the <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC</a> bits) |
| 1043 |
that the filesystem supports atomic writes and if a transaction |
| 1044 |
involves a change to only a single page of the database file, |
| 1045 |
then the transaction commits with just a single write request of |
| 1046 |
a single page of the database and no rollback journal is created |
| 1047 |
or written. On filesystems that support atomic writes, this |
| 1048 |
optimization can result in significant speed improvements for |
| 1049 |
small updates. However, few filesystems support this capability |
| 1050 |
and the code paths that check for this capability slow down write |
| 1051 |
performance on systems that lack atomic write capability, so this |
| 1052 |
feature is disabled by default. |
| 1053 |
</p></blockquote><a name="enable_batch_atomic_write"></a> |
| 1054 |
<p><b>SQLITE_ENABLE_BATCH_ATOMIC_WRITE</b></p><blockquote><p> |
| 1055 |
This compile-time option enables SQLite to take advantage of batch |
| 1056 |
atomic write capabilities in the underlying filesystem. As of |
| 1057 |
SQLite version 3.21.0 (2017-10-24) this is only supported on |
| 1058 |
<a href="https://en.wikipedia.org/wiki/F2FS">F2FS</a>. However, the interface |
| 1059 |
is implemented generically, using <a href="c3ref/file_control.html">sqlite3_file_control()</a> with |
| 1060 |
<a href="c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlbeginatomicwrite">SQLITE_FCNTL_BEGIN_ATOMIC_WRITE</a> and <a href="c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlcommitatomicwrite">SQLITE_FCNTL_COMMIT_ATOMIC_WRITE</a> |
| 1061 |
so the capability can be added to other filesystems in the |
| 1062 |
future. When this option is enabled, SQLite automatically detects |
| 1063 |
that the underlying filesystem supports batch atomic writes, and |
| 1064 |
when it does so it avoids writing the <a href="lockingv3.html#rollback">rollback journal</a> for transaction |
| 1065 |
control. This can make transactions over twice as fast, while |
| 1066 |
simultaneously reducing wear on SSD storage devices. |
| 1067 |
<p> |
| 1068 |
Future versions of SQLite might enable the batch-atomic-write |
| 1069 |
capability by default, at which point this compile-time option |
| 1070 |
will become superfluous. |
| 1071 |
</p></blockquote><a name="enable_bytecode_vtab"></a> |
| 1072 |
<p><b>SQLITE_ENABLE_BYTECODE_VTAB</b></p><blockquote><p> |
| 1073 |
This option enables the <a href="bytecodevtab.html">bytecode and tables_used virtual tables</a>. |
| 1074 |
</p></blockquote><a name="enable_carray"></a> |
| 1075 |
<p><b>SQLITE_ENABLE_CARRAY</b></p><blockquote><p> |
| 1076 |
This option enables the <a href="carray.html">carray() extension</a>, which has been available in |
| 1077 |
<a href="amalgamation.html">the amalgamation</a> since SQLite version 3.51.0 (2025-11-04). Prior to |
| 1078 |
version 3.51.0, the carray() extension was in a separate source code file that |
| 1079 |
needed to be compiled independently and linked as a <a href="loadext.html">loadable extension</a>. |
| 1080 |
</p></blockquote><a name="enable_column_metadata"></a> |
| 1081 |
<p><b>SQLITE_ENABLE_COLUMN_METADATA</b></p><blockquote><p> |
| 1082 |
When this C-preprocessor macro is defined, SQLite includes some |
| 1083 |
additional APIs that provide convenient access to meta-data about |
| 1084 |
tables and queries. The APIs that are enabled by this option are:</p> |
| 1085 |
|
| 1086 |
<p> <ul> |
| 1087 |
<li> <a href="c3ref/column_database_name.html">sqlite3_column_database_name()</a> </li> |
| 1088 |
<li> <a href="c3ref/column_database_name.html">sqlite3_column_database_name16()</a> </li> |
| 1089 |
<li> <a href="c3ref/column_database_name.html">sqlite3_column_table_name()</a> </li> |
| 1090 |
<li> <a href="c3ref/column_database_name.html">sqlite3_column_table_name16()</a> </li> |
| 1091 |
<li> <a href="c3ref/column_database_name.html">sqlite3_column_origin_name()</a> </li> |
| 1092 |
<li> <a href="c3ref/column_database_name.html">sqlite3_column_origin_name16()</a> </li> |
| 1093 |
</ul> |
| 1094 |
</p></blockquote><a name="enable_dbpage_vtab"></a> |
| 1095 |
<p><b>SQLITE_ENABLE_DBPAGE_VTAB</b></p><blockquote><p> |
| 1096 |
This option enables the <a href="dbpage.html">SQLITE_DBPAGE virtual table</a>. |
| 1097 |
</p></blockquote><a name="enable_dbstat_vtab"></a> |
| 1098 |
<p><b>SQLITE_ENABLE_DBSTAT_VTAB</b></p><blockquote><p> |
| 1099 |
This option enables the <a href="dbstat.html">dbstat virtual table</a>. |
| 1100 |
</p></blockquote><a name="enable_deserialize"></a> |
| 1101 |
<p><b>SQLITE_ENABLE_DESERIALIZE</b></p><blockquote><p> |
| 1102 |
This option was formerly used to enable |
| 1103 |
the <a href="c3ref/serialize.html">sqlite3_serialize()</a> and <a href="c3ref/deserialize.html">sqlite3_deserialize()</a> |
| 1104 |
interfaces. However, as of SQLite 3.36.0 (2021-06-18) |
| 1105 |
those interfaces are enabled by default and a new |
| 1106 |
compile-time option <a href="compile.html#omit_deserialize">SQLITE_OMIT_DESERIALIZE</a> is added |
| 1107 |
to omit them. |
| 1108 |
</p></blockquote><a name="enable_explain_comments"></a> |
| 1109 |
<p><b>SQLITE_ENABLE_EXPLAIN_COMMENTS</b></p><blockquote><p> |
| 1110 |
This option adds extra logic to SQLite that inserts comment text into the |
| 1111 |
output of <a href="lang_explain.html">EXPLAIN</a>. These extra comments use extra memory, thus |
| 1112 |
making <a href="c3ref/stmt.html">prepared statements</a> larger and very slightly slower, and so they are |
| 1113 |
turned off by default and in most applications. But some applications, such |
| 1114 |
as the <a href="cli.html">command-line shell</a> for SQLite, value clarity of EXPLAIN output |
| 1115 |
over raw performance and so this compile-time option is available to them. |
| 1116 |
The SQLITE_ENABLE_EXPLAIN_COMMENTS compile-time option is also enabled |
| 1117 |
automatically if <a href="compile.html#debug">SQLITE_DEBUG</a> is enabled. |
| 1118 |
</p></blockquote><a name="enable_fts3"></a> |
| 1119 |
<p><b>SQLITE_ENABLE_FTS3</b></p><blockquote><p> |
| 1120 |
When this option is defined in the <a href="amalgamation.html">amalgamation</a>, versions 3 and 4 |
| 1121 |
of the full-text search engine are added to the build automatically. |
| 1122 |
</p></blockquote><a name="enable_fts3_parenthesis"></a> |
| 1123 |
<p><b>SQLITE_ENABLE_FTS3_PARENTHESIS</b></p><blockquote><p> |
| 1124 |
This option modifies the query pattern parser in FTS3 such that it |
| 1125 |
supports operators AND and NOT (in addition to the usual OR and NEAR) |
| 1126 |
and also allows query expressions to contain nested parentheses. |
| 1127 |
</p></blockquote><a name="enable_fts3_tokenizer"></a> |
| 1128 |
<p><b>SQLITE_ENABLE_FTS3_TOKENIZER</b></p><blockquote><p> |
| 1129 |
This option enables the two-argument version of the <a href="fts3.html#f3tknzr">fts3_tokenizer()</a> |
| 1130 |
interface. The second argument to fts3_tokenizer() should be a |
| 1131 |
pointer to a function (encoded as a BLOB) that implements an |
| 1132 |
application defined tokenizer. If hostile actors are able to run |
| 1133 |
the two-argument version of fts3_tokenizer() with an arbitrary second |
| 1134 |
argument, they could crash or take control of the process. |
| 1135 |
<p> |
| 1136 |
Because of security concerns, the two-argument fts3_tokenizer() feature |
| 1137 |
was disabled beginning with <a href="releaselog/3_11_0.html">Version 3.11.0</a> (2016-02-15) |
| 1138 |
unless this compile-time option is used. |
| 1139 |
<a href="releaselog/3_12_0.html">Version 3.12.0</a> (2016-03-29) added the |
| 1140 |
<a href="c3ref/db_config.html">sqlite3_db_config</a>(db,<a href="c3ref/c_dbconfig_defensive.html#sqlitedbconfigenablefts3tokenizer">SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</a>,1,0) interface |
| 1141 |
that activates the two-argument version of <a href="fts3.html#f3tknzr">fts3_tokenizer()</a> |
| 1142 |
for a specific <a href="c3ref/sqlite3.html">database connection</a> at run-time. |
| 1143 |
</p></blockquote><a name="enable_fts4"></a> |
| 1144 |
<p><b>SQLITE_ENABLE_FTS4</b></p><blockquote><p> |
| 1145 |
When this option is defined in the <a href="amalgamation.html">amalgamation</a>, versions 3 and 4 |
| 1146 |
of the full-text search engine are added to the build automatically. |
| 1147 |
</p></blockquote><a name="enable_fts5"></a> |
| 1148 |
<p><b>SQLITE_ENABLE_FTS5</b></p><blockquote><p> |
| 1149 |
When this option is defined in the <a href="amalgamation.html">amalgamation</a>, version 5 |
| 1150 |
of the full-text search engine (<a href="fts5.html">fts5</a>) is added to the build automatically. |
| 1151 |
</p></blockquote><a name="enable_geopoly"></a> |
| 1152 |
<p><b>SQLITE_ENABLE_GEOPOLY</b></p><blockquote><p> |
| 1153 |
When this option is defined in the <a href="amalgamation.html">amalgamation</a>, the <a href="geopoly.html">Geopoly extension</a> |
| 1154 |
is included in the build. |
| 1155 |
</p></blockquote><a name="enable_hidden_columns"></a> |
| 1156 |
<p><b>SQLITE_ENABLE_HIDDEN_COLUMNS</b></p><blockquote><p> |
| 1157 |
When this option is defined in the <a href="amalgamation.html">amalgamation</a>, |
| 1158 |
The <a href="vtab.html#hiddencol">hidden columns</a> feature is enabled for virtual tables. |
| 1159 |
</p></blockquote><a name="enable_icu"></a> |
| 1160 |
<p><b>SQLITE_ENABLE_ICU</b></p><blockquote><p> |
| 1161 |
This option causes the |
| 1162 |
<a href="https://icu.unicode.org">International Components for Unicode</a> |
| 1163 |
or "ICU" extension to SQLite to be added to the build. |
| 1164 |
</p></blockquote><a name="enable_iotrace"></a> |
| 1165 |
<p><b>SQLITE_ENABLE_IOTRACE</b></p><blockquote><p> |
| 1166 |
When both the SQLite core and the <a href="cli.html">Command Line Interface</a> (CLI) are both |
| 1167 |
compiled with this option, then the CLI provides an extra command |
| 1168 |
named ".iotrace" that provides a low-level log of I/O activity. |
| 1169 |
This option is experimental and may be discontinued in a future release. |
| 1170 |
</p></blockquote><a name="enable_json1"></a> |
| 1171 |
<p><b>SQLITE_ENABLE_JSON1</b></p><blockquote><p> |
| 1172 |
This compile-time option is a no-op. Prior to SQLite version 3.38.0 |
| 1173 |
(2022-02-22), it was necessary to compile with this option in order |
| 1174 |
to include the <a href="json1.html">JSON SQL functions</a> in the build. However, beginning |
| 1175 |
with SQLite version 3.38.0, those functions are included by default. |
| 1176 |
Use the <a href="compile.html#omit_json">-DSQLITE_OMIT_JSON</a> option to omit them. |
| 1177 |
</p></blockquote><a name="enable_locking_style"></a> |
| 1178 |
<p><b>SQLITE_ENABLE_LOCKING_STYLE</b></p><blockquote><p> |
| 1179 |
This option enables additional logic in the OS interface layer for |
| 1180 |
Mac OS X. The additional logic attempts to determine the type of the |
| 1181 |
underlying filesystem and choose an alternative locking strategy |
| 1182 |
that works correctly for that filesystem type. Five locking strategies |
| 1183 |
are available:</p> |
| 1184 |
|
| 1185 |
<p> <ul> |
| 1186 |
<li> POSIX locking style. This is the default locking style and the |
| 1187 |
style used by other (non Mac OS X) Unixes. Locks are obtained and |
| 1188 |
released using the fcntl() system call.</p> |
| 1189 |
|
| 1190 |
<p> <li> AFP locking style. This locking style is used for network file |
| 1191 |
systems that use the AFP (Apple Filing Protocol) protocol. Locks |
| 1192 |
are obtained by calling the library function _AFPFSSetLock().</p> |
| 1193 |
|
| 1194 |
<p> <li> Flock locking style. This is used for file-systems that do not |
| 1195 |
support POSIX locking style. Locks are obtained and released using |
| 1196 |
the flock() system call.</p> |
| 1197 |
|
| 1198 |
<p> <li> Dot-file locking style. This locking style is used when neither |
| 1199 |
flock nor POSIX locking styles are supported by the file system. |
| 1200 |
Database locks are obtained by creating an entry in the file-system |
| 1201 |
at a well-known location relative to the database file (a "dot-file") |
| 1202 |
and relinquished by deleting the same file.</p> |
| 1203 |
|
| 1204 |
<p> <li> No locking style. If none of the above can be supported, this |
| 1205 |
locking style is used. No database locking mechanism is used. When |
| 1206 |
this system is used it is not safe for a single database to be |
| 1207 |
accessed by multiple clients. |
| 1208 |
</ul></p> |
| 1209 |
|
| 1210 |
<p> Additionally, five extra <a href="vfs.html">VFS</a> implementations are provided as well as the |
| 1211 |
default. By specifying one of the extra VFS implementations |
| 1212 |
when calling <a href="c3ref/open.html">sqlite3_open_v2()</a>, an application may bypass the file-system |
| 1213 |
detection logic and explicitly select one of the above locking styles. The |
| 1214 |
five extra <a href="vfs.html">VFS</a> implementations are called "unix-posix", "unix-afp", |
| 1215 |
"unix-flock", "unix-dotfile" and "unix-none". |
| 1216 |
</p></blockquote><a name="enable_math_functions"></a> |
| 1217 |
<p><b>SQLITE_ENABLE_MATH_FUNCTIONS</b></p><blockquote><p> |
| 1218 |
This macro enables the <a href="lang_mathfunc.html">built-in SQL math functions</a>. This option |
| 1219 |
is automatically added to the Makefile by the configure script on unix platforms, |
| 1220 |
unless the --disable-math option is used. |
| 1221 |
This option is also included on Windows builds using the |
| 1222 |
"Makefile.msc" makefile for nmake. |
| 1223 |
</p></blockquote><a name="enable_memory_management"></a> |
| 1224 |
<p><b>SQLITE_ENABLE_MEMORY_MANAGEMENT</b></p><blockquote><p> |
| 1225 |
This option adds extra logic to SQLite that allows it to release unused |
| 1226 |
memory upon request. This option must be enabled in order for the |
| 1227 |
<a href="c3ref/release_memory.html">sqlite3_release_memory()</a> interface to work. If this compile-time |
| 1228 |
option is not used, the <a href="c3ref/release_memory.html">sqlite3_release_memory()</a> interface is a |
| 1229 |
no-op. |
| 1230 |
</p></blockquote><a name="enable_memsys3"></a> |
| 1231 |
<p><b>SQLITE_ENABLE_MEMSYS3</b></p><blockquote><p> |
| 1232 |
This option includes code in SQLite that implements an alternative |
| 1233 |
memory allocator. This alternative memory allocator is only engaged |
| 1234 |
when the <a href="c3ref/c_config_covering_index_scan.html#sqliteconfigheap">SQLITE_CONFIG_HEAP</a> option to <a href="c3ref/config.html">sqlite3_config()</a> is used to |
| 1235 |
supply a large chunk of memory from which all memory allocations are |
| 1236 |
taken. |
| 1237 |
The MEMSYS3 memory allocator uses a hybrid allocation algorithm |
| 1238 |
patterned after dlmalloc(). Only one of SQLITE_ENABLE_MEMSYS3 and |
| 1239 |
SQLITE_ENABLE_MEMSYS5 may be enabled at once. |
| 1240 |
</p></blockquote><a name="enable_memsys5"></a> |
| 1241 |
<p><b>SQLITE_ENABLE_MEMSYS5</b></p><blockquote><p> |
| 1242 |
This option includes code in SQLite that implements an alternative |
| 1243 |
memory allocator. This alternative memory allocator is only engaged |
| 1244 |
when the <a href="c3ref/c_config_covering_index_scan.html#sqliteconfigheap">SQLITE_CONFIG_HEAP</a> option to <a href="c3ref/config.html">sqlite3_config()</a> is used to |
| 1245 |
supply a large chunk of memory from which all memory allocations are |
| 1246 |
taken. |
| 1247 |
The MEMSYS5 module rounds all allocations up to the next power |
| 1248 |
of two and uses a first-fit, buddy-allocator algorithm |
| 1249 |
that provides strong guarantees against fragmentation and breakdown |
| 1250 |
subject to certain operating constraints. |
| 1251 |
</p></blockquote><a name="enable_normalize"></a> |
| 1252 |
<p><b>SQLITE_ENABLE_NORMALIZE</b></p><blockquote><p> |
| 1253 |
This option includes the <a href="c3ref/expanded_sql.html">sqlite3_normalized_sql()</a> API. |
| 1254 |
</p></blockquote><a name="enable_null_trim"></a> |
| 1255 |
<p><b>SQLITE_ENABLE_NULL_TRIM</b></p><blockquote><p> |
| 1256 |
This option enables an optimization that omits NULL columns at |
| 1257 |
the ends of rows, for a space savings on disk. |
| 1258 |
<p> |
| 1259 |
Databases generated with this option enabled are not readable |
| 1260 |
by SQLite version 3.1.6 (2005-03-17) and earlier. Also, |
| 1261 |
databases generated with this option enabled are prone to |
| 1262 |
triggering the |
| 1263 |
<a href="https://sqlite.org/src/info/e6e962d6b0f06f46e">e6e962d6b0f06f46</a> |
| 1264 |
bug in the <a href="c3ref/blob_reopen.html">sqlite3_blob_reopen()</a> interface. For those reasons, |
| 1265 |
this optimization is disabled by default. However, this optimization |
| 1266 |
may be enabled by default in a future release of SQLite. |
| 1267 |
</p></blockquote><a name="enable_offset_sql_func"></a> |
| 1268 |
<p><b>SQLITE_ENABLE_OFFSET_SQL_FUNC</b></p><blockquote><p> |
| 1269 |
This option enables support for the <a href="lang_corefunc.html#sqlite_offset">sqlite_offset(X)</a> SQL function. |
| 1270 |
<p> |
| 1271 |
The <a href="lang_corefunc.html#sqlite_offset">sqlite_offset(X)</a> SQL function requires a new interface on the |
| 1272 |
B-tree storage engine, a new opcode in the <a href="opcode.html">virtual machine</a> that |
| 1273 |
runs SQL statements, and a new conditional in a critical path of the |
| 1274 |
code generator. To avoid that overhead in applications that do not |
| 1275 |
need the utility of sqlite_offset(X), the function is disabled by |
| 1276 |
default. |
| 1277 |
</p></blockquote><a name="enable_ordered_set_aggregates"></a> |
| 1278 |
<p><b>SQLITE_ENABLE_ORDERED_SET_AGGREGATES</b></p><blockquote><p> |
| 1279 |
This option enables support for the "WITHIN GROUP ORDER BY" |
| 1280 |
ordered-set aggregate syntax. For example: |
| 1281 |
<p><pre> |
| 1282 |
SELECT percentile_cont(0.75) WITHIN GROUP (ORDER BY x) FROM tab;</pre> |
| 1283 |
<p>The above is the SQL-standard way to compute the 75th-percentile |
| 1284 |
value of a distribution. The usual way to do this in SQLite is |
| 1285 |
as follows: |
| 1286 |
<p><pre> |
| 1287 |
SELECT percentile_cont(x,0.75) FROM tab;</pre> |
| 1288 |
<p>Though simpler, easier to read, and easier to type, this syntax |
| 1289 |
is <i>not</i> compliant with standard SQL. The simpler, non-standard |
| 1290 |
syntax is always available in SQLite. But the SQL-standard compliant |
| 1291 |
syntax is only available if compiled using |
| 1292 |
-DSQLITE_ENABLE_ORDERED_SET_AGGREGATES. |
| 1293 |
The SQL-standard compliant syntax is disabled by default because (A) |
| 1294 |
it requires about 1,200 bytes of extra code in the compiled SQLite binary |
| 1295 |
and (B) because it makes your SQL code more difficult to read, write, |
| 1296 |
and understand without adding any value. Use this option only if you need |
| 1297 |
to write cross-platform SQL that uses ordered-set aggregate functions |
| 1298 |
such as <a href="lang_aggfunc.html#percentile_cont">percentile_cont()</a>. |
| 1299 |
<p> |
| 1300 |
Using this compile-time option adds WITHIN as a keyword. |
| 1301 |
<p> |
| 1302 |
The ordered-set aggregate syntax can only be used by aggregate functions |
| 1303 |
that have the <a href="c3ref/c_deterministic.html#sqliteselforder1">SQLITE_SELFORDER1</a> property. If the |
| 1304 |
SQLITE_ENABLE_ORDERED_SET_AGGREGATES compile-time option is not specified, |
| 1305 |
then the <a href="c3ref/c_deterministic.html#sqliteselforder1">SQLITE_SELFORDER1</a> property is essentially a no-op. |
| 1306 |
<p> |
| 1307 |
This compile-time option only works when building from canonical source |
| 1308 |
code, since it changes the LALR(1) parser tables. This compile-time |
| 1309 |
option cannot be used to change the behavior of an <a href="amalgamation.html">amalgamation</a>. |
| 1310 |
</p></blockquote><a name="enable_percentile"></a> |
| 1311 |
<p><b>SQLITE_ENABLE_PERCENTILE</b></p><blockquote><p> |
| 1312 |
This option enables the <a href="percentile.html">percentile extension</a>, which has been available in |
| 1313 |
<a href="amalgamation.html">the amalgamation</a> since SQLite version 3.51.0 (2025-11-04). Prior to |
| 1314 |
version 3.51.0, the percentile extension was in a separate source code file that |
| 1315 |
needed to be compiled independently and linked as a <a href="loadext.html">loadable extension</a>. |
| 1316 |
</p></blockquote><a name="enable_preupdate_hook"></a> |
| 1317 |
<p><b>SQLITE_ENABLE_PREUPDATE_HOOK</b></p><blockquote><p> |
| 1318 |
This option enables |
| 1319 |
<a href="c3ref/preupdate_blobwrite.html">several new APIs</a> that provide callbacks |
| 1320 |
prior to any change to a <a href="rowidtable.html">rowid table</a>. The callbacks can be used |
| 1321 |
to record the state of the row before the change occurs. |
| 1322 |
<p>The action of the preupdate hook is similar to the |
| 1323 |
<a href="c3ref/update_hook.html">update hook</a> except that the callback is |
| 1324 |
invoked before the change, not afterwards, and the preupdate |
| 1325 |
hook interfaces are omitted unless this compile-time option is |
| 1326 |
used. |
| 1327 |
<p>The preupdate hook interfaces were originally added to |
| 1328 |
support the <a href="sessionintro.html">session</a> extension. |
| 1329 |
</p></blockquote><a name="enable_qpsg"></a> |
| 1330 |
<p><b>SQLITE_ENABLE_QPSG</b></p><blockquote><p> |
| 1331 |
This option causes the <a href="queryplanner-ng.html#qpstab">query planner stability guarantee</a> (QPSG) to |
| 1332 |
be on by default. Normally the QPSG is off and must be activated |
| 1333 |
at run-time using the <a href="c3ref/c_dbconfig_defensive.html#sqlitedbconfigenableqpsg">SQLITE_DBCONFIG_ENABLE_QPSG</a> option to the |
| 1334 |
<a href="c3ref/db_config.html">sqlite3_db_config()</a> interface. |
| 1335 |
</p></blockquote><a name="enable_rbu"></a> |
| 1336 |
<p><b>SQLITE_ENABLE_RBU</b></p><blockquote><p> |
| 1337 |
Enable the code that implements the <a href="rbu.html">RBU extension</a>. |
| 1338 |
</p></blockquote><a name="enable_rtree"></a> |
| 1339 |
<p><b>SQLITE_ENABLE_RTREE</b></p><blockquote><p> |
| 1340 |
This option causes SQLite to include support for the |
| 1341 |
<a href="rtree.html">R*Tree index extension</a>. |
| 1342 |
</p></blockquote><a name="enable_session"></a> |
| 1343 |
<p><b>SQLITE_ENABLE_SESSION</b></p><blockquote><p> |
| 1344 |
This option enables the <a href="sessionintro.html">session extension</a>. |
| 1345 |
</p></blockquote><a name="enable_snapshot"></a> |
| 1346 |
<p><b>SQLITE_ENABLE_SNAPSHOT</b></p><blockquote><p> |
| 1347 |
This option enables the code to support the <a href="c3ref/snapshot.html">sqlite3_snapshot</a> object |
| 1348 |
and its related interfaces: |
| 1349 |
<ul> |
| 1350 |
<li> <a href="c3ref/snapshot_get.html">sqlite3_snapshot_get()</a> (constructor) |
| 1351 |
<li> <a href="c3ref/snapshot_free.html">sqlite3_snapshot_free()</a> (destructor) |
| 1352 |
<li> <a href="c3ref/snapshot_open.html">sqlite3_snapshot_open()</a> |
| 1353 |
<li> <a href="c3ref/snapshot_cmp.html">sqlite3_snapshot_cmp()</a> |
| 1354 |
<li> <a href="c3ref/snapshot_recover.html">sqlite3_snapshot_recover()</a> |
| 1355 |
</ul> |
| 1356 |
</p></blockquote><a name="enable_sorter_references"></a> |
| 1357 |
<p><b>SQLITE_ENABLE_SORTER_REFERENCES</b></p><blockquote><p> |
| 1358 |
This option activates an optimization that reduces the memory required |
| 1359 |
by the sorter at the cost of doing additional B-tree lookups after |
| 1360 |
the sort has occurred. |
| 1361 |
<p> |
| 1362 |
The default sorting procedure is to gather all information that will |
| 1363 |
ultimately be output into a "record" and pass that complete record |
| 1364 |
to the sorter. But in some cases, for example if some of the output |
| 1365 |
columns consists of large BLOB values, the size of the each record |
| 1366 |
can be large, which means that the sorter has to either use more memory, |
| 1367 |
and/or write more content to temporary storage. |
| 1368 |
<p> |
| 1369 |
When SQLITE_ENABLE_SORTER_REFERENCES is enabled, the records passed to |
| 1370 |
the sorter often contain only a <a href="lang_createtable.html#rowid">ROWID</a> value. Such records are much |
| 1371 |
smaller. This means the sorter has much less "payload" to deal with and |
| 1372 |
can run faster. After sorting has occurred, the ROWID is used to look up |
| 1373 |
the output column values in the original table. That requires another |
| 1374 |
search into the table, and could potentially result in a slowdown. Or, |
| 1375 |
it might be a performance win, depending on how large the values are. |
| 1376 |
<p> |
| 1377 |
Even when the SQLITE_ENABLE_SORTER_REFERENCES compile-time option is on, |
| 1378 |
sorter references are still disabled by default. To use sorter references, |
| 1379 |
the application must set a sorter reference size threshold using the |
| 1380 |
<a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_covering_index_scan.html#sqliteconfigsorterrefsize">SQLITE_CONFIG_SORTERREF_SIZE</a>) interface at start-time. |
| 1381 |
<p> |
| 1382 |
Because the SQLite developers do not know whether the |
| 1383 |
SQLITE_ENABLE_SORTER_REFERENCES option will help or hurt performance, |
| 1384 |
it is disabled by default at this time (2018-05-04). It might be enabled |
| 1385 |
by default in some future release, depending on what is learned about its |
| 1386 |
impact on performance. |
| 1387 |
</p></blockquote><a name="enable_stmt_scanstatus"></a> |
| 1388 |
<p><b>SQLITE_ENABLE_STMT_SCANSTATUS</b></p><blockquote><p> |
| 1389 |
This option enables the <a href="c3ref/stmt_scanstatus.html">sqlite3_stmt_scanstatus()</a> and |
| 1390 |
<a href="c3ref/stmt_scanstatus.html">sqlite3_stmt_scanstatus_v2()</a> interfaces and activates the |
| 1391 |
<a href="bytecodevtab.html#nexec">nexec and ncycle</a> columns of the <a href="bytecodevtab.html">bytecode virtual table</a>. |
| 1392 |
These features are normally omitted or deactivated because they |
| 1393 |
impose a run-time performance cost even if unused. |
| 1394 |
<p> |
| 1395 |
The SQLITE_ENABLE_STMT_SCANSTATUS option is not recommended for |
| 1396 |
production builds because of the added run-time cost even when |
| 1397 |
the performance statistics are not used. But SQLITE_ENABLE_STMT_SCANSTATUS |
| 1398 |
is useful for diagnostic and debugging builds. |
| 1399 |
</p></blockquote><a name="enable_stmtvtab"></a> |
| 1400 |
<p><b>SQLITE_ENABLE_STMTVTAB</b></p><blockquote><p> |
| 1401 |
This compile-time option enables the <a href="stmt.html">SQLITE_STMT virtual table</a> logic. |
| 1402 |
</p></blockquote><a name="rtree_int_only"></a> |
| 1403 |
<p><b>SQLITE_RTREE_INT_ONLY</b></p><blockquote><p> |
| 1404 |
This compile-time option is deprecated and untested. |
| 1405 |
</p></blockquote><a name="enable_sqllog"></a> |
| 1406 |
<p><b>SQLITE_ENABLE_SQLLOG</b></p><blockquote><p> |
| 1407 |
This option enables extra code (especially the <a href="c3ref/c_config_covering_index_scan.html#sqliteconfigsqllog">SQLITE_CONFIG_SQLLOG</a> |
| 1408 |
option to <a href="c3ref/config.html">sqlite3_config()</a>) that can be used to create logs of all |
| 1409 |
SQLite processing performed by an application. These logs can be useful |
| 1410 |
in doing off-line analysis of the behavior of an application, and especially |
| 1411 |
for performance analysis. In order for the SQLITE_ENABLE_SQLLOG option to |
| 1412 |
be useful, some extra code is required. The |
| 1413 |
<a href="https://sqlite.org/src/doc/trunk/src/test_sqllog.c">"test_sqllog.c"</a> |
| 1414 |
source code |
| 1415 |
file in the SQLite source tree is a working example of the required extra |
| 1416 |
code. On unix and windows systems, a developer can append the text of the |
| 1417 |
"test_sqllog.c" source code file to the end of an "sqlite3.c" amalgamation, |
| 1418 |
recompile the application using the -DSQLITE_ENABLE_SQLLOG option, then |
| 1419 |
control logging using environment variables. See the header comment on |
| 1420 |
the "test_sqllog.c" source file for additional detail. |
| 1421 |
</p></blockquote><a name="enable_stat2"></a> |
| 1422 |
<p><b>SQLITE_ENABLE_STAT2</b></p><blockquote><p> |
| 1423 |
This option used to cause the <a href="lang_analyze.html">ANALYZE</a> command to collect |
| 1424 |
index histogram data in the <b>sqlite_stat2</b> table. But that |
| 1425 |
functionality was superseded by <a href="compile.html#enable_stat3">SQLITE_ENABLE_STAT3</a> as of |
| 1426 |
SQLite <a href="releaselog/3_7_9.html">version 3.7.9</a> (2011-11-01). |
| 1427 |
The SQLITE_ENABLE_STAT2 compile-time option |
| 1428 |
is now a no-op. |
| 1429 |
</p></blockquote><a name="enable_stat3"></a> |
| 1430 |
<p><b>SQLITE_ENABLE_STAT3</b></p><blockquote><p> |
| 1431 |
This option used to cause the <a href="lang_analyze.html">ANALYZE</a> command to collect |
| 1432 |
index histogram data in the <b>sqlite_stat3</b> table. But that |
| 1433 |
functionality was superseded by <a href="compile.html#enable_stat4">SQLITE_ENABLE_STAT4</a> as of |
| 1434 |
SQLite <a href="releaselog/3_8_1.html">version 3.8.1</a> (2013-10-17). |
| 1435 |
The SQLITE_ENABLE_STAT3 compile-time option |
| 1436 |
continued to be supported through <a href="releaselog/3_29_0.html">version 3.29.0</a> (2019-07-10) |
| 1437 |
but has now become a no-op. |
| 1438 |
<p> |
| 1439 |
</p></blockquote><a name="enable_stat4"></a> |
| 1440 |
<p><b>SQLITE_ENABLE_STAT4</b></p><blockquote><p> |
| 1441 |
This option adds additional logic to the <a href="lang_analyze.html">ANALYZE</a> command and to |
| 1442 |
the <a href="optoverview.html">query planner</a> that can help SQLite to choose a better query plan |
| 1443 |
under certain situations. The <a href="lang_analyze.html">ANALYZE</a> command is enhanced to collect |
| 1444 |
histogram data from all columns of every index and store that data |
| 1445 |
in the <a href="fileformat2.html#stat4tab">sqlite_stat4</a> table. The query planner will then use the |
| 1446 |
histogram data to help it make better index choices. The downside of |
| 1447 |
this compile-time option is that it violates the |
| 1448 |
<a href="queryplanner-ng.html#qpstab">query planner stability guarantee</a> making it more difficult to ensure |
| 1449 |
consistent performance in mass-produced applications. |
| 1450 |
<p> |
| 1451 |
SQLITE_ENABLE_STAT4 is an enhancement of <a href="compile.html#enable_stat3">SQLITE_ENABLE_STAT3</a>. STAT3 |
| 1452 |
only recorded histogram data for the left-most column of each index |
| 1453 |
whereas the STAT4 enhancement records histogram data from all columns |
| 1454 |
of each index. |
| 1455 |
The <a href="compile.html#enable_stat3">SQLITE_ENABLE_STAT3</a> compile-time option has become a no-op. |
| 1456 |
</p></blockquote><a name="enable_tree_explain"></a> |
| 1457 |
<p><b>SQLITE_ENABLE_TREE_EXPLAIN</b></p><blockquote><p> |
| 1458 |
This compile-time option is no longer used. |
| 1459 |
</p></blockquote><a name="enable_update_delete_limit"></a> |
| 1460 |
<p><b>SQLITE_ENABLE_UPDATE_DELETE_LIMIT</b></p><blockquote><p> |
| 1461 |
This option enables an optional ORDER BY and LIMIT clause on |
| 1462 |
<a href="lang_update.html">UPDATE</a> and <a href="lang_delete.html">DELETE</a> statements.</p> |
| 1463 |
|
| 1464 |
<p> <p>If this option is defined, then it must also be |
| 1465 |
defined when using the <a href="lemon.html">Lemon parser generator</a> tool to generate a parse.c |
| 1466 |
file. Because of this, this option may only be used when the library is built |
| 1467 |
from source, not from the <a href="amalgamation.html">amalgamation</a> or from the collection of |
| 1468 |
pre-packaged C files provided for non-Unix like platforms on the website. |
| 1469 |
</p> |
| 1470 |
</p></blockquote><a name="enable_unknown_sql_function"></a> |
| 1471 |
<p><b>SQLITE_ENABLE_UNKNOWN_SQL_FUNCTION</b></p><blockquote><p> |
| 1472 |
When the SQLITE_ENABLE_UNKNOWN_SQL_FUNCTION compile-time option is |
| 1473 |
activated, SQLite will suppress "unknown function" errors when running |
| 1474 |
an <a href="lang_explain.html">EXPLAIN</a> or <a href="eqp.html">EXPLAIN QUERY PLAN</a>. Instead of throwing an error, |
| 1475 |
SQLite will insert a substitute no-op function named "unknown()". |
| 1476 |
The substitution of "unknown()" in place of unrecognized functions |
| 1477 |
only occurs on <a href="lang_explain.html">EXPLAIN</a> and <a href="eqp.html">EXPLAIN QUERY PLAN</a>, not on ordinary |
| 1478 |
statements. |
| 1479 |
<p> |
| 1480 |
When used in the <a href="cli.html">command-line shell</a>, the |
| 1481 |
SQLITE_ENABLE_UNKNOWN_SQL_FUNCTION feature allows SQL text that contains |
| 1482 |
application-defined functions to be pasted into the shell for |
| 1483 |
analysis and debugging without having to create and load an |
| 1484 |
extension that implements the application-defined functions. |
| 1485 |
</p></blockquote><a name="enable_unlock_notify"></a> |
| 1486 |
<p><b>SQLITE_ENABLE_UNLOCK_NOTIFY</b></p><blockquote><p> |
| 1487 |
This option enables the <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify()</a> interface and |
| 1488 |
its associated functionality. See the documentation titled |
| 1489 |
<a href="unlock_notify.html">Using the SQLite Unlock Notification Feature</a> for additional |
| 1490 |
information. |
| 1491 |
</p></blockquote><a name="introspection_pragmas"></a> |
| 1492 |
<p><b>SQLITE_INTROSPECTION_PRAGMAS</b></p><blockquote><p> |
| 1493 |
This option is obsolete. It used to enable |
| 1494 |
some extra PRAGMA statements such as |
| 1495 |
<a href="pragma.html#pragma_function_list">PRAGMA function_list</a>, <a href="pragma.html#pragma_module_list">PRAGMA module_list</a>, and |
| 1496 |
<a href="pragma.html#pragma_pragma_list">PRAGMA pragma_list</a>, but those pragmas are now all |
| 1497 |
enabled by default. See <a href="compile.html#omit_introspection_pragmas">SQLITE_OMIT_INTROSPECTION_PRAGMAS</a>. |
| 1498 |
</p></blockquote><a name="soundex"></a> |
| 1499 |
<p><b>SQLITE_SOUNDEX</b></p><blockquote><p> |
| 1500 |
This option enables the <a href="lang_corefunc.html#soundex">soundex() SQL function</a>. |
| 1501 |
</p></blockquote><a name="strict_subtype"></a> |
| 1502 |
<p><b>SQLITE_STRICT_SUBTYPE=1</b></p><blockquote><p> |
| 1503 |
This option causes <a href="appfunc.html">application-defined SQL functions</a> to raise an SQL |
| 1504 |
error if they invoke the <a href="c3ref/result_subtype.html">sqlite3_result_subtype()</a> interface but |
| 1505 |
were not registered with the <a href="c3ref/c_deterministic.html#sqliteresultsubtype">SQLITE_RESULT_SUBTYPE</a> property. |
| 1506 |
This recommended option helps to identify problems in the |
| 1507 |
implementation of application-defined SQL functions early in the |
| 1508 |
development cycle. |
| 1509 |
</p></blockquote><a name="use_alloca"></a> |
| 1510 |
<p><b>SQLITE_USE_ALLOCA</b></p><blockquote><p> |
| 1511 |
If this option is enabled, then the alloca() memory allocator will be |
| 1512 |
used in a few situations where it is appropriate. This results in a slightly |
| 1513 |
smaller and faster binary. The SQLITE_USE_ALLOCA compile-time only |
| 1514 |
works, of course, on systems that support alloca(). |
| 1515 |
</p></blockquote><a name="use_fcntl_trace"></a> |
| 1516 |
<p><b>SQLITE_USE_FCNTL_TRACE</b></p><blockquote><p> |
| 1517 |
This option causes SQLite to issue extra <a href="c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntltrace">SQLITE_FCNTL_TRACE</a> file controls |
| 1518 |
to provide supplementary information to the VFS. The "vfslog.c" extension |
| 1519 |
makes use of this to provide enhanced logs of VFS activity. |
| 1520 |
</p></blockquote><a name="use_seh"></a> |
| 1521 |
<p><b>SQLITE_USE_SEH</b></p><blockquote><p> |
| 1522 |
This option used to be a toggle to enable what is now controlled |
| 1523 |
by <a href="compile.html#omit_seh">SQLITE_OMIT_SEH</a>. Client code should not use this define, |
| 1524 |
as it is used internally by the library. |
| 1525 |
</p></blockquote><a name="have_zlib"></a> |
| 1526 |
<p><b>SQLITE_HAVE_ZLIB</b></p><blockquote><p> |
| 1527 |
This option causes some extensions to link against the |
| 1528 |
<a href="https://zlib.net">zlib compression library</a>. |
| 1529 |
<p> |
| 1530 |
This option has no effect on the SQLite core. It is only used by extensions. |
| 1531 |
This option is necessary for the compression and decompression |
| 1532 |
functions that are part of <a href="sqlar.html">SQL Archive</a> support in the |
| 1533 |
<a href="cli.html">command-line shell</a>. |
| 1534 |
<p> |
| 1535 |
When compiling with this option, it will normally |
| 1536 |
be necessary to add a linker option to include the zlib library in the |
| 1537 |
build. Normally this option is "-lz" but might be different on different |
| 1538 |
systems. |
| 1539 |
<p> |
| 1540 |
When building with MSVC on Windows systems, one can put the zlib source |
| 1541 |
code in the compat/zlib subdirectory of the source tree and then add |
| 1542 |
the USE_ZLIB=1 option to the nmake command to cause the Makefile.msc |
| 1543 |
to automatically build and use an appropriate zlib library implementation. |
| 1544 |
</p></blockquote><a name="yytrackmaxstackdepth"></a> |
| 1545 |
<p><b>YYTRACKMAXSTACKDEPTH</b></p><blockquote><p> |
| 1546 |
This option causes the LALR(1) parser stack depth to be tracked |
| 1547 |
and reported using the <a href="c3ref/status.html">sqlite3_status</a>(<a href="c3ref/c_status_malloc_count.html#sqlitestatusparserstack">SQLITE_STATUS_PARSER_STACK</a>,...) |
| 1548 |
interface. SQLite's LALR(1) parser has a fixed stack depth |
| 1549 |
(determined at compile-time using the <a href="compile.html#yystackdepth">YYSTACKDEPTH</a> options). |
| 1550 |
This option can be used to help determine if an application is |
| 1551 |
getting close to exceeding the maximum LALR(1) stack depth. |
| 1552 |
</p></blockquote> |
| 1553 |
|
| 1554 |
<a name="disablefeatures"></a> |
| 1555 |
<h1 id="_options_to_disable_features_normally_turned_on"><span>8. </span> Options To Disable Features Normally Turned On</h1> |
| 1556 |
|
| 1557 |
<a name="disable_lfs"></a> |
| 1558 |
<p><b>SQLITE_DISABLE_LFS</b></p><blockquote><p> |
| 1559 |
If this C-preprocessor macro is defined, large file support |
| 1560 |
is disabled. |
| 1561 |
</p></blockquote><a name="disable_dirsync"></a> |
| 1562 |
<p><b>SQLITE_DISABLE_DIRSYNC</b></p><blockquote><p> |
| 1563 |
If this C-preprocessor macro is defined, directory syncs |
| 1564 |
are disabled. SQLite typically attempts to sync the parent |
| 1565 |
directory when a file is deleted to ensure the directory |
| 1566 |
entries are updated immediately on disk. |
| 1567 |
</p></blockquote><a name="disable_fts3_unicode"></a> |
| 1568 |
<p><b>SQLITE_DISABLE_FTS3_UNICODE</b></p><blockquote><p> |
| 1569 |
If this C-preprocessor macro is defined, the <a href="fts3.html#unicode61">unicode61</a> tokenizer |
| 1570 |
in <a href="fts3.html">FTS3</a> is omitted from the build and is unavailable to |
| 1571 |
applications. |
| 1572 |
</p></blockquote><a name="disable_fts4_deferred"></a> |
| 1573 |
<p><b>SQLITE_DISABLE_FTS4_DEFERRED</b></p><blockquote><p> |
| 1574 |
If defined, this C-preprocessor macro disables the "deferred token" optimization |
| 1575 |
in <a href="fts3.html#fts4">FTS4</a>. The "deferred token" optimization avoids loading massive |
| 1576 |
posting lists for terms that are in most documents of the collection |
| 1577 |
and instead simply scans for those tokens in the document source. <a href="fts3.html#fts4">FTS4</a> |
| 1578 |
should get exactly the same answer both with and without this optimization. |
| 1579 |
</p></blockquote><a name="disable_intrinsic"></a> |
| 1580 |
<p><b>SQLITE_DISABLE_INTRINSIC</b></p><blockquote><p> |
| 1581 |
This option disables the use of compiler-specific built-in functions |
| 1582 |
such as __builtin_bswap32() and __builtin_add_overflow() in GCC and Clang, |
| 1583 |
or _byteswap_ulong() and _ReadWriteBarrier() with MSVC. |
| 1584 |
</p></blockquote><a name="disable_pagecache_overflow_stats"></a> |
| 1585 |
<p><b>SQLITE_DISABLE_PAGECACHE_OVERFLOW_STATS</b></p><blockquote><p> |
| 1586 |
This option disables the collection of the <a href="c3ref/status.html">sqlite3_status()</a>, |
| 1587 |
<a href="c3ref/c_status_malloc_count.html#sqlitestatuspagecacheoverflow">SQLITE_STATUS_PAGECACHE_OVERFLOW</a> and <a href="c3ref/c_status_malloc_count.html#sqlitestatuspagecachesize">SQLITE_STATUS_PAGECACHE_SIZE</a> |
| 1588 |
statistics. Setting this option has been shown to increase performance in |
| 1589 |
high concurrency multi-threaded applications. |
| 1590 |
</p></blockquote> |
| 1591 |
|
| 1592 |
<a name="omitfeatures"></a> |
| 1593 |
|
| 1594 |
<h1 id="_options_to_omit_features"><span>9. </span> Options To Omit Features</h1> |
| 1595 |
|
| 1596 |
<p>The following options can be used to |
| 1597 |
<a href="footprint.html">reduce the size of the compiled library</a> |
| 1598 |
by omitting unused features. This is probably only useful |
| 1599 |
in embedded systems where space is especially tight, as even with all |
| 1600 |
features included the SQLite library is relatively small. Don't forget |
| 1601 |
to tell your compiler to optimize for binary size! (the -Os option if |
| 1602 |
using GCC). Telling your compiler to optimize for size usually has |
| 1603 |
a much larger impact on library footprint than employing any of these |
| 1604 |
compile-time options. You should also verify that |
| 1605 |
<a href="#debugoptions">debugging options</a> are disabled.</p> |
| 1606 |
|
| 1607 |
<p>The macros in this section do not require values. The following |
| 1608 |
compilation switches all have the same effect:<br> |
| 1609 |
-DSQLITE_OMIT_ALTERTABLE<br> |
| 1610 |
-DSQLITE_OMIT_ALTERTABLE=1<br> |
| 1611 |
-DSQLITE_OMIT_ALTERTABLE=0 |
| 1612 |
</p> |
| 1613 |
|
| 1614 |
<p>If any of these options are defined, then the same set of SQLITE_OMIT_* |
| 1615 |
options must also be defined when using the <a href="lemon.html">Lemon parser generator</a> |
| 1616 |
tool to generate the |
| 1617 |
parse.c file and when compiling the 'mkkeywordhash' tool which generates |
| 1618 |
the keywordhash.h file. |
| 1619 |
Because of this, these options may only be used when the library is built |
| 1620 |
from canonical source, not from the <a href="amalgamation.html">amalgamation</a>. |
| 1621 |
Some SQLITE_OMIT_* options might work, or appear to work, when used with |
| 1622 |
the <a href="amalgamation.html">amalgamation</a>. But this is not guaranteed. In general, always compile |
| 1623 |
from canonical sources in order to take advantage of SQLITE_OMIT_* options. |
| 1624 |
</p> |
| 1625 |
|
| 1626 |
<blockquote> |
| 1627 |
<i><b>Important Note:</b> The SQLITE_OMIT_* options may not work with the |
| 1628 |
<a href="amalgamation.html">amalgamation</a>. SQLITE_OMIT_* compile-time |
| 1629 |
options usually work correctly only when SQLite is built from canonical |
| 1630 |
source files. |
| 1631 |
</i> |
| 1632 |
</blockquote> |
| 1633 |
|
| 1634 |
|
| 1635 |
<p>Special versions of the SQLite amalgamation that do work with a |
| 1636 |
predetermined set of SQLITE_OMIT_* options can be generated. To do so, |
| 1637 |
make a copy of the Makefile.linux-gcc makefile template in the canonical |
| 1638 |
source code distribution. Change the name of your copy to simply "Makefile". |
| 1639 |
Then edit "Makefile" to set up appropriate compile-time options. Then |
| 1640 |
type: |
| 1641 |
</p><div class="codeblock"><pre>make clean; make sqlite3.c |
| 1642 |
</pre></div> |
| 1643 |
<p>The resulting "sqlite3.c" amalgamation code file (and its associated |
| 1644 |
header file "sqlite3.h") can then be moved to a non-unix platform |
| 1645 |
for final compilation using a native compiler.</p> |
| 1646 |
|
| 1647 |
<p>The SQLITE_OMIT_* options are unsupported. By this we mean that |
| 1648 |
an SQLITE_OMIT_* option that omits code from the build in the current |
| 1649 |
release might become a no-op in the next release. Or the other way around: |
| 1650 |
an SQLITE_OMIT_* that is a no-op in the current release might cause code |
| 1651 |
to be excluded in the next release. Also, not all SQLITE_OMIT_* options |
| 1652 |
are tested. Some SQLITE_OMIT_* options might cause SQLite to malfunction |
| 1653 |
and/or provide incorrect answers. |
| 1654 |
|
| 1655 |
</p><blockquote> |
| 1656 |
<i><b>Important Note:</b> |
| 1657 |
The SQLITE_OMIT_* compile-time options are mostly unsupported. |
| 1658 |
</i></blockquote> |
| 1659 |
|
| 1660 |
<p>The following are the available OMIT options: |
| 1661 |
|
| 1662 |
<a name="omit_altertable"></a> |
| 1663 |
<p><b>SQLITE_OMIT_ALTERTABLE</b></p><blockquote><p> |
| 1664 |
When this option is defined, the |
| 1665 |
<a href="lang_altertable.html">ALTER TABLE</a> command is not included in the |
| 1666 |
library. Executing an <a href="lang_altertable.html">ALTER TABLE</a> statement causes a parse error. |
| 1667 |
</p></blockquote><a name="omit_analyze"></a> |
| 1668 |
<p><b>SQLITE_OMIT_ANALYZE</b></p><blockquote><p> |
| 1669 |
When this option is defined, the <a href="lang_analyze.html">ANALYZE</a> command is omitted from |
| 1670 |
the build. |
| 1671 |
</p></blockquote><a name="omit_attach"></a> |
| 1672 |
<p><b>SQLITE_OMIT_ATTACH</b></p><blockquote><p> |
| 1673 |
When this option is defined, the <a href="lang_attach.html">ATTACH</a> and <a href="lang_detach.html">DETACH</a> commands are |
| 1674 |
omitted from the build. |
| 1675 |
</p></blockquote><a name="omit_authorization"></a> |
| 1676 |
<p><b>SQLITE_OMIT_AUTHORIZATION</b></p><blockquote><p> |
| 1677 |
Defining this option causes the |
| 1678 |
<a href="c3ref/set_authorizer.html">sqlite3_set_authorizer()</a> API function and related |
| 1679 |
logic to be omitted. |
| 1680 |
</p></blockquote><a name="omit_autoincrement"></a> |
| 1681 |
<p><b>SQLITE_OMIT_AUTOINCREMENT</b></p><blockquote><p> |
| 1682 |
This option is omits the <a href="autoinc.html">AUTOINCREMENT</a> feature. |
| 1683 |
When this is macro is defined, columns declared as |
| 1684 |
"<a href="lang_createtable.html#rowid">INTEGER PRIMARY KEY</a> AUTOINCREMENT" |
| 1685 |
behave in the same way as columns declared as "<a href="lang_createtable.html#rowid">INTEGER PRIMARY KEY</a>" when a |
| 1686 |
NULL is inserted. The sqlite_sequence system table is neither created, nor |
| 1687 |
respected if it already exists. |
| 1688 |
</p></blockquote><a name="omit_autoinit"></a> |
| 1689 |
<p><b>SQLITE_OMIT_AUTOINIT</b></p><blockquote><p> |
| 1690 |
For backwards compatibility with older versions of SQLite that lack |
| 1691 |
the <a href="c3ref/initialize.html">sqlite3_initialize()</a> interface, the <a href="c3ref/initialize.html">sqlite3_initialize()</a> interface |
| 1692 |
is called automatically upon entry to certain key interfaces such as |
| 1693 |
<a href="c3ref/open.html">sqlite3_open()</a>, <a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a>, and <a href="c3ref/mprintf.html">sqlite3_mprintf()</a>. |
| 1694 |
The overhead of invoking <a href="c3ref/initialize.html">sqlite3_initialize()</a> automatically in this |
| 1695 |
way may be omitted by building SQLite with the SQLITE_OMIT_AUTOINIT |
| 1696 |
C-preprocessor macro. When built using SQLITE_OMIT_AUTOINIT, SQLite |
| 1697 |
will not automatically initialize itself and the application is required |
| 1698 |
to invoke <a href="c3ref/initialize.html">sqlite3_initialize()</a> directly prior to beginning use of the |
| 1699 |
SQLite library. |
| 1700 |
</p></blockquote><a name="omit_automatic_index"></a> |
| 1701 |
<p><b>SQLITE_OMIT_AUTOMATIC_INDEX</b></p><blockquote><p> |
| 1702 |
This option is used to omit the |
| 1703 |
<a href="optoverview.html#autoindex">automatic indexing</a> functionality. |
| 1704 |
See also: <a href="compile.html#default_automatic_index">SQLITE_DEFAULT_AUTOMATIC_INDEX</a>. |
| 1705 |
</p></blockquote><a name="omit_autoreset"></a> |
| 1706 |
<p><b>SQLITE_OMIT_AUTORESET</b></p><blockquote><p> |
| 1707 |
By default, the <a href="c3ref/step.html">sqlite3_step()</a> interface will automatically invoke |
| 1708 |
<a href="c3ref/reset.html">sqlite3_reset()</a> to reset the <a href="c3ref/stmt.html">prepared statement</a> if necessary. This |
| 1709 |
compile-time option changes that behavior so that <a href="c3ref/step.html">sqlite3_step()</a> will |
| 1710 |
return <a href="rescode.html#misuse">SQLITE_MISUSE</a> if it is called again after returning anything other |
| 1711 |
than <a href="rescode.html#row">SQLITE_ROW</a>, <a href="rescode.html#busy">SQLITE_BUSY</a>, or <a href="rescode.html#locked">SQLITE_LOCKED</a> unless there was an |
| 1712 |
intervening call to <a href="c3ref/reset.html">sqlite3_reset()</a>.</p> |
| 1713 |
|
| 1714 |
<p> In SQLite <a href="releaselog/3_6_23_1.html">version 3.6.23.1</a> (2010-03-26) |
| 1715 |
and earlier, <a href="c3ref/step.html">sqlite3_step()</a> used to always |
| 1716 |
return <a href="rescode.html#misuse">SQLITE_MISUSE</a> if it was invoked again after returning anything |
| 1717 |
other than <a href="rescode.html#row">SQLITE_ROW</a> without an intervening call to <a href="c3ref/reset.html">sqlite3_reset()</a>. |
| 1718 |
This caused problems on some poorly written smartphone applications which |
| 1719 |
did not correctly handle the <a href="rescode.html#locked">SQLITE_LOCKED</a> and <a href="rescode.html#busy">SQLITE_BUSY</a> error |
| 1720 |
returns. Rather than fix the many defective smartphone applications, |
| 1721 |
the behavior of SQLite was changed in 3.6.23.2 to automatically reset |
| 1722 |
the prepared statement. But that change caused issues in other |
| 1723 |
improperly implemented applications that were actually looking |
| 1724 |
for an <a href="rescode.html#misuse">SQLITE_MISUSE</a> return to terminate their query loops. (When |
| 1725 |
an application gets an SQLITE_MISUSE error code from SQLite, that means the |
| 1726 |
application is misusing the SQLite interface and is thus incorrectly |
| 1727 |
implemented.) The SQLITE_OMIT_AUTORESET interface was added to SQLite |
| 1728 |
<a href="releaselog/3_7_5.html">version 3.7.5</a> (2011-02-01) in an effort to get all of the (broken) |
| 1729 |
applications to work again without having to actually fix the applications. |
| 1730 |
</p></blockquote><a name="omit_autovacuum"></a> |
| 1731 |
<p><b>SQLITE_OMIT_AUTOVACUUM</b></p><blockquote><p> |
| 1732 |
If this option is defined, the library cannot create or write to |
| 1733 |
databases that support <a href="pragma.html#pragma_auto_vacuum">auto_vacuum</a>. |
| 1734 |
Executing a <a href="pragma.html#pragma_auto_vacuum">PRAGMA auto_vacuum</a> statement is not an error |
| 1735 |
(since unknown PRAGMAs are silently ignored), but does not return a value |
| 1736 |
or modify the auto-vacuum flag in the database file. If a database that |
| 1737 |
supports auto-vacuum is opened by a library compiled with this option, it |
| 1738 |
is automatically opened in read-only mode. |
| 1739 |
</p></blockquote><a name="omit_between_optimization"></a> |
| 1740 |
<p><b>SQLITE_OMIT_BETWEEN_OPTIMIZATION</b></p><blockquote><p> |
| 1741 |
This option disables the use of indices with WHERE clause terms |
| 1742 |
that employ the BETWEEN operator. |
| 1743 |
</p></blockquote><a name="omit_blob_literal"></a> |
| 1744 |
<p><b>SQLITE_OMIT_BLOB_LITERAL</b></p><blockquote><p> |
| 1745 |
When this option is defined, it is not possible to specify a blob in |
| 1746 |
an SQL statement using the X'ABCD' syntax. |
| 1747 |
</p></blockquote><a name="omit_btreecount"></a> |
| 1748 |
<p><b>SQLITE_OMIT_BTREECOUNT</b></p><blockquote><p> |
| 1749 |
This option is no longer used for anything. It is a no-op. |
| 1750 |
</p></blockquote><a name="omit_builtin_test"></a> |
| 1751 |
<p><b>SQLITE_OMIT_BUILTIN_TEST</b></p><blockquote><p> |
| 1752 |
This compile-time option has been renamed to <a href="compile.html#untestable">SQLITE_UNTESTABLE</a>. |
| 1753 |
</p></blockquote><a name="omit_case_sensitive_like_pragma"></a> |
| 1754 |
<p><b>SQLITE_OMIT_CASE_SENSITIVE_LIKE_PRAGMA</b></p><blockquote><p> |
| 1755 |
This compile-time option disables the <a href="pragma.html#pragma_case_sensitive_like">PRAGMA case_sensitive_like</a> |
| 1756 |
command. |
| 1757 |
</p></blockquote><a name="omit_cast"></a> |
| 1758 |
<p><b>SQLITE_OMIT_CAST</b></p><blockquote><p> |
| 1759 |
This option causes SQLite to omit support for the CAST operator. |
| 1760 |
</p></blockquote><a name="omit_check"></a> |
| 1761 |
<p><b>SQLITE_OMIT_CHECK</b></p><blockquote><p> |
| 1762 |
This option causes SQLite to omit support for CHECK constraints. |
| 1763 |
The parser will still accept CHECK constraints in SQL statements, |
| 1764 |
they will just not be enforced. |
| 1765 |
</p></blockquote><a name="omit_compileoption_diags"></a> |
| 1766 |
<p><b>SQLITE_OMIT_COMPILEOPTION_DIAGS</b></p><blockquote><p> |
| 1767 |
This option is used to omit the compile-time option diagnostics available |
| 1768 |
in SQLite, including the <a href="c3ref/compileoption_get.html">sqlite3_compileoption_used()</a> and |
| 1769 |
<a href="c3ref/compileoption_get.html">sqlite3_compileoption_get()</a> C/C++ functions, the |
| 1770 |
<a href="lang_corefunc.html#sqlite_compileoption_used">sqlite_compileoption_used()</a> and <a href="lang_corefunc.html#sqlite_compileoption_get">sqlite_compileoption_get()</a> SQL functions, |
| 1771 |
and the <a href="pragma.html#pragma_compile_options">compile_options pragma</a>. |
| 1772 |
</p></blockquote><a name="omit_complete"></a> |
| 1773 |
<p><b>SQLITE_OMIT_COMPLETE</b></p><blockquote><p> |
| 1774 |
This option causes the <a href="c3ref/complete.html">sqlite3_complete()</a> and <a href="c3ref/complete.html">sqlite3_complete16()</a> |
| 1775 |
interfaces to be omitted. |
| 1776 |
</p></blockquote><a name="omit_compound_select"></a> |
| 1777 |
<p><b>SQLITE_OMIT_COMPOUND_SELECT</b></p><blockquote><p> |
| 1778 |
This option is used to omit the compound <a href="lang_select.html">SELECT</a> functionality. |
| 1779 |
<a href="lang_select.html">SELECT</a> statements that use the |
| 1780 |
UNION, UNION ALL, INTERSECT or EXCEPT compound SELECT operators will |
| 1781 |
cause a parse error.</p> |
| 1782 |
|
| 1783 |
<p> An <a href="lang_insert.html">INSERT</a> statement with multiple values in the VALUES clause is |
| 1784 |
implemented internally as a compound SELECT. Hence, this option also |
| 1785 |
disables the ability to insert more than a single row using an |
| 1786 |
INSERT INTO ... VALUES ... statement. |
| 1787 |
</p></blockquote><a name="omit_cte"></a> |
| 1788 |
<p><b>SQLITE_OMIT_CTE</b></p><blockquote><p> |
| 1789 |
This option causes support for <a href="lang_with.html">common table expressions</a> to be omitted. |
| 1790 |
</p></blockquote><a name="omit_datetime_funcs"></a> |
| 1791 |
<p><b>SQLITE_OMIT_DATETIME_FUNCS</b></p><blockquote><p> |
| 1792 |
If this option is defined, SQLite's built-in date and time manipulation |
| 1793 |
functions are omitted. Specifically, the SQL functions julianday(), date(), |
| 1794 |
time(), datetime() and strftime() are not available. The default column |
| 1795 |
values CURRENT_TIME, CURRENT_DATE and CURRENT_TIMESTAMP are still available. |
| 1796 |
</p></blockquote><a name="omit_decltype"></a> |
| 1797 |
<p><b>SQLITE_OMIT_DECLTYPE</b></p><blockquote><p> |
| 1798 |
This option causes SQLite to omit support for the |
| 1799 |
<a href="c3ref/column_decltype.html">sqlite3_column_decltype()</a> and <a href="c3ref/column_decltype.html">sqlite3_column_decltype16()</a> |
| 1800 |
interfaces. |
| 1801 |
</p></blockquote><a name="omit_deprecated"></a> |
| 1802 |
<p><b>SQLITE_OMIT_DEPRECATED</b></p><blockquote><p> |
| 1803 |
This option causes SQLite to omit support for interfaces |
| 1804 |
marked as deprecated. This includes |
| 1805 |
<a href="c3ref/aggregate_count.html">sqlite3_aggregate_count()</a>, |
| 1806 |
<a href="c3ref/aggregate_count.html">sqlite3_expired()</a>, |
| 1807 |
<a href="c3ref/aggregate_count.html">sqlite3_transfer_bindings()</a>, |
| 1808 |
<a href="c3ref/aggregate_count.html">sqlite3_global_recover()</a>, |
| 1809 |
<a href="c3ref/aggregate_count.html">sqlite3_thread_cleanup()</a> and |
| 1810 |
<a href="c3ref/aggregate_count.html">sqlite3_memory_alarm()</a> interfaces and |
| 1811 |
<a href="pragma.html#syntax">PRAGMA</a> statements <a href="pragma.html#pragma_count_changes">PRAGMA count_changes</a>, |
| 1812 |
<a href="pragma.html#pragma_data_store_directory">PRAGMA data_store_directory</a>, |
| 1813 |
<a href="pragma.html#pragma_default_cache_size">PRAGMA default_cache_size</a>, |
| 1814 |
<a href="pragma.html#pragma_empty_result_callbacks">PRAGMA empty_result_callbacks</a>, |
| 1815 |
<a href="pragma.html#pragma_full_column_names">PRAGMA full_column_names</a>, |
| 1816 |
<a href="pragma.html#pragma_short_column_names">PRAGMA short_column_names</a>, and |
| 1817 |
<a href="pragma.html#pragma_temp_store_directory">PRAGMA temp_store_directory</a>. |
| 1818 |
</p></blockquote><a name="omit_deserialize"></a> |
| 1819 |
<p><b>SQLITE_OMIT_DESERIALIZE</b></p><blockquote><p> |
| 1820 |
This option causes the |
| 1821 |
<a href="c3ref/serialize.html">sqlite3_serialize()</a> and <a href="c3ref/deserialize.html">sqlite3_deserialize()</a> |
| 1822 |
interfaces to be omitted from the build. |
| 1823 |
</p></blockquote><a name="omit_diskio"></a> |
| 1824 |
<p><b>SQLITE_OMIT_DISKIO</b></p><blockquote><p> |
| 1825 |
This option omits all support for writing to the disk and forces |
| 1826 |
databases to exist in memory only. This option has not been |
| 1827 |
maintained and probably does not work with newer versions of SQLite. |
| 1828 |
</p></blockquote><a name="omit_explain"></a> |
| 1829 |
<p><b>SQLITE_OMIT_EXPLAIN</b></p><blockquote><p> |
| 1830 |
Defining this option causes the <a href="lang_explain.html">EXPLAIN</a> command to be omitted from the |
| 1831 |
library. Attempting to execute an <a href="lang_explain.html">EXPLAIN</a> statement will cause a parse |
| 1832 |
error. |
| 1833 |
</p></blockquote><a name="omit_flag_pragmas"></a> |
| 1834 |
<p><b>SQLITE_OMIT_FLAG_PRAGMAS</b></p><blockquote><p> |
| 1835 |
This option omits support for a subset of <a href="pragma.html#syntax">PRAGMA</a> commands that |
| 1836 |
query and set boolean properties. |
| 1837 |
</p></blockquote><a name="omit_floating_point"></a> |
| 1838 |
<p><b>SQLITE_OMIT_FLOATING_POINT</b></p><blockquote><p> |
| 1839 |
This option is used to omit floating-point number support from the SQLite |
| 1840 |
library. When specified, specifying a floating point number as a literal |
| 1841 |
(i.e. "1.01") results in a parse error.</p> |
| 1842 |
|
| 1843 |
<p> <p>In the future, this option may also disable other floating point |
| 1844 |
functionality, for example the <a href="c3ref/result_blob.html">sqlite3_result_double()</a>, |
| 1845 |
<a href="c3ref/bind_blob.html">sqlite3_bind_double()</a>, <a href="c3ref/value_blob.html">sqlite3_value_double()</a> and |
| 1846 |
<a href="c3ref/column_blob.html">sqlite3_column_double()</a> API functions. |
| 1847 |
</p> |
| 1848 |
</p></blockquote><a name="omit_foreign_key"></a> |
| 1849 |
<p><b>SQLITE_OMIT_FOREIGN_KEY</b></p><blockquote><p> |
| 1850 |
If this option is defined, then <a href="foreignkeys.html">foreign key constraint</a> syntax is |
| 1851 |
not recognized. |
| 1852 |
</p></blockquote><a name="omit_generated_columns"></a> |
| 1853 |
<p><b>SQLITE_OMIT_GENERATED_COLUMNS</b></p><blockquote><p> |
| 1854 |
If this option is defined, then <a href="gencol.html">generated column</a> syntax is |
| 1855 |
not recognized. |
| 1856 |
</p></blockquote><a name="omit_get_table"></a> |
| 1857 |
<p><b>SQLITE_OMIT_GET_TABLE</b></p><blockquote><p> |
| 1858 |
This option causes support for <a href="c3ref/free_table.html">sqlite3_get_table()</a> and |
| 1859 |
<a href="c3ref/free_table.html">sqlite3_free_table()</a> to be omitted. |
| 1860 |
</p></blockquote><a name="omit_hex_integer"></a> |
| 1861 |
<p><b>SQLITE_OMIT_HEX_INTEGER</b></p><blockquote><p> |
| 1862 |
This option omits support for <a href="lang_expr.html#hexint">hexadecimal integer literals</a>. |
| 1863 |
</p></blockquote><a name="omit_incrblob"></a> |
| 1864 |
<p><b>SQLITE_OMIT_INCRBLOB</b></p><blockquote><p> |
| 1865 |
This option causes support for <a href="c3ref/blob.html">incremental BLOB I/O</a> |
| 1866 |
to be omitted. |
| 1867 |
</p></blockquote><a name="omit_integrity_check"></a> |
| 1868 |
<p><b>SQLITE_OMIT_INTEGRITY_CHECK</b></p><blockquote><p> |
| 1869 |
This option omits support for the <a href="pragma.html#pragma_integrity_check">integrity_check pragma</a>. |
| 1870 |
</p></blockquote><a name="omit_introspection_pragmas"></a> |
| 1871 |
<p><b>SQLITE_OMIT_INTROSPECTION_PRAGMAS</b></p><blockquote><p> |
| 1872 |
This option omits support for |
| 1873 |
<a href="pragma.html#pragma_function_list">PRAGMA function_list</a>, <a href="pragma.html#pragma_module_list">PRAGMA module_list</a>, and |
| 1874 |
<a href="pragma.html#pragma_pragma_list">PRAGMA pragma_list</a>. |
| 1875 |
</p></blockquote><a name="omit_json"></a> |
| 1876 |
<p><b>SQLITE_OMIT_JSON</b></p><blockquote><p> |
| 1877 |
This option omits the <a href="json1.html">JSON SQL functions</a> from the build. |
| 1878 |
</p></blockquote><a name="omit_like_optimization"></a> |
| 1879 |
<p><b>SQLITE_OMIT_LIKE_OPTIMIZATION</b></p><blockquote><p> |
| 1880 |
This option disables the ability of SQLite to use indices to help |
| 1881 |
resolve <a href="lang_expr.html#like">LIKE</a> and <a href="lang_expr.html#glob">GLOB</a> operators in a WHERE clause. |
| 1882 |
</p></blockquote><a name="omit_load_extension"></a> |
| 1883 |
<p><b>SQLITE_OMIT_LOAD_EXTENSION</b></p><blockquote><p> |
| 1884 |
This option omits the entire extension loading mechanism from |
| 1885 |
SQLite, including <a href="c3ref/enable_load_extension.html">sqlite3_enable_load_extension()</a> and |
| 1886 |
<a href="c3ref/load_extension.html">sqlite3_load_extension()</a> interfaces. |
| 1887 |
</p></blockquote><a name="omit_localtime"></a> |
| 1888 |
<p><b>SQLITE_OMIT_LOCALTIME</b></p><blockquote><p> |
| 1889 |
This option omits the "localtime" modifier from the date and time |
| 1890 |
functions. This option is sometimes useful when trying to compile |
| 1891 |
the date and time functions on a platform that does not support the |
| 1892 |
concept of local time. |
| 1893 |
</p></blockquote><a name="omit_lookaside"></a> |
| 1894 |
<p><b>SQLITE_OMIT_LOOKASIDE</b></p><blockquote><p> |
| 1895 |
This option omits the <a href="malloc.html#lookaside">lookaside memory allocator</a>. |
| 1896 |
</p></blockquote><a name="omit_memorydb"></a> |
| 1897 |
<p><b>SQLITE_OMIT_MEMORYDB</b></p><blockquote><p> |
| 1898 |
When this is defined, the library does not respect the special database |
| 1899 |
name ":memory:" (normally used to create an <a href="inmemorydb.html">in-memory database</a>). If |
| 1900 |
":memory:" is passed to <a href="c3ref/open.html">sqlite3_open()</a>, <a href="c3ref/open.html">sqlite3_open16()</a>, or |
| 1901 |
<a href="c3ref/open.html">sqlite3_open_v2()</a>, a file with this name will be |
| 1902 |
opened or created. |
| 1903 |
</p></blockquote><a name="omit_or_optimization"></a> |
| 1904 |
<p><b>SQLITE_OMIT_OR_OPTIMIZATION</b></p><blockquote><p> |
| 1905 |
This option disables the ability of SQLite to use an index together |
| 1906 |
with terms of a WHERE clause connected by the OR operator. |
| 1907 |
</p></blockquote><a name="omit_pager_pragmas"></a> |
| 1908 |
<p><b>SQLITE_OMIT_PAGER_PRAGMAS</b></p><blockquote><p> |
| 1909 |
Defining this option omits pragmas related to the pager subsystem from |
| 1910 |
the build. |
| 1911 |
</p></blockquote><a name="omit_pragma"></a> |
| 1912 |
<p><b>SQLITE_OMIT_PRAGMA</b></p><blockquote><p> |
| 1913 |
This option is used to omit the <a href="pragma.html#syntax">PRAGMA</a> command |
| 1914 |
from the library. Note that it is useful to define the macros that omit |
| 1915 |
specific pragmas in addition to this, as they may also remove supporting code |
| 1916 |
in other sub-systems. This macro removes the <a href="pragma.html#syntax">PRAGMA</a> command only. |
| 1917 |
</p></blockquote><a name="omit_progress_callback"></a> |
| 1918 |
<p><b>SQLITE_OMIT_PROGRESS_CALLBACK</b></p><blockquote><p> |
| 1919 |
When defined, this option omits the [sqlite3_progress_handler() API |
| 1920 |
and related logic. |
| 1921 |
</p></blockquote><a name="omit_quickbalance"></a> |
| 1922 |
<p><b>SQLITE_OMIT_QUICKBALANCE</b></p><blockquote><p> |
| 1923 |
This option omits an alternative, faster B-Tree balancing routine. |
| 1924 |
Using this option makes SQLite slightly smaller at the expense of |
| 1925 |
making it run slightly slower. |
| 1926 |
</p></blockquote><a name="omit_reindex"></a> |
| 1927 |
<p><b>SQLITE_OMIT_REINDEX</b></p><blockquote><p> |
| 1928 |
When this option is defined, the <a href="lang_reindex.html">REINDEX</a> |
| 1929 |
command is not included in the library. |
| 1930 |
Executing a <a href="lang_reindex.html">REINDEX</a> statement causes |
| 1931 |
a parse error. |
| 1932 |
</p></blockquote><a name="omit_schema_pragmas"></a> |
| 1933 |
<p><b>SQLITE_OMIT_SCHEMA_PRAGMAS</b></p><blockquote><p> |
| 1934 |
Defining this option omits pragmas for querying the database schema from |
| 1935 |
the build. |
| 1936 |
</p></blockquote><a name="omit_schema_version_pragmas"></a> |
| 1937 |
<p><b>SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS</b></p><blockquote><p> |
| 1938 |
Defining this option omits pragmas for querying and modifying the |
| 1939 |
database schema version and user version from the build. Specifically, the |
| 1940 |
<a href="pragma.html#pragma_schema_version">schema_version</a> and <a href="pragma.html#pragma_user_version">user_version</a> PRAGMAs are omitted. |
| 1941 |
</p></blockquote><a name="omit_shared_cache"></a> |
| 1942 |
<p><b>SQLITE_OMIT_SHARED_CACHE</b></p><blockquote><p> |
| 1943 |
This option builds SQLite without support for <a href="sharedcache.html">shared cache mode</a>. |
| 1944 |
The <a href="c3ref/enable_shared_cache.html">sqlite3_enable_shared_cache()</a> is omitted along with a fair |
| 1945 |
amount of logic within the B-Tree subsystem associated with shared |
| 1946 |
cache management.</p> |
| 1947 |
|
| 1948 |
<p> This compile-time option is recommended for most applications as it |
| 1949 |
results in improved performance and reduced library footprint. |
| 1950 |
</p></blockquote><a name="omit_seh"></a> |
| 1951 |
<p><b>SQLITE_OMIT_SEH</b></p><blockquote><p> |
| 1952 |
If defined, Structured Exception Handling (SEH) is disabled on |
| 1953 |
Windows builds. SEH is a Windows-specific technique for catching |
| 1954 |
exceptions raised while accessing a memory-mapped file. SEH is used |
| 1955 |
to intercept errors that might occur while accessing the |
| 1956 |
memory-mapped <a href="walformat.html#shm">shm file</a> that are part of <a href="wal.html">WAL mode</a> processing. If |
| 1957 |
the operating system raised errors while SQLite is trying to access |
| 1958 |
the shm file, this option causes those errors to be caught and dealt |
| 1959 |
with by SQLite, rather than aborting the whole process. |
| 1960 |
<p> |
| 1961 |
This has no effect except when compiling on Windows using MSVC. |
| 1962 |
</p></blockquote><a name="omit_subquery"></a> |
| 1963 |
<p><b>SQLITE_OMIT_SUBQUERY</b></p><blockquote><p> |
| 1964 |
If defined, support for sub-selects and the IN() operator are omitted. |
| 1965 |
</p></blockquote><a name="omit_tcl_variable"></a> |
| 1966 |
<p><b>SQLITE_OMIT_TCL_VARIABLE</b></p><blockquote><p> |
| 1967 |
If this macro is defined, then the special "$<variable-name>" syntax |
| 1968 |
used to automatically bind SQL variables to TCL variables is omitted. |
| 1969 |
</p></blockquote><a name="omit_tempdb"></a> |
| 1970 |
<p><b>SQLITE_OMIT_TEMPDB</b></p><blockquote><p> |
| 1971 |
This option omits support for TEMP or TEMPORARY tables. |
| 1972 |
</p></blockquote><a name="omit_trace"></a> |
| 1973 |
<p><b>SQLITE_OMIT_TRACE</b></p><blockquote><p> |
| 1974 |
This option omits support for the <a href="c3ref/profile.html">sqlite3_profile()</a> and |
| 1975 |
<a href="c3ref/profile.html">sqlite3_trace()</a> interfaces and their associated logic. |
| 1976 |
</p></blockquote><a name="omit_trigger"></a> |
| 1977 |
<p><b>SQLITE_OMIT_TRIGGER</b></p><blockquote><p> |
| 1978 |
Defining this option omits support for TRIGGER objects. Neither the |
| 1979 |
<a href="lang_createtrigger.html">CREATE TRIGGER</a> or <a href="lang_droptrigger.html">DROP TRIGGER</a> |
| 1980 |
commands are available in this case, and attempting to execute |
| 1981 |
either will result in a parse error. |
| 1982 |
This option also disables enforcement of <a href="foreignkeys.html">foreign key constraints</a>, |
| 1983 |
since the code that implements triggers and which is omitted by this |
| 1984 |
option is also used to implement <a href="foreignkeys.html#fk_actions">foreign key actions</a>. |
| 1985 |
</p></blockquote><a name="omit_truncate_optimization"></a> |
| 1986 |
<p><b>SQLITE_OMIT_TRUNCATE_OPTIMIZATION</b></p><blockquote><p> |
| 1987 |
This option omits the <a href="lang_delete.html#truncateopt">truncate optimization</a>. |
| 1988 |
</p></blockquote><a name="omit_utf16"></a> |
| 1989 |
<p><b>SQLITE_OMIT_UTF16</b></p><blockquote><p> |
| 1990 |
This macro is used to omit support for UTF16 text encoding. When this is |
| 1991 |
defined all API functions that return or accept UTF16 encoded text are |
| 1992 |
unavailable. These functions can be identified by the fact that they end |
| 1993 |
with '16', for example <a href="c3ref/prepare.html">sqlite3_prepare16()</a>, <a href="c3ref/column_blob.html">sqlite3_column_text16()</a> and |
| 1994 |
<a href="c3ref/bind_blob.html">sqlite3_bind_text16()</a>. |
| 1995 |
</p></blockquote><a name="omit_vacuum"></a> |
| 1996 |
<p><b>SQLITE_OMIT_VACUUM</b></p><blockquote><p> |
| 1997 |
When this option is defined, the <a href="lang_vacuum.html">VACUUM</a> |
| 1998 |
command is not included in the library. |
| 1999 |
Executing a <a href="lang_vacuum.html">VACUUM</a> statement causes |
| 2000 |
a parse error. |
| 2001 |
</p></blockquote><a name="omit_view"></a> |
| 2002 |
<p><b>SQLITE_OMIT_VIEW</b></p><blockquote><p> |
| 2003 |
Defining this option omits support for VIEW objects. Neither the |
| 2004 |
<a href="lang_createview.html">CREATE VIEW</a> nor the <a href="lang_dropview.html">DROP VIEW</a> |
| 2005 |
commands are available in this case, and |
| 2006 |
attempting to execute either will result in a parse error.</p> |
| 2007 |
|
| 2008 |
<p> WARNING: If this macro is defined, it will not be possible to open a database |
| 2009 |
for which the schema contains VIEW objects. |
| 2010 |
</p></blockquote><a name="omit_virtualtable"></a> |
| 2011 |
<p><b>SQLITE_OMIT_VIRTUALTABLE</b></p><blockquote><p> |
| 2012 |
This option omits support for the <a href="c3ref/vtab.html">Virtual Table</a> |
| 2013 |
mechanism in SQLite. |
| 2014 |
</p></blockquote><a name="omit_wal"></a> |
| 2015 |
<p><b>SQLITE_OMIT_WAL</b></p><blockquote><p> |
| 2016 |
This option omits the "<a href="wal.html">write-ahead log</a>" (a.k.a. "<a href="wal.html">WAL</a>") capability. |
| 2017 |
</p></blockquote><a name="omit_windowfunc"></a> |
| 2018 |
<p><b>SQLITE_OMIT_WINDOWFUNC</b></p><blockquote><p> |
| 2019 |
This option omits <a href="windowfunctions.html">window functions</a> from the build. |
| 2020 |
</p></blockquote><a name="omit_wsd"></a> |
| 2021 |
<p><b>SQLITE_OMIT_WSD</b></p><blockquote><p> |
| 2022 |
This option builds a version of the SQLite library that contains no |
| 2023 |
Writable Static Data (WSD). WSD is global variables and/or static |
| 2024 |
variables. Some platforms do not support WSD, and this option is necessary |
| 2025 |
in order for SQLite to work those platforms.</p> |
| 2026 |
|
| 2027 |
<p> Unlike other OMIT options which make the SQLite library smaller, |
| 2028 |
this option actually increases the size of SQLite and makes it run |
| 2029 |
a little slower. Only use this option if SQLite is being built for an |
| 2030 |
embedded target that does not support WSD. |
| 2031 |
</p></blockquote><a name="omit_xfer_opt"></a> |
| 2032 |
<p><b>SQLITE_OMIT_XFER_OPT</b></p><blockquote><p> |
| 2033 |
This option omits support for optimizations that help statements |
| 2034 |
of the form "INSERT INTO ... SELECT ..." run faster. |
| 2035 |
</p></blockquote><a name="untestable"></a> |
| 2036 |
<p><b>SQLITE_UNTESTABLE</b></p><blockquote><p> |
| 2037 |
A standard SQLite build includes a small amount of logic associated |
| 2038 |
with <a href="c3ref/test_control.html">sqlite3_test_control()</a> to exercise |
| 2039 |
parts of the SQLite core that are otherwise difficult to validate. |
| 2040 |
This compile-time option omits that extra testing logic. This |
| 2041 |
compile-time option was called "SQLITE_OMIT_BUILTIN_TEST" prior |
| 2042 |
to SQLite version 3.16.0 (2017-01-02). The name was changed |
| 2043 |
to better describe the implications of using it. |
| 2044 |
<p> |
| 2045 |
Setting this compile-time option prevents SQLite from being fully |
| 2046 |
testable. Branch test coverage drops from 100% down to about 95%. |
| 2047 |
<p> |
| 2048 |
SQLite developers follow the NASA principle of |
| 2049 |
"fly what you test and test what you fly". This principle is violated |
| 2050 |
if this option is enabled for delivery but disabled for testing. |
| 2051 |
But if this option is enabled during testing, not all branches are |
| 2052 |
reachable. Therefore, the use of this compile-time option is discouraged. |
| 2053 |
</p></blockquote><a name="zero_malloc"></a> |
| 2054 |
<p><b>SQLITE_ZERO_MALLOC</b></p><blockquote><p> |
| 2055 |
This option omits both the <a href="malloc.html#defaultalloc">default memory allocator</a> and the |
| 2056 |
<a href="malloc.html#memdebug">debugging memory allocator</a> from the build and substitutes a stub |
| 2057 |
memory allocator that always fails. SQLite will not run with this |
| 2058 |
stub memory allocator since it will be unable to allocate memory. But |
| 2059 |
this stub can be replaced at start-time using |
| 2060 |
<a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_covering_index_scan.html#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a>,...) or |
| 2061 |
<a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_covering_index_scan.html#sqliteconfigheap">SQLITE_CONFIG_HEAP</a>,...). |
| 2062 |
So the net effect of this compile-time option is that it allows SQLite |
| 2063 |
to be compiled and linked against a system library that does not support |
| 2064 |
malloc(), free(), and/or realloc(). |
| 2065 |
</p></blockquote> |
| 2066 |
<a name="debugoptions"></a> |
| 2067 |
</p><h1 id="_analysis_and_debugging_options"><span>10. </span> Analysis and Debugging Options</h1> |
| 2068 |
<a name="debug"></a> |
| 2069 |
<p><b>SQLITE_DEBUG</b></p><blockquote><p> |
| 2070 |
The SQLite source code contains literally thousands of assert() statements |
| 2071 |
used to verify internal assumptions and subroutine preconditions and |
| 2072 |
postconditions. These assert() statements are normally turned off |
| 2073 |
(they generate no code) since turning them on makes SQLite run approximately |
| 2074 |
three times slower. But for testing and analysis, it is useful to turn |
| 2075 |
the assert() statements on. The SQLITE_DEBUG compile-time option does this. |
| 2076 |
<p>SQLITE_DEBUG also enables some other debugging features, such as |
| 2077 |
special <a href="pragma.html#syntax">PRAGMA</a> statements that turn on tracing and listing features |
| 2078 |
used for troubleshooting and analysis of the <a href="opcode.html">VDBE</a> and code generator. |
| 2079 |
</p></blockquote><a name="memdebug"></a> |
| 2080 |
<p><b>SQLITE_MEMDEBUG</b></p><blockquote><p> |
| 2081 |
The SQLITE_MEMDEBUG option causes an instrumented |
| 2082 |
<a href="malloc.html#memdebug">debugging memory allocator</a> |
| 2083 |
to be used as the default memory allocator within SQLite. The |
| 2084 |
instrumented memory allocator checks for misuse of dynamically allocated |
| 2085 |
memory. Examples of misuse include using memory after it is freed, |
| 2086 |
writing off the ends of a memory allocation, freeing memory not previously |
| 2087 |
obtained from the memory allocator, or failing to initialize newly |
| 2088 |
allocated memory. |
| 2089 |
</p></blockquote> |
| 2090 |
<a name="win32options"></a> |
| 2091 |
<h1 id="_windows_specific_options"><span>11. </span> Windows-Specific Options</h1> |
| 2092 |
<a name="win32_heap_create"></a> |
| 2093 |
<p><b>SQLITE_WIN32_HEAP_CREATE</b></p><blockquote><p> |
| 2094 |
This option forces the Win32 native memory allocator, when enabled, to |
| 2095 |
create a private heap to hold all memory allocations. |
| 2096 |
</p></blockquote><a name="win32_malloc_validate"></a> |
| 2097 |
<p><b>SQLITE_WIN32_MALLOC_VALIDATE</b></p><blockquote><p> |
| 2098 |
This option forces the Win32 native memory allocator, when enabled, to |
| 2099 |
make strategic calls into the HeapValidate() function if assert() is also |
| 2100 |
enabled. |
| 2101 |
</p></blockquote> |
| 2102 |
<a name="linkage"></a> |
| 2103 |
<h1 id="compiler_linkage_and_calling_convention_control"><span>12. </span>Compiler Linkage and Calling Convention Control</h1> |
| 2104 |
|
| 2105 |
<p>The following macros specify interface details |
| 2106 |
for certain kinds of SQLite builds. The Makefiles will normally |
| 2107 |
handle setting these macros automatically. Application developers should |
| 2108 |
not need to worry with these macros. The following documentation about these |
| 2109 |
macros is included for completeness.</p> |
| 2110 |
|
| 2111 |
<a name="api"></a> |
| 2112 |
<p><b>SQLITE_API</b></p><blockquote><p> |
| 2113 |
This macro identifies an externally visible interface for SQLite. |
| 2114 |
This macro is sometimes set to "extern". But the definition is |
| 2115 |
compiler-specific. |
| 2116 |
</p></blockquote><a name="apicall"></a> |
| 2117 |
<p><b>SQLITE_APICALL</b></p><blockquote><p> |
| 2118 |
This macro identifies the calling convention used by public interface |
| 2119 |
routines in SQLite which accept a fixed number of arguments. |
| 2120 |
This macro is normally defined to be nothing, |
| 2121 |
though on Windows builds it can sometimes be set to "__cdecl" or "__stdcall". |
| 2122 |
The "__cdecl" setting is the default, but "__stdcall" is used when SQLite |
| 2123 |
is intended to be compiled as a Windows system library. |
| 2124 |
<p> |
| 2125 |
A single function declaration should contain no more than one of |
| 2126 |
the following: <a href="compile.html#apicall">SQLITE_APICALL</a>, <a href="compile.html#cdecl">SQLITE_CDECL</a>, or <a href="compile.html#sysapi">SQLITE_SYSAPI</a>. |
| 2127 |
</p></blockquote><a name="callback"></a> |
| 2128 |
<p><b>SQLITE_CALLBACK</b></p><blockquote><p> |
| 2129 |
This macro specifies the calling convention used with callback pointers |
| 2130 |
in SQLite. This macro is normally defined to be nothing, though on Windows |
| 2131 |
builds it can sometimes be set to "__cdecl" or "__stdcall". The |
| 2132 |
"__cdecl" setting is the default, but "__stdcall" is used when SQLite |
| 2133 |
is intended to be compiled as a Windows system library. |
| 2134 |
</p></blockquote><a name="cdecl"></a> |
| 2135 |
<p><b>SQLITE_CDECL</b></p><blockquote><p> |
| 2136 |
This macro specifies the calling convention used by varargs interface |
| 2137 |
routines in SQLite. This macro is normally defined to be nothing, |
| 2138 |
though on Windows builds it can sometimes be set to "__cdecl". This |
| 2139 |
macro is used on varargs routines and so cannot be set to "__stdcall" |
| 2140 |
since the __stdcall calling convention does not support varargs functions. |
| 2141 |
<p> |
| 2142 |
A single function declaration should contain no more than one of |
| 2143 |
the following: <a href="compile.html#apicall">SQLITE_APICALL</a>, <a href="compile.html#cdecl">SQLITE_CDECL</a>, or <a href="compile.html#sysapi">SQLITE_SYSAPI</a>. |
| 2144 |
</p></blockquote><a name="extern"></a> |
| 2145 |
<p><b>SQLITE_EXTERN</b></p><blockquote><p> |
| 2146 |
This macro specifies linkage for public interface variables in SQLite. |
| 2147 |
It should normally be allowed to default to "extern". |
| 2148 |
</p></blockquote><a name="stdcall"></a> |
| 2149 |
<p><b>SQLITE_STDCALL</b></p><blockquote><p> |
| 2150 |
This macro is no longer used and is now deprecated. |
| 2151 |
</p></blockquote><a name="sysapi"></a> |
| 2152 |
<p><b>SQLITE_SYSAPI</b></p><blockquote><p> |
| 2153 |
This macro identifies the calling convention used by operating system |
| 2154 |
interfaces for the target platform for an SQLite build. |
| 2155 |
This macro is normally defined to be nothing, |
| 2156 |
though on Windows builds it can sometimes be set to "__stdcall". |
| 2157 |
<p> |
| 2158 |
A single function declaration should contain no more than one of |
| 2159 |
the following: <a href="compile.html#apicall">SQLITE_APICALL</a>, <a href="compile.html#cdecl">SQLITE_CDECL</a>, or <a href="compile.html#sysapi">SQLITE_SYSAPI</a>. |
| 2160 |
</p></blockquote><a name="tclapi"></a> |
| 2161 |
<p><b>SQLITE_TCLAPI</b></p><blockquote><p> |
| 2162 |
This macro specifies the calling convention used by the |
| 2163 |
<a href="http://www.tcl.tk">TCL</a> library interface routines. |
| 2164 |
This macro is not used by the SQLite core, but only by the <a href="tclsqlite.html">TCL Interface</a> |
| 2165 |
and <a href="testing.html#tcl">TCL test suite</a>. |
| 2166 |
This macro is normally defined to be nothing, |
| 2167 |
though on Windows builds it can sometimes be set to "__cdecl". This |
| 2168 |
macro is used on TCL library interface routines which are always compiled |
| 2169 |
as __cdecl, even on platforms that prefer to use __stdcall, so this |
| 2170 |
macro should not be set to __stdcall unless the platform has a custom |
| 2171 |
TCL library build that supports __stdcall. |
| 2172 |
<p> |
| 2173 |
This macro may not be used in combination with any of <a href="compile.html#apicall">SQLITE_APICALL</a>, |
| 2174 |
<a href="compile.html#callback">SQLITE_CALLBACK</a>, <a href="compile.html#cdecl">SQLITE_CDECL</a> or <a href="compile.html#sysapi">SQLITE_SYSAPI</a>. |
| 2175 |
</p></blockquote> |
| 2176 |
<p align="center"><small><i>This page was last updated on 2026-01-26 12:08:31Z </small></i></p> |
| 2177 |
|