diff options
Diffstat (limited to 'www/compile.html')
| -rw-r--r-- | www/compile.html | 2133 |
1 files changed, 2133 insertions, 0 deletions
diff --git a/www/compile.html b/www/compile.html new file mode 100644 index 0000000..5e300e2 --- /dev/null +++ b/www/compile.html @@ -0,0 +1,2133 @@ +<!DOCTYPE html> +<html><head> +<meta name="viewport" content="width=device-width, initial-scale=1.0"> +<meta http-equiv="content-type" content="text/html; charset=UTF-8"> +<link href="sqlite.css" rel="stylesheet"> +<title>Compile-time Options</title> +<!-- path= --> +</head> +<body> +<div class=nosearch> +<a href="index.html"> +<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite" border="0"> +</a> +<div><!-- IE hack to prevent disappearing logo --></div> +<div class="tagline desktoponly"> +Small. Fast. Reliable.<br>Choose any three. +</div> +<div class="menu mainmenu"> +<ul> +<li><a href="index.html">Home</a> +<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a> +<li class='wideonly'><a href='about.html'>About</a> +<li class='desktoponly'><a href="docs.html">Documentation</a> +<li class='desktoponly'><a href="download.html">Download</a> +<li class='wideonly'><a href='copyright.html'>License</a> +<li class='desktoponly'><a href="support.html">Support</a> +<li class='desktoponly'><a href="prosupport.html">Purchase</a> +<li class='search' id='search_menubutton'> +<a href="javascript:void(0)" onclick='toggle_search()'>Search</a> +</ul> +</div> +<div class="menu submenu" id="submenu"> +<ul> +<li><a href='about.html'>About</a> +<li><a href='docs.html'>Documentation</a> +<li><a href='download.html'>Download</a> +<li><a href='support.html'>Support</a> +<li><a href='prosupport.html'>Purchase</a> +</ul> +</div> +<div class="searchmenu" id="searchmenu"> +<form method="GET" action="search"> +<select name="s" id="searchtype"> +<option value="d">Search Documentation</option> +<option value="c">Search Changelog</option> +</select> +<input type="text" name="q" id="searchbox" value=""> +<input type="submit" value="Go"> +</form> +</div> +</div> +<script> +function toggle_div(nm) { +var w = document.getElementById(nm); +if( w.style.display=="block" ){ +w.style.display = "none"; +}else{ +w.style.display = "block"; +} +} +function toggle_search() { +var w = document.getElementById("searchmenu"); +if( w.style.display=="block" ){ +w.style.display = "none"; +} else { +w.style.display = "block"; +setTimeout(function(){ +document.getElementById("searchbox").focus() +}, 30); +} +} +function div_off(nm){document.getElementById(nm).style.display="none";} +window.onbeforeunload = function(e){div_off("submenu");} +/* Disable the Search feature if we are not operating from CGI, since */ +/* Search is accomplished using CGI and will not work without it. */ +if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){ +document.getElementById("search_menubutton").style.display = "none"; +} +/* Used by the Hide/Show button beside syntax diagrams, to toggle the */ +function hideorshow(btn,obj){ +var x = document.getElementById(obj); +var b = document.getElementById(btn); +if( x.style.display!='none' ){ +x.style.display = 'none'; +b.innerHTML='show'; +}else{ +x.style.display = ''; +b.innerHTML='hide'; +} +return false; +} +var antiRobot = 0; +function antiRobotGo(){ +if( antiRobot!=3 ) return; +antiRobot = 7; +var j = document.getElementById("mtimelink"); +if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href"); +} +function antiRobotDefense(){ +document.body.onmousedown=function(){ +antiRobot |= 2; +antiRobotGo(); +document.body.onmousedown=null; +} +document.body.onmousemove=function(){ +antiRobot |= 2; +antiRobotGo(); +document.body.onmousemove=null; +} +setTimeout(function(){ +antiRobot |= 1; +antiRobotGo(); +}, 100) +antiRobotGo(); +} +antiRobotDefense(); +</script> +<div class=fancy> +<div class=nosearch> +<div class="fancy_title"> +Compile-time Options +</div> +<div class="fancy_toc"> +<a onclick="toggle_toc()"> +<span class="fancy_toc_mark" id="toc_mk">►</span> +Table Of Contents +</a> +<div id="toc_sub"><div class="fancy-toc1"><a href="#overview">1. Overview</a></div> +<div class="fancy-toc1"><a href="#recommended_compile_time_options">2. Recommended Compile-time Options</a></div> +<div class="fancy-toc1"><a href="#_platform_configuration">3. Platform Configuration</a></div> +<div class="fancy-toc1"><a href="#_options_to_set_default_parameter_values">4. Options To Set Default Parameter Values</a></div> +<div class="fancy-toc1"><a href="#_options_to_set_size_limits">5. Options To Set Size Limits</a></div> +<div class="fancy-toc1"><a href="#_options_to_control_operating_characteristics">6. Options To Control Operating Characteristics</a></div> +<div class="fancy-toc1"><a href="#_options_to_enable_features_normally_turned_off">7. Options To Enable Features Normally Turned Off</a></div> +<div class="fancy-toc1"><a href="#_options_to_disable_features_normally_turned_on">8. Options To Disable Features Normally Turned On</a></div> +<div class="fancy-toc1"><a href="#_options_to_omit_features">9. Options To Omit Features</a></div> +<div class="fancy-toc1"><a href="#_analysis_and_debugging_options">10. Analysis and Debugging Options</a></div> +<div class="fancy-toc1"><a href="#_windows_specific_options">11. Windows-Specific Options</a></div> +<div class="fancy-toc1"><a href="#compiler_linkage_and_calling_convention_control">12. Compiler Linkage and Calling Convention Control</a></div> +</div> +</div> +<script> +function toggle_toc(){ +var sub = document.getElementById("toc_sub") +var mk = document.getElementById("toc_mk") +if( sub.style.display!="block" ){ +sub.style.display = "block"; +mk.innerHTML = "▼"; +} else { +sub.style.display = "none"; +mk.innerHTML = "►"; +} +} +</script> +</div> + + + + + +<h1 id="overview"><span>1. </span>Overview</h1> + +<p> +For most purposes, SQLite can be built just fine using the default +compilation options. However, if required, the compile-time options +documented below can be used to +<a href="#omitfeatures">omit SQLite features</a> (resulting in +a <a href="footprint.html">smaller compiled library size</a>) or to change the +<a href="#defaults">default values</a> of some parameters. +</p> + +<p> +Every effort has been made to ensure that the various combinations +of compilation options work harmoniously and produce a working library. +Nevertheless, it is strongly recommended that the SQLite test-suite +be executed to check for errors before using an SQLite library built +with non-standard compilation options. +</p> + +<a name="rcmd"></a> + + +<h1 id="recommended_compile_time_options"><span>2. </span>Recommended Compile-time Options</h1> + +<p>The following compile-time options are recommended for applications that +are able to use them, in order to minimized the number of CPU cycles and +the bytes of memory used by SQLite. +Not all of these compile-time options are usable by every application. +For example, the SQLITE_THREADSAFE=0 option is only usable by applications +that never access SQLite from more than one thread at a time. And the +SQLITE_OMIT_PROGRESS_CALLBACK option is only usable by applications that +do not use the <a href="c3ref/progress_handler.html">sqlite3_progress_handler()</a> interface. And so forth. + +</p><p>It is impossible to test every possible combination of compile-time +options for SQLite. But the following set of compile-time options is +one configuration that is always fully tested. + +</p><ol> +<li><p><b><a href="compile.html#dqs">SQLITE_DQS=0</a></b>. +This setting disables the <a href="quirks.html#dblquote">double-quoted string literal</a> misfeature. + +</p></li><li><p><b><a href="compile.html#threadsafe">SQLITE_THREADSAFE=0</a></b>. +Setting -DSQLITE_THREADSAFE=0 causes all of the mutex and thread-safety logic +in SQLite to be omitted. This is the single compile-time option causes SQLite +to run about 2% faster and also reduces the size of the library by about 2%. +But the downside is that using the compile-time option means that SQLite can never +be used by more than a single thread at a time, even if each thread has its own +database connection. + +</p></li><li><p><b><a href="compile.html#default_memstatus">SQLITE_DEFAULT_MEMSTATUS=0</a></b>. +This setting causes the <a href="c3ref/status.html">sqlite3_status()</a> interfaces that track memory usage +to be disabled. This helps the <a href="c3ref/free.html">sqlite3_malloc()</a> routines run much faster, +and since SQLite uses <a href="c3ref/free.html">sqlite3_malloc()</a> internally, this helps to make the +entire library faster. + +</p></li><li><p><b><a href="compile.html#default_wal_synchronous">SQLITE_DEFAULT_WAL_SYNCHRONOUS=1</a></b>. +For maximum database safety following a power loss, the setting of +<a href="pragma.html#pragma_synchronous">PRAGMA synchronous=FULL</a> is recommended. However, in <a href="wal.html">WAL mode</a>, complete +database integrity is guaranteed with <a href="pragma.html#pragma_synchronous">PRAGMA synchronous=NORMAL</a>. With +<a href="pragma.html#pragma_synchronous">PRAGMA synchronous=NORMAL</a> in <a href="wal.html">WAL mode</a>, recent changes to the database might +be rolled back by a power loss, but the database will not be corrupted. +Furthermore, transaction commit is much faster in WAL mode using +synchronous=NORMAL than with the default synchronous=FULL. For these +reasons, it is recommended that the synchronous setting be changed from +FULL to NORMAL when switching to WAL mode. This compile-time option will +accomplish that. + +</p></li><li><p><b><a href="compile.html#like_doesnt_match_blobs">SQLITE_LIKE_DOESNT_MATCH_BLOBS</a></b>. +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> +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 +and slows the <a href="optoverview.html#like_opt">LIKE optimization</a>. When this option is set, it means that +the LIKE and GLOB operators always return FALSE if either operand is a BLOB. +That simplifies the implementation of the <a href="optoverview.html#like_opt">LIKE optimization</a> and allows +queries that use the <a href="optoverview.html#like_opt">LIKE optimization</a> to run faster. + +</p></li><li><p><b><a href="limits.html#max_expr_depth">SQLITE_MAX_EXPR_DEPTH=0</a></b>. +Setting the maximum expression parse-tree depth to zero disables all checking +of the expression parse-tree depth, which simplifies the code resulting in +faster execution, and helps the parse tree to use less memory. + +</p></li><li><p><b><a href="compile.html#omit_decltype">SQLITE_OMIT_DECLTYPE</a></b>. +By omitting the (seldom-needed) ability to return the declared type of +columns from the result set of query, <a href="c3ref/stmt.html">prepared statements</a> can be made +to consume less memory. + +</p></li><li><p><b><a href="compile.html#omit_deprecated">SQLITE_OMIT_DEPRECATED</a></b>. +Omitting deprecated interfaces and features will not help SQLite to +run any faster. It will reduce the library footprint, however. And +it is the right thing to do. + +</p></li><li><p><b><a href="compile.html#omit_progress_callback">SQLITE_OMIT_PROGRESS_CALLBACK</a></b>. +The progress handler callback counter must be checked in the inner loop +of the <a href="opcode.html">bytecode engine</a>. By omitting this interface, a single conditional +is removed from the inner loop of the <a href="opcode.html">bytecode engine</a>, helping SQL statements +to run slightly faster. + +</p></li><li><p><b><a href="compile.html#omit_shared_cache">SQLITE_OMIT_SHARED_CACHE</a></b>. +Omitting the possibility of using <a href="sharedcache.html">shared cache</a> allows many conditionals +in performance-critical sections of the code to be eliminated. This can +give a noticeable improvement in performance. + +</p></li><li><p><b><a href="compile.html#use_alloca">SQLITE_USE_ALLOCA</a></b>. +Make use of alloca() for dynamically allocating temporary stack space for +use within a single function, on systems that support alloca(). Without +this option, temporary space is allocated from the heap. + +</p></li><li><p><b><a href="compile.html#omit_autoinit">SQLITE_OMIT_AUTOINIT</a></b>. +The SQLite library needs to be initialized using a call to +<a href="c3ref/initialize.html">sqlite3_initialize()</a> before certain interfaces are used. +This initialization normally happens automatically the first time +it is needed. However, with the SQLITE_OMIT_AUTOINIT option, the automatic +initialization is omitted. This helps many API calls to run a little faster +(since they do not have to check to see if initialization has already occurred +and then run initialization if it has not previously been invoked) but it +also means that the application must call <a href="c3ref/initialize.html">sqlite3_initialize()</a> manually. +If SQLite is compiled with -DSQLITE_OMIT_AUTOINIT and a routine like +<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 +without first calling <a href="c3ref/initialize.html">sqlite3_initialize()</a>, the likely result will be +a segfault. + +</p><li<p><b><a href="compile.html#strict_subtype">SQLITE_STRICT_SUBTYPE=1</a></b>. +This option causes an error to be raised if an application defined +function that does not have the <a href="c3ref/c_deterministic.html#sqliteresultsubtype">SQLITE_RESULT_SUBTYPE</a> property +invokes the <a href="c3ref/result_subtype.html">sqlite3_result_subtype()</a> interface. The sqlite3_result_subtype() +interface does not work reliably unless the function is registered +with the SQLITE_RESULT_SUBTYPE property. This compile-time option +is designed to bring this problem to the attention of developers +early. +</li<p></li></ol> + +<p>When all of the recommended compile-time options above are used, +the SQLite library will be approximately 3% smaller and use about 5% fewer +CPU cycles. So these options do not make a huge difference. But in +some design situations, every little bit helps. + +<a name="osconfig"></a> +</p><h1 id="_platform_configuration"><span>3. </span> Platform Configuration</h1> + +<a name="sqlite_config_h"></a> +<p><b>_HAVE_SQLITE_CONFIG_H</b></p><blockquote><p> + If the _HAVE_SQLITE_CONFIG_H macro is defined + then the SQLite source code will attempt to #include a file named "config.h". + The "config.h" file usually contains other configuration options, especially + "HAVE_<i>INTERFACE</i>" type options generated by autoconf scripts. +</p></blockquote><a name="fdatasync"></a> +<p><b>HAVE_FDATASYNC</b></p><blockquote><p> + If the HAVE_FDATASYNC compile-time option is true, then the default <a href="vfs.html">VFS</a> + for unix systems will attempt to use fdatasync() instead of fsync() where + appropriate. If this flag is missing or false, then fsync() is always used. +</p></blockquote><a name="gmtime_r"></a> +<p><b>HAVE_GMTIME_R</b></p><blockquote><p> + If the HAVE_GMTIME_R option is true and if <a href="compile.html#omit_datetime_funcs">SQLITE_OMIT_DATETIME_FUNCS</a> is true, + then the CURRENT_TIME, CURRENT_DATE, and CURRENT_TIMESTAMP keywords will use + the threadsafe "gmtime_r()" interface rather than "gmtime()". In the usual case + where <a href="compile.html#omit_datetime_funcs">SQLITE_OMIT_DATETIME_FUNCS</a> is not defined or is false, then the + built-in <a href="lang_datefunc.html">date and time functions</a> are used to implement the CURRENT_TIME, + CURRENT_DATE, and CURRENT_TIMESTAMP keywords and neither gmtime_r() nor + gmtime() is ever called. +</p></blockquote><a name="isnan"></a> +<p><b>HAVE_ISNAN</b></p><blockquote><p> + If the HAVE_ISNAN option is true, then SQLite invokes the system library isnan() + function to determine if a double-precision floating point value is a NaN. + If HAVE_ISNAN is undefined or false, then SQLite substitutes its own home-grown + implementation of isnan(). +</p></blockquote><a name="localtime_r"></a> +<p><b>HAVE_LOCALTIME_R</b></p><blockquote><p> + If the HAVE_LOCALTIME_R option is true, then SQLite uses the threadsafe + localtime_r() library routine instead of localtime() + to help implement the <a href="lang_datefunc.html#localtime">localtime modifier</a> + to the built-in <a href="lang_datefunc.html">date and time functions</a>. +</p></blockquote><a name="localtime_s"></a> +<p><b>HAVE_LOCALTIME_S</b></p><blockquote><p> + If the HAVE_LOCALTIME_S option is true, then SQLite uses the threadsafe + localtime_s() library routine instead of localtime() + to help implement the <a href="lang_datefunc.html#localtime">localtime modifier</a> + to the built-in <a href="lang_datefunc.html">date and time functions</a>. +</p></blockquote><a name="malloc_usable_size"></a> +<p><b>HAVE_MALLOC_USABLE_SIZE</b></p><blockquote><p> + If the HAVE_MALLOC_USABLE_SIZE option is true, then SQLite tries uses the + malloc_usable_size() interface to find the size of a memory allocation obtained + from the standard-library malloc() or realloc() routines. This option is only + applicable if the standard-library malloc() is used. On Apple systems, + "zone malloc" is used instead, and so this option is not applicable. And, of + course, if the application supplies its own malloc implementation using + <a href="c3ref/c_config_covering_index_scan.html#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a> then this option has no effect. + <p> + If the HAVE_MALLOC_USABLE_SIZE option is omitted or is false, then SQLite + uses a wrapper around system malloc() and realloc() that enlarges each allocation + by 8 bytes and writes the size of the allocation in the initial 8 bytes, and + then SQLite also implements its own home-grown version of malloc_usable_size() + that consults that 8-byte prefix to find the allocation size. This approach + works but it is suboptimal. Applications are encouraged to use + HAVE_MALLOC_USABLE_SIZE whenever possible. +</p></blockquote><a name="strchrnul"></a> +<p><b>HAVE_STRCHRNUL</b></p><blockquote><p> + If the HAVE_STRCHRNUL option is true, then SQLite uses the strchrnul() library + function. If this option is missing or false, then SQLite substitutes its own + home-grown implementation of strchrnul(). +</p></blockquote><a name="utime"></a> +<p><b>HAVE_UTIME</b></p><blockquote><p> + If the HAVE_UTIME option is true, then the built-in but non-standard + "unix-dotfile" VFS will use the utime() system call, instead of utimes(), + to set the last access time on the lock file. +</p></blockquote><a name="byteorder"></a> +<p><b>SQLITE_BYTEORDER=<i>(0|1234|4321)</i></b></p><blockquote><p> + SQLite needs to know if the native byte order of the target CPU is + big-endian or little-ending. The SQLITE_BYTEORDER preprocessor is set + to 4321 for big-endian machines and 1234 for little-endian machines, or + it can be 0 to mean that the byte order must be determined at run-time. + There are #ifdefs in the code that set SQLITE_BYTEORDER automatically + for all common platforms and compilers. However, it may be advantageous + to set SQLITE_BYTEORDER appropriately when compiling SQLite for obscure + targets. If the target byte order cannot be determined at compile-time, + then SQLite falls back to doing run-time checks, which always work, though + with a small performance penalty. +</p></blockquote> + +<a name="defaults"></a> +<h1 id="_options_to_set_default_parameter_values"><span>4. </span> Options To Set Default Parameter Values</h1> + +<a name="default_automatic_index"></a> +<p><b>SQLITE_DEFAULT_AUTOMATIC_INDEX=<i><0 or 1></i></b></p><blockquote><p> + This macro determines the initial setting for <a href="pragma.html#pragma_automatic_index">PRAGMA automatic_index</a> + for newly opened <a href="c3ref/sqlite3.html">database connections</a>. + For all versions of SQLite through 3.7.17, + automatic indices are normally enabled for new database connections if + this compile-time option is omitted. + However, that might change in future releases of SQLite. + <p>See also: <a href="compile.html#omit_automatic_index">SQLITE_OMIT_AUTOMATIC_INDEX</a> +</p></blockquote><a name="default_autovacuum"></a> +<p><b>SQLITE_DEFAULT_AUTOVACUUM=<i><0 or 1 or 2></i></b></p><blockquote><p> + This macro determines if SQLite creates databases with the + <a href="pragma.html#pragma_auto_vacuum">auto_vacuum</a> flag set by default to OFF (0), FULL (1), or + INCREMENTAL (2). The default value is 0 meaning that databases + are created with auto-vacuum turned off. + In any case the compile-time default may be overridden by the + <a href="pragma.html#pragma_auto_vacuum">PRAGMA auto_vacuum</a> command. +</p></blockquote><a name="default_cache_size"></a> +<p><b>SQLITE_DEFAULT_CACHE_SIZE=<i><N></i></b></p><blockquote><p> + This macro sets the default maximum size of the page-cache for each attached + database. A positive value means that the limit is N page. If N is negative + that means to limit the cache size to -N*1024 bytes. + The suggested maximum cache size can be overridden by the + <a href="pragma.html#pragma_cache_size">PRAGMA cache_size</a> command. The default value is -2000, which translates + into a maximum of 2048000 bytes per cache. +</p></blockquote><a name="default_file_format"></a> +<p><b>SQLITE_DEFAULT_FILE_FORMAT=<i><1 or 4></i></b></p><blockquote><p> + The default <a href="fileformat2.html#schemaformat">schema format number</a> used by SQLite when creating + new database files is set by this macro. The schema formats are all + very similar. The difference between formats 1 and 4 is that format + 4 understands <a href="lang_createindex.html#descidx">descending indices</a> and has a tighter encoding for + boolean values.</p> + +<p> All versions of SQLite since 3.3.0 (2006-01-10) + can read and write any schema format + between 1 and 4. But older versions of SQLite might not be able to + read formats greater than 1. So that older versions of SQLite will + be able to read and write database files created by newer versions + of SQLite, the default schema format was set to 1 for SQLite versions + through 3.7.9 (2011-11-01). Beginning with + <a href="releaselog/3_7_10.html">version 3.7.10</a> (2012-01-16), the default + schema format is 4.</p> + +<p> The schema format number for a new database can be set at runtime using + the <a href="pragma.html#pragma_legacy_file_format">PRAGMA legacy_file_format</a> command. +</p></blockquote><a name="default_file_permissions"></a> +<p><b>SQLITE_DEFAULT_FILE_PERMISSIONS=<i>N</i></b></p><blockquote><p> + The default numeric file permissions for newly created database files + under unix. If not specified, the default is 0644 which means that + the files is globally readable but only writable by the creator. +</p></blockquote><a name="default_foreign_keys"></a> +<p><b>SQLITE_DEFAULT_FOREIGN_KEYS=<i><0 or 1></i></b></p><blockquote><p> + This macro determines whether enforcement of + <a href="foreignkeys.html">foreign key constraints</a> is enabled or disabled by default for + new database connections. Each database connection can always turn + enforcement of foreign key constraints on and off and run-time using + the <a href="pragma.html#pragma_foreign_keys">foreign_keys pragma</a>. Enforcement of foreign key constraints + is normally off by default, but if this compile-time parameter is + set to 1, enforcement of foreign key constraints will be on by default. +</p></blockquote><a name="default_mmap_size"></a> +<p><b>SQLITE_DEFAULT_MMAP_SIZE=<i>N</i></b></p><blockquote><p> + This macro sets the default limit on the amount of memory that + will be used for memory-mapped I/O + for each open database file. If the <i>N</i> + is zero, then memory mapped I/O is disabled by default. This + compile-time limit and the <a href="compile.html#max_mmap_size">SQLITE_MAX_MMAP_SIZE</a> can be modified + at start-time using the + <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 + using the <a href="pragma.html#pragma_mmap_size">mmap_size pragma</a>. +</p></blockquote><a name="default_journal_size_limit"></a> +<p><b>SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT=<i><bytes></i></b></p><blockquote><p> + This option sets the size limit on <a href="lockingv3.html#rollback">rollback journal</a> files in + <a href="pragma.html#pragma_journal_mode">persistent journal mode</a> and + <a href="pragma.html#pragma_locking_mode">exclusive locking mode</a> and on the size of the + write-ahead log file in <a href="wal.html">WAL mode</a>. When this + compile-time option is omitted there is no upper bound on the + size of the rollback journals or write-ahead logs. + The journal file size limit + can be changed at run-time using the <a href="pragma.html#pragma_journal_size_limit">journal_size_limit pragma</a>. +</p></blockquote><a name="default_locking_mode"></a> +<p><b>SQLITE_DEFAULT_LOCKING_MODE=<i><1 or 0></i></b></p><blockquote><p> + If set to 1, then the default <a href="pragma.html#pragma_locking_mode">locking_mode</a> is set to EXCLUSIVE. + If omitted or set to 0 then the default <a href="pragma.html#pragma_locking_mode">locking_mode</a> is NORMAL. +</p></blockquote><a name="default_lookaside"></a> +<p><b>SQLITE_DEFAULT_LOOKASIDE=<i>SZ,N</i></b></p><blockquote><p> + Sets the default size of the <a href="malloc.html#lookaside">lookaside memory allocator</a> memory pool + to N entries of SZ bytes each. This setting can be modified at + 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 + as each <a href="c3ref/sqlite3.html">database connection</a> is opened using + <a href="c3ref/db_config.html">sqlite3_db_config</a>(db, <a href="c3ref/c_dbconfig_defensive.html#sqlitedbconfiglookaside">SQLITE_DBCONFIG_LOOKASIDE</a>). +</p></blockquote><a name="default_memstatus"></a> +<p><b>SQLITE_DEFAULT_MEMSTATUS=<i><1 or 0></i></b></p><blockquote><p> + This macro is used to determine whether or not the features enabled and + disabled using the SQLITE_CONFIG_MEMSTATUS argument to <a href="c3ref/config.html">sqlite3_config()</a> + are available by default. The default value is 1 (<a href="c3ref/c_config_covering_index_scan.html#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a> + related features enabled). + <p> + The <a href="c3ref/memory_highwater.html">sqlite3_memory_used()</a> and <a href="c3ref/memory_highwater.html">sqlite3_memory_highwater()</a> interfaces, + the <a href="c3ref/status.html">sqlite3_status64</a>(<a href="c3ref/c_status_malloc_count.html#sqlitestatusmemoryused">SQLITE_STATUS_MEMORY_USED</a>) interface, + and the <a href="compile.html#max_memory">SQLITE_MAX_MEMORY</a> compile-time option are all non-functional + when memory usage tracking is disabled. +</p></blockquote><a name="default_pcache_initsz"></a> +<p><b>SQLITE_DEFAULT_PCACHE_INITSZ=<i>N</i></b></p><blockquote><p> + This macro determines the number of pages initially allocated by the + page cache module when <a href="c3ref/c_config_covering_index_scan.html#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a> configuration option is + not use and memory for the page cache is obtained from <a href="c3ref/free.html">sqlite3_malloc()</a> + instead. The number of pages set by this macro are allocated in a single + allocation, which reduces the load on the memory allocator. +</p></blockquote><a name="default_page_size"></a> +<p><b>SQLITE_DEFAULT_PAGE_SIZE=<i><bytes></i></b></p><blockquote><p> + This macro is used to set the default page-size used when a + database is created. The value assigned must be a power of 2. The + default value is 4096. The compile-time default may be overridden at + runtime by the <a href="pragma.html#pragma_page_size">PRAGMA page_size</a> command. +</p></blockquote><a name="default_synchronous"></a> +<p><b>SQLITE_DEFAULT_SYNCHRONOUS=<i><0-3></i></b></p><blockquote><p> + This macro determines the default value of the + <a href="pragma.html#pragma_synchronous">PRAGMA synchronous</a> setting. If not overridden at compile-time, + the default setting is 2 (FULL). +</p></blockquote><a name="default_wal_synchronous"></a> +<p><b>SQLITE_DEFAULT_WAL_SYNCHRONOUS=<i><0-3></i></b></p><blockquote><p> + This macro determines the default value of the + <a href="pragma.html#pragma_synchronous">PRAGMA synchronous</a> setting for database files that open in + <a href="wal.html">WAL mode</a>. If not overridden at compile-time, this value is the + same as <a href="compile.html#default_synchronous">SQLITE_DEFAULT_SYNCHRONOUS</a>. + <p> + If SQLITE_DEFAULT_WAL_SYNCHRONOUS differs from SQLITE_DEFAULT_SYNCHRONOUS, + and if the application has not modified the synchronous setting for + the database file using the <a href="pragma.html#pragma_synchronous">PRAGMA synchronous</a> statement, then + the synchronous setting is changed to value defined by + SQLITE_DEFAULT_WAL_SYNCHRONOUS when the database connection switches + into WAL mode for the first time. + If the SQLITE_DEFAULT_WAL_SYNCHRONOUS value is not overridden at + compile-time, then it will always be the same as + <a href="compile.html#default_synchronous">SQLITE_DEFAULT_SYNCHRONOUS</a> and so no automatic synchronous setting + changes will ever occur. +</p></blockquote><a name="default_wal_autocheckpoint"></a> +<p><b>SQLITE_DEFAULT_WAL_AUTOCHECKPOINT=<i><pages></i></b></p><blockquote><p> + This macro sets the default page count for the <a href="wal.html">WAL</a> + <a href="wal.html#ckpt">automatic checkpointing</a> feature. If unspecified, + the default page count is 1000. +</p></blockquote><a name="default_worker_threads"></a> +<p><b>SQLITE_DEFAULT_WORKER_THREADS=<i>N</i></b></p><blockquote><p> + This macro sets the default value for + the <a href="c3ref/c_limit_attached.html#sqlitelimitworkerthreads">SQLITE_LIMIT_WORKER_THREADS</a> parameter. The <a href="c3ref/c_limit_attached.html#sqlitelimitworkerthreads">SQLITE_LIMIT_WORKER_THREADS</a> + parameter sets the maximum number of auxiliary threads that a single + <a href="c3ref/stmt.html">prepared statement</a> will launch to assist it with a query. If not specified, + the default maximum is 0. + The value set here cannot be more than <a href="compile.html#max_worker_threads">SQLITE_MAX_WORKER_THREADS</a>. +</p></blockquote><a name="dqs"></a> +<p><b>SQLITE_DQS=<i>N</i></b></p><blockquote><p> + This macro determines the default values for + <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 + in turn determine how SQLite handles each <a href="quirks.html#dblquote">double-quoted string literal</a>. + The "DQS" name stands for + "<u>D</u>ouble-<u>Q</u>uoted <u>S</u>tring". + The <i>N</i> argument should be an integer 0, 1, 2, or 3. + <blockquote><table border=1 cellpadding="0" cellspacing="0"> + <tr><th rowspan="2">SQLITE_DQS<th colspan="2">Double-Quoted Strings Allowed + <th rowspan="2">Remarks + <tr><th>In DDL<th>In DML + <tr><td>3<td>yes<td>yes<td>default + <tr><td>2<td>yes<td>no<td> + <tr><td>1<td>no<td>yes<td> + <tr><td>0<td>no<td>no<td>recommended + </table></blockquote> + <p>The recommended setting is 0, meaning that double-quoted + strings are disallowed in all contexts. However, the default + setting is 3 for maximum compatibility with legacy applications. +</p></blockquote><a name="extra_durable"></a> +<p><b>SQLITE_EXTRA_DURABLE</b></p><blockquote><p> + The SQLITE_EXTRA_DURABLE compile-time option that used to cause the default + <a href="pragma.html#pragma_synchronous">PRAGMA synchronous</a> setting to be EXTRA, rather than FULL. This option + is no longer supported. Use + <a href="compile.html#default_synchronous">SQLITE_DEFAULT_SYNCHRONOUS=3</a> instead. +</p></blockquote><a name="fts3_max_expr_depth"></a> +<p><b>SQLITE_FTS3_MAX_EXPR_DEPTH=<i>N</i></b></p><blockquote><p> + This macro sets the maximum depth of the search tree that corresponds to + 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 + index. The full-text search uses a recursive algorithm, so the depth of + the tree is limited to prevent using too much stack space. The default + limit is 12. This limit is sufficient for up to 4095 search terms on the + right-hand side of the MATCH operator and it holds stack space usage to + less than 2000 bytes. + <p> + For ordinary FTS3/FTS4 queries, the search tree depth is approximately + the base-2 logarithm of the number of terms in the right-hand side of the + MATCH operator. However, for <a href="fts3.html#phrase">phrase queries</a> and <a href="fts3.html#near">NEAR queries</a> the + search tree depth is linear in the number of right-hand side terms. + So the default depth limit of 12 is sufficient for up to 4095 ordinary + terms on a MATCH, it is only sufficient for 11 or 12 phrase or NEAR + terms. Even so, the default is more than enough for most application. +</p></blockquote><a name="json_max_depth"></a> +<p><b>SQLITE_JSON_MAX_DEPTH=<i>N</i></b></p><blockquote><p> + This macro sets the maximum nesting depth for JSON objects and arrays. + The default value is 1000. + <p> + The <a href="json1.html">JSON SQL functions</a> use a + <a href="https://en.wikipedia.org/wiki/Recursive_descent_parser">recursive decent parser</a>. + This means that deeply nested JSON might require a lot of stack space to + parse. On systems with limited stack space, SQLite can be compiled with + a greatly reduced maximum JSON nesting depth to avoid the possibility of + a stack overflow, even from hostile inputs. A value of 10 or 20 is normally + sufficient even for the most complex real-world JSON. +</p></blockquote><a name="like_doesnt_match_blobs"></a> +<p><b>SQLITE_LIKE_DOESNT_MATCH_BLOBS</b></p><blockquote><p> + This compile-time option causes the <a href="lang_expr.html#like">LIKE</a> operator to always return + False if either operand is a BLOB. The default behavior of <a href="lang_expr.html#like">LIKE</a> + is that BLOB operands are cast to TEXT before the comparison is done. + <p> + This compile-time option makes SQLite run more efficiently when processing + queries that use the <a href="lang_expr.html#like">LIKE</a> operator, at the expense of breaking backwards + compatibility. However, the backwards compatibility break may be only + a technicality. There was a long-standing bug in the <a href="lang_expr.html#like">LIKE</a> processing logic + (see <a href="https://www.sqlite.org/src/info/05f43be8fdda9f">https://www.sqlite.org/src/info/05f43be8fdda9f</a>) that caused it to + misbehavior for BLOB operands and nobody observed that bug in nearly + 10 years of active use. So for more users, it is probably safe to + enable this compile-time option and thereby save a little CPU time + on LIKE queries. + <p> + This compile-time option affects the SQL <a href="lang_expr.html#like">LIKE</a> operator only and has + no impact on the <a href="c3ref/strlike.html">sqlite3_strlike()</a> C-language interface. +</p></blockquote><a name="max_memory"></a> +<p><b>SQLITE_MAX_MEMORY=<i>N</i></b></p><blockquote><p> + This option limits the total amount of memory that SQLite will request + from malloc() to <i>N</i> bytes. Any attempt by SQLite to allocate + new memory that would cause the sum of all allocations held by SQLite to exceed + <i>N</i> bytes will result in an out-of-memory error. + This is a hard upper limit. See also the <a href="c3ref/soft_heap_limit.html">sqlite3_soft_heap_limit()</a> + interface. + <p> + This option is a limit on the <i>total</i> amount of memory allocated. + See the <a href="compile.html#max_allocation_size">SQLITE_MAX_ALLOCATION_SIZE</a> option for a limitation on the amount + of memory allowed in any single memory allocation. + <p> + This limit is only functional if memory usage statistics are available via + 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>) + interfaces. Without that memory usage information, SQLite has no way of + knowing when it is about to go over the limit, and thus is unable to prevent + the excess memory allocation. Memory usage tracking is turned on by default, + but can be disabled at compile-time using the <a href="compile.html#default_memstatus">SQLITE_DEFAULT_MEMSTATUS</a> option, + 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>). +</p></blockquote><a name="max_mmap_size"></a> +<p><b>SQLITE_MAX_MMAP_SIZE=<i>N</i></b></p><blockquote><p> + This macro sets a hard upper bound on the amount of address space that + can be used by any single database for memory-mapped I/O. + Setting this value to 0 completely disables memory-mapped I/O and + causes logic associated with memory-mapped I/O to be omitted from the + build. This option does change the default memory-mapped I/O address + space size (set by <a href="compile.html#default_mmap_size">SQLITE_DEFAULT_MMAP_SIZE</a> or + sqlite3_config(<a href="c3ref/c_config_covering_index_scan.html#sqliteconfigmmapsize">SQLITE_CONFIG_MMAP_SIZE</a>) or the + run-time memory-mapped I/O address space size (set by + sqlite3_file_control(<a href="c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlmmapsize">SQLITE_FCNTL_MMAP_SIZE</a>) or + <a href="pragma.html#pragma_mmap_size">PRAGMA mmap_size</a>) as long as those other settings are less than the + maximum value defined here. +</p></blockquote><a name="max_schema_retry"></a> +<p><b>SQLITE_MAX_SCHEMA_RETRY=<i>N</i></b></p><blockquote><p> + Whenever the database schema changes, prepared statements are automatically + reprepared to accommodate the new schema. There is a race condition here + in that if one thread is constantly changing the schema, another thread + might spin on reparses and repreparations of a prepared statement and + never get any real work done. This parameter prevents an infinite loop + by forcing the spinning thread to give up after a fixed number of attempts + at recompiling the prepared statement. The default setting is 50 which is + more than adequate for most applications. +</p></blockquote><a name="max_worker_threads"></a> +<p><b>SQLITE_MAX_WORKER_THREADS=<i>N</i></b></p><blockquote><p> + 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) + setting that determines the maximum number of auxiliary threads that a single + <a href="c3ref/stmt.html">prepared statement</a> will use to aid with CPU-intensive computations + (mostly sorting). See also the <a href="compile.html#default_worker_threads">SQLITE_DEFAULT_WORKER_THREADS</a> options. +</p></blockquote><a name="memdb_default_maxsize"></a> +<p><b>SQLITE_MEMDB_DEFAULT_MAXSIZE=<i>N</i></b></p><blockquote><p> + Set the default size limit (in bytes) for in-memory databases created using + <a href="c3ref/deserialize.html">sqlite3_deserialize()</a>. This is just the default. The limit can be + changed at start-time using + <a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_covering_index_scan.html#sqliteconfigmemdbmaxsize">SQLITE_CONFIG_MEMDB_MAXSIZE</a>,N) + or at run-time for individual databases using the + <a href="c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlsizelimit">SQLITE_FCNTL_SIZE_LIMIT</a> <a href="c3ref/file_control.html">file-control</a>. + If no default is specified, 1073741824 is used. +</p></blockquote><a name="minimum_file_descriptor"></a> +<p><b>SQLITE_MINIMUM_FILE_DESCRIPTOR=<i>N</i></b></p><blockquote><p> + The unix <a href="vfs.html">VFS</a> will never use a file descriptor less than <i>N</i>. The + default value of <i>N</i> is 3. + <p> + Avoiding the use of low-numbered file descriptors is a defense against + accidental database corruption. If a database file was opened using + file descriptor 2, for example, and then an assert() failed and invoked + write(2,...), that would likely cause database corruption by overwriting + part of the database file with the assertion error message. Using only + higher-valued file descriptors avoids this potential problem. The + protection against + using low-numbered file descriptors can be disabled by setting this + compile-time option to 0. +</p></blockquote><a name="powersafe_overwrite"></a> +<p><b>SQLITE_POWERSAFE_OVERWRITE=<i><0 or 1></i></b></p><blockquote><p> + This option changes the default assumption about <a href="psow.html">powersafe overwrite</a> + for the underlying filesystems for the unix and windows <a href="vfs.html">VFSes</a>. + Setting SQLITE_POWERSAFE_OVERWRITE to 1 causes SQLite to assume that + application-level writes cannot changes bytes outside the range of + bytes written even if the write occurs just before a power loss. + With SQLITE_POWERSAFE_OVERWRITE set to 0, SQLite assumes that other + bytes in the same sector with a written byte might be changed or + damaged by a power loss. +</p></blockquote><a name="printf_precision_limit"></a> +<p><b>SQLITE_PRINTF_PRECISION_LIMIT=<i>N</i></b></p><blockquote><p> + This option limits the maximum width and precision of substitutions + for the <a href="lang_corefunc.html#printf">printf() SQL function</a> and the other C-language string + formatting functions such as <a href="c3ref/mprintf.html">sqlite3_mprintf()</a> and + <a href="c3ref/str_append.html">sqlite3_str_appendf()</a>. This is turn can prevent a hostile or + malfunctioning script from using excessive memory by invoking + a format such as: "<tt>printf('%*s',2147483647,'hi')</tt>". + A value for <i>N</i> of around 100000 is normally sufficient. + <p> + 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> + limit of <a href="c3ref/limit.html">sqlite3_limit()</a>. Hence any printf() result with a + width or precision more than the SQLITE_LIMIT_LENGTH will cause + an <a href="rescode.html#toobig">SQLITE_TOOBIG</a> error. However, the low-level formatting + for the printf() function is done by a subroutine that does not + have access to SQLITE_LIMIT_LENGTH. So the low-level formatting + is done into a memory allocation that might be considerably larger + than SQLITE_LIMIT_LENGTH and the SQLITE_LIMIT_LENGTH check is only + performed after all formatting is complete. Thus there might be a + transient buffer that exceeds SQLITE_LIMIT_LENGTH. The + SQLITE_PRINTF_PRECISION_LIMIT option is an additional check + that prevents excess sizes for the transient buffer used inside + the low-level formatting subroutine, prior to the + SQLITE_LIMIT_LENGTH check. + <p> + Be careful not to set SQLITE_PRINTF_PRECISION_LIMIT too low. + SQLite uses its <a href="printf.html">built-in printf()</a> functionality to format the text + of CREATE statements stored in the <a href="schematab.html">sqlite_schema table</a>. So + SQLITE_PRINTF_PRECISION_LIMIT should be at least as big as the largest + table, index, view, or trigger definition that you are likely to + encounter. + <p> + No error is raised if a width or precision exceeds + SQLITE_PRINTF_PRECISION_LIMIT. Instead, the large width or + precision is silently truncated. + <p> + The default value for SQLITE_PRINTF_PRECISION_LIMIT is 2147483647 + (0x7fffffff).</p> + +<p></p></blockquote><a name="query_planner_limit"></a> +<p><b>SQLITE_QUERY_PLANNER_LIMIT=<i>N</i></b></p><blockquote><p> + As part of the query planning process, SQLite enumerates all usable + combinations of indexes and WHERE-clause constraints. For certain + pathological queries, the number of these index-and-constraint combinations + can be very large, resulting in slow performance by the query planner. + The SQLITE_QUERY_PLANNER_LIMIT value (in conjunction with the + related <a href="compile.html#query_planner_limit_incr">SQLITE_QUERY_PLANNER_LIMIT_INCR</a> setting) limits the number + of index-and-constraint combinations that the query planner will + consider, in order to prevent the query planner from using excess + CPU time. The default value for SQLITE_QUERY_PLANNER_LIMIT is set + high enough so that is never reached for real-world queries. The + query planner search limit only applies to queries that are deliberately + crafted to use excess planning time. +</p></blockquote><a name="query_planner_limit_incr"></a> +<p><b>SQLITE_QUERY_PLANNER_LIMIT_INCR=<i>N</i></b></p><blockquote><p> + The <a href="compile.html#query_planner_limit">SQLITE_QUERY_PLANNER_LIMIT</a> option sets an initial baseline value + for the maximum number of index-and-constraint combinations that the + query planner consider. The baseline query planner limit is increased + by SQLITE_QUERY_PLANNER_LIMIT_INCR prior to processing each table of a + join so that each table is guaranteed to be able to propose at least + some index-and-constraint combinations to the optimizer even if prior + tables of the join have exhausted the baseline limit. The default + value for both this compile-time option and the + <a href="compile.html#query_planner_limit">SQLITE_QUERY_PLANNER_LIMIT</a> option are set high enough so that they should + never be reached for real-world queries. +</p></blockquote><a name="reverse_unordered_selects"></a> +<p><b>SQLITE_REVERSE_UNORDERED_SELECTS</b></p><blockquote><p> + This option causes the <a href="pragma.html#pragma_reverse_unordered_selects">PRAGMA reverse_unordered_selects</a> setting to be + enabled by default. When enabled, <a href="lang_select.html">SELECT</a> statements that lack an + ORDER BY clause will run in reverse order.<p> + This option is useful for detecting when applications (incorrectly) + assume that the order of rows in a SELECT without an ORDER BY clause + will always be the same. +</p></blockquote><a name="sorter_pmasz"></a> +<p><b>SQLITE_SORTER_PMASZ=<i>N</i></b></p><blockquote><p> + If multi-threaded processing is enabled via the + <a href="pragma.html#pragma_threads">PRAGMA threads</a> setting, then sort operations will + attempt to start helper threads when the amount of content + to be sorted exceeds the minimum of the <a href="pragma.html#pragma_cache_size">cache_size</a> and PMA Size + determined by the <a href="c3ref/c_config_covering_index_scan.html#sqliteconfigpmasz">SQLITE_CONFIG_PMASZ</a> start-time option. + This compile-time option sets the default value for the + <a href="c3ref/c_config_covering_index_scan.html#sqliteconfigpmasz">SQLITE_CONFIG_PMASZ</a> start-time option. + The default value is 250. +</p></blockquote><a name="stmtjrnl_spill"></a> +<p><b>SQLITE_STMTJRNL_SPILL=<i>N</i></b></p><blockquote><p> + The SQLITE_STMTJRNL_SPILL compile-time option determines the + default setting of the <a href="c3ref/c_config_covering_index_scan.html#sqliteconfigstmtjrnlspill">SQLITE_CONFIG_STMTJRNL_SPILL</a> start-time + setting. That setting determines the size threshold above which + <a href="tempfiles.html#stmtjrnl">statement journals</a> are moved from memory to disk. +</p></blockquote><a name="win32_malloc"></a> +<p><b>SQLITE_WIN32_MALLOC</b></p><blockquote><p> + This option enables the use of the Windows Heap API functions for memory + allocation instead of the standard library malloc() and free() routines. +</p></blockquote><a name="yystackdepth"></a> +<p><b>YYSTACKDEPTH=<i><max_depth></i></b></p><blockquote><p> + This macro sets the maximum depth of the LALR(1) stack used by + the SQL parser within SQLite. The default value is 100. A typical + application will use less than about 20 levels of the stack. + Developers whose applications contain SQL statements that + need more than 100 LALR(1) stack entries should seriously + consider refactoring their SQL as it is likely to be well beyond + the ability of any human to comprehend. +</p></blockquote> + +<h1 id="_options_to_set_size_limits"><span>5. </span> Options To Set Size Limits</h1> + +<p>There are compile-time options that will set upper bounds +on the sizes of various structures in SQLite. The compile-time +options normally set a hard upper bound that can be changed +at run-time on individual <a href="c3ref/sqlite3.html">database connections</a> using the +<a href="c3ref/limit.html">sqlite3_limit()</a> interface.</p> + +<p>The compile-time options for setting upper bounds are +<a href="limits.html">documented separately</a>. The following is a list of +the available settings:</p> + +<ul> +<li> <a href="limits.html#max_attached">SQLITE_MAX_ATTACHED</a> </li> +<li> <a href="limits.html#max_column">SQLITE_MAX_COLUMN</a> </li> +<li> <a href="limits.html#max_compound_select">SQLITE_MAX_COMPOUND_SELECT</a> </li> +<li> <a href="limits.html#max_expr_depth">SQLITE_MAX_EXPR_DEPTH</a> </li> +<li> <a href="limits.html#max_function_arg">SQLITE_MAX_FUNCTION_ARG</a> </li> +<li> <a href="limits.html#max_length">SQLITE_MAX_LENGTH</a> </li> +<li> <a href="limits.html#max_like_pattern_length">SQLITE_MAX_LIKE_PATTERN_LENGTH</a> </li> +<li> <a href="limits.html#max_page_count">SQLITE_MAX_PAGE_COUNT</a> </li> +<li> <a href="limits.html#max_sql_length">SQLITE_MAX_SQL_LENGTH</a> </li> +<li> <a href="limits.html#max_variable_number">SQLITE_MAX_VARIABLE_NUMBER</a> </li> +</ul> + +<p>There are also some size limits that cannot be modified using +<a href="c3ref/limit.html">sqlite3_limit()</a>. See, for example: + +</p><ul> +<li> <a href="compile.html#fts3_max_expr_depth">SQLITE_FTS3_MAX_EXPR_DEPTH</a> </li> +<li> <a href="compile.html#json_max_depth">SQLITE_JSON_MAX_DEPTH</a> </li> +<li> <a href="compile.html#max_allocation_size">SQLITE_MAX_ALLOCATION_SIZE</a> </li> +<li> <a href="compile.html#max_memory">SQLITE_MAX_MEMORY</a> </li> +<li> <a href="compile.html#max_mmap_size">SQLITE_MAX_MMAP_SIZE</a> </li> +<li> <a href="compile.html#printf_precision_limit">SQLITE_PRINTF_PRECISION_LIMIT</a> </li> +<li> <a href="compile.html#trace_size_limit">SQLITE_TRACE_SIZE_LIMIT</a> </li> +<li> <a href="compile.html#yystackdepth">YYSTACKDEPTH</a> </li> +</ul> + +<a name="controlfeatures"></a> +<h1 id="_options_to_control_operating_characteristics"><span>6. </span> Options To Control Operating Characteristics</h1> + +<a name="4_byte_aligned_malloc"></a> +<p><b>SQLITE_4_BYTE_ALIGNED_MALLOC</b></p><blockquote><p> + On most systems, the malloc() system call returns a buffer that is + aligned to an 8-byte boundary. But on some systems (ex: windows) malloc() + returns 4-byte aligned pointer. This compile-time option must be used + on systems that return 4-byte aligned pointers from malloc(). +</p></blockquote><a name="case_sensitive_like"></a> +<p><b>SQLITE_CASE_SENSITIVE_LIKE</b></p><blockquote><p> + If this option is present, then the built-in <a href="lang_expr.html#like">LIKE</a> operator will be + case sensitive. This same effect can be achieved at run-time using + the <a href="pragma.html#pragma_case_sensitive_like">case_sensitive_like pragma</a>. +</p></blockquote><a name="direct_overflow_read"></a> +<p><b>SQLITE_DIRECT_OVERFLOW_READ</b></p><blockquote><p> + When this option is present, content contained in + <a href="fileformat2.html#ovflpgs">overflow pages</a> of the database file is read directly from disk, + bypassing the <a href="c3ref/pcache_methods2.html">page cache</a>, during read transactions. In applications + that do a lot of reads of large BLOBs or strings, this option improves + read performance. + <p> + As of version 3.45.0 (2024-01-15), this option is enabled by + default. To disable it, using -DSQLITE_DIRECT_OVERFLOW_READ=0. +</p></blockquote><a name="have_isnan"></a> +<p><b>SQLITE_HAVE_ISNAN</b></p><blockquote><p> + If this option is present, then SQLite will use the isnan() function from + the system math library. This is an alias for the <a href="compile.html#isnan">HAVE_ISNAN</a> configuration + option. +</p></blockquote><a name="max_allocation_size"></a> +<p><b>SQLITE_MAX_ALLOCATION_SIZE=<i>N</i></b></p><blockquote><p> + This compile-time option sets an upper bound on the size of memory + allocations that can be requested using <a href="c3ref/free.html">sqlite3_malloc64()</a>, + <a href="c3ref/free.html">sqlite3_realloc64()</a>, and similar. The default value is + 2,147,483,391 (0x7ffffeff) and this should be considered an + upper bound. Most applications can get by with a maximum allocation + size of a few million bytes. + <p> + This is a limit on the maximum size of any single memory allocation. + It is <i>not</i> a limit on the total amount of memory allocated. + See <a href="compile.html#max_memory">SQLITE_MAX_MEMORY</a> for a limitation on the total amount of memory + allocated. + <p> + Reducing the maximum size of individual memory allocations provides + extra defense against denial-of-service attacks that attempt to exhaust + system memory by doing many large allocations. It is also an extra layer + of defense against application bugs where the size of a memory allocation + is computed using a signed 32-bit integer that could overflow → + with a small maximum allocation size, such buggy memory allocation size + computations are likely to be spotted sooner due to out-of-memory errors + and before the integer actually overflows. +</p></blockquote><a name="os_other"></a> +<p><b>SQLITE_OS_OTHER=<i><0 or 1></i></b></p><blockquote><p> + The option causes SQLite to omit its built-in operating system interfaces + for Unix, Windows, and OS/2. The resulting library will have no default + <a href="c3ref/vfs.html">operating system interface</a>. Applications must use + <a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a> to register an appropriate interface before + using SQLite. Applications must also supply implementations for the + <a href="c3ref/initialize.html">sqlite3_os_init()</a> and <a href="c3ref/initialize.html">sqlite3_os_end()</a> interfaces. The usual practice + 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>. + SQLite will automatically invoke <a href="c3ref/initialize.html">sqlite3_os_init()</a> when it initializes.</p> + +<p> This option is typically used when building SQLite for an embedded + platform with a custom operating system. +</p></blockquote><a name="secure_delete"></a> +<p><b>SQLITE_SECURE_DELETE</b></p><blockquote><p> + This compile-time option changes the default setting of the + <a href="pragma.html#pragma_secure_delete">secure_delete pragma</a>. When this option is not used, secure_delete defaults + to off. When this option is present, secure_delete defaults to on.</p> + +<p> The secure_delete setting causes deleted content to be overwritten with + zeros. There is a small performance penalty since additional I/O + must occur. On the other hand, secure_delete can prevent fragments of + sensitive information from lingering in unused parts of the database file + after it has been deleted. See the documentation on the + <a href="pragma.html#pragma_secure_delete">secure_delete pragma</a> for additional information. +</p></blockquote><a name="threadsafe"></a> +<p><b>SQLITE_THREADSAFE=<i><0 or 1 or 2></i></b></p><blockquote><p> + This option controls whether or not code is included in SQLite to + enable it to operate safely in a multithreaded environment. The + default is SQLITE_THREADSAFE=1 which is safe for use in a multithreaded + environment. When compiled with SQLITE_THREADSAFE=0 all mutexing code + is omitted and it is unsafe to use SQLite in a multithreaded program. + When compiled with SQLITE_THREADSAFE=2, SQLite can be used in a multithreaded + program so long as no two threads attempt to use the same + <a href="c3ref/sqlite3.html">database connection</a> (or any <a href="c3ref/stmt.html">prepared statements</a> derived from + that database connection) at the same time.</p> + +<p> To put it another way, SQLITE_THREADSAFE=1 sets the default + <a href="threadsafe.html">threading mode</a> to Serialized. SQLITE_THREADSAFE=2 sets the default + <a href="threadsafe.html">threading mode</a> to Multi-threaded. And SQLITE_THREADSAFE=0 sets the + <a href="threadsafe.html">threading mode</a> to Single-threaded.</p> + +<p> The value of SQLITE_THREADSAFE can be determined at run-time + using the <a href="c3ref/threadsafe.html">sqlite3_threadsafe()</a> interface.</p> + +<p> When SQLite has been compiled with SQLITE_THREADSAFE=1 or + SQLITE_THREADSAFE=2 then the <a href="threadsafe.html">threading mode</a> + can be altered at run-time using the <a href="c3ref/config.html">sqlite3_config()</a> interface together + with one of these verbs:</p> + +<p> <ul> + <li><a href="c3ref/c_config_covering_index_scan.html#sqliteconfigsinglethread">SQLITE_CONFIG_SINGLETHREAD</a> + <li><a href="c3ref/c_config_covering_index_scan.html#sqliteconfigmultithread">SQLITE_CONFIG_MULTITHREAD</a> + <li><a href="c3ref/c_config_covering_index_scan.html#sqliteconfigserialized">SQLITE_CONFIG_SERIALIZED</a> + </ul></p> + +<p> The <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_NOMUTEX</a> and + <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 + to adjust the <a href="threadsafe.html">threading mode</a> of individual <a href="c3ref/sqlite3.html">database connections</a> + at run-time.</p> + +<p> Note that when SQLite is compiled with SQLITE_THREADSAFE=0, the code + to make SQLite threadsafe is omitted from the build. When this occurs, + it is impossible to change the <a href="threadsafe.html">threading mode</a> at start-time or run-time.</p> + +<p> See the <a href="threadsafe.html">threading mode</a> documentation for additional information + on aspects of using SQLite in a multithreaded environment. +</p></blockquote><a name="temp_store"></a> +<p><b>SQLITE_TEMP_STORE=<i><0 through 3></i></b></p><blockquote><p> + This option controls whether temporary files are stored on disk or + in memory. The meanings for various settings of this compile-time + option are as follows:</p> + +<p> <table cellpadding="2" border="1"> + <tr><th>SQLITE_TEMP_STORE</th><th>Meaning</th></tr> + <tr><td align="center">0</td><td>Always use temporary files</td></tr> + <tr><td align="center">1</td><td>Use files by default but allow the + <a href="pragma.html#pragma_temp_store">PRAGMA temp_store</a> command to override</td></tr> + <tr><td align="center">2</td><td>Use memory by default but allow the + <a href="pragma.html#pragma_temp_store">PRAGMA temp_store</a> command to override</td></tr> + <tr><td align="center">3</td><td>Always use memory</td></tr> + </table></p> + +<p> The default setting is 1. + Additional information can be found in <a href="tempfiles.html#tempstore">tempfiles.html</a>. +</p></blockquote><a name="trace_size_limit"></a> +<p><b>SQLITE_TRACE_SIZE_LIMIT=<i>N</i></b></p><blockquote><p> + If this macro is defined to a positive integer <i>N</i>, then the length of + strings and BLOB that are expanded into parameters in the output of + <a href="c3ref/profile.html">sqlite3_trace()</a> is limited to <i>N</i> bytes. +</p></blockquote><a name="trusted_schema"></a> +<p><b>SQLITE_TRUSTED_SCHEMA=<i><0 or 1></i></b></p><blockquote><p> + This macro determines the default value for the + <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. + If no alternative is specified, the trusted-schema setting defaults + to ON (a value of 1) for legacy compatibility. However, for best + security, systems that implement + <a href="appfunc.html">application-defined SQL functions</a> and/or <a href="vtab.html">virtual tables</a> should + consider changing the default to OFF. +</p></blockquote><a name="use_uri"></a> +<p><b>SQLITE_USE_URI</b></p><blockquote><p> + This option causes the <a href="uri.html">URI filename</a> process logic to be enabled by + default. +</p></blockquote> + +<a name="enablefeatures"></a> +<h1 id="_options_to_enable_features_normally_turned_off"><span>7. </span> Options To Enable Features Normally Turned Off</h1> + +<a name="allow_uri_authority"></a> +<p><b>SQLITE_ALLOW_URI_AUTHORITY</b></p><blockquote><p> + <a href="uri.html">URI filenames</a> normally throws an error if the authority section is + not either empty or "localhost". However, if SQLite is compiled with + the SQLITE_ALLOW_URI_AUTHORITY compile-time option, then the URI is + converted into a Uniform Naming Convention (UNC) filename and passed + down to the underlying operating system that way. + <p> + Some future versions of SQLite may change to enable this feature + by default. +</p></blockquote><a name="allow_covering_index_scan"></a> +<p><b>SQLITE_ALLOW_COVERING_INDEX_SCAN=<i><0 or 1></i></b></p><blockquote><p> + This C-preprocess macro determines the default setting of the + <a href="c3ref/c_config_covering_index_scan.html#sqliteconfigcoveringindexscan">SQLITE_CONFIG_COVERING_INDEX_SCAN</a> configuration setting. It defaults + to 1 (on) which means that covering indices are used for full table + scans where possible, in order to reduce I/O and improve performance. + However, the use of a covering index for a full scan will cause results + to appear in a different order from legacy, which could cause some + (incorrectly-coded) legacy applications to break. Hence, the covering + index scan option can be disabled at compile-time on systems that what + to minimize their risk of exposing errors in legacy applications. +</p></blockquote><a name="enable_8_3_names"></a> +<p><b>SQLITE_ENABLE_8_3_NAMES=<i><1 or 2></i></b></p><blockquote><p> + If this C-preprocessor macro is defined, then extra code is + included that allows SQLite to function on a filesystem that + only support 8+3 filenames. If the value of this macro is 1, + then the default behavior is to continue to use long filenames and + to only use 8+3 filenames if the + database connection is opened using <a href="uri.html">URI filenames</a> with + the "<tt>8_3_names=1</tt>" query parameter. If the value of + this macro is 2, then the use of 8+3 filenames becomes the default + but may be disabled on using the <tt>8_3_names=0</tt> query parameter. +</p></blockquote><a name="enable_api_armor"></a> +<p><b>SQLITE_ENABLE_API_ARMOR</b></p><blockquote><p> + When defined, this C-preprocessor macro activates extra code that + attempts to detect misuse of the SQLite API, such as passing in NULL + pointers to required parameters or using objects after they have been + destroyed. When this option is enabled and an illegal API usage + is detected, the interface will typically return SQLITE_MISUSE. + <p> + The SQLITE_ENABLE_API_ARMOR option does not guarantee that all + illegal API usages will be detected. Even when + SQLITE_ENABLE_API_ARMOR is enabled, passing incorrect values + into the C-language APIs can cause a process crash due to segmentation + fault or null-pointer deference or other reasons. The + SQLITE_ENABLE_API_ARMOR compile-time option is intended as an aid + for application testing and debugging option. Applications + should not depend SQLITE_ENABLE_API_ARMOR for safety. + SQLITE_ENABLE_API_ARMORE is appropriate as a second line of + defense against application bugs, but it should not be the only + defense. If any SQLite interface returns SQLITE_MISUSE, that + indicates that the application is using SQLite contrary to + the spec and that the application contains a bug. The SQLITE_MISUSE + return provides the application with the opportunity to respond + gracefully to that bug, rather than simply crashing the process, + but nothing more. Applications should not make use of nor depend + upon SQLITE_MISUSE for routine processing. +</p></blockquote><a name="enable_atomic_write"></a> +<p><b>SQLITE_ENABLE_ATOMIC_WRITE</b></p><blockquote><p> + If this C-preprocessor macro is defined and if the + xDeviceCharacteristics method of <a href="c3ref/io_methods.html">sqlite3_io_methods</a> object for + a database file reports (via one of the <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC</a> bits) + that the filesystem supports atomic writes and if a transaction + involves a change to only a single page of the database file, + then the transaction commits with just a single write request of + a single page of the database and no rollback journal is created + or written. On filesystems that support atomic writes, this + optimization can result in significant speed improvements for + small updates. However, few filesystems support this capability + and the code paths that check for this capability slow down write + performance on systems that lack atomic write capability, so this + feature is disabled by default. +</p></blockquote><a name="enable_batch_atomic_write"></a> +<p><b>SQLITE_ENABLE_BATCH_ATOMIC_WRITE</b></p><blockquote><p> + This compile-time option enables SQLite to take advantage batch + atomic write capabilities in the underlying filesystem. As of + SQLite version 3.21.0 (2017-10-24) this is only supported on + <a href="https://en.wikipedia.org/wiki/F2FS">F2FS</a>. However, the interface + is implemented generically, using <a href="c3ref/file_control.html">sqlite3_file_control()</a> with + <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> + so the capability can be added to other filesystem times in the + future. When this option is enabled, SQLite automatically detects + that the underlying filesystem supports batch atomic writes, and + when it does so it avoids writing the <a href="lockingv3.html#rollback">rollback journal</a> for transaction + control. This can make transactions over twice as fast, while + simultaneously reducing wear on SSD storage devices. +<p> + Future versions of SQLite might enable the batch-atomic-write + capability by default, at which point this compile-time option + will become superfluous. +</p></blockquote><a name="enable_bytecode_vtab"></a> +<p><b>SQLITE_ENABLE_BYTECODE_VTAB</b></p><blockquote><p> + This option enables the <a href="bytecodevtab.html">bytecode and tables_used virtual tables</a>. +</p></blockquote><a name="enable_column_metadata"></a> +<p><b>SQLITE_ENABLE_COLUMN_METADATA</b></p><blockquote><p> + When this C-preprocessor macro is defined, SQLite includes some + additional APIs that provide convenient access to meta-data about + tables and queries. The APIs that are enabled by this option are:</p> + +<p> <ul> + <li> <a href="c3ref/column_database_name.html">sqlite3_column_database_name()</a> </li> + <li> <a href="c3ref/column_database_name.html">sqlite3_column_database_name16()</a> </li> + <li> <a href="c3ref/column_database_name.html">sqlite3_column_table_name()</a> </li> + <li> <a href="c3ref/column_database_name.html">sqlite3_column_table_name16()</a> </li> + <li> <a href="c3ref/column_database_name.html">sqlite3_column_origin_name()</a> </li> + <li> <a href="c3ref/column_database_name.html">sqlite3_column_origin_name16()</a> </li> + </ul> +</p></blockquote><a name="enable_dbpage_vtab"></a> +<p><b>SQLITE_ENABLE_DBPAGE_VTAB</b></p><blockquote><p> + This option enables the <a href="dbpage.html">SQLITE_DBPAGE virtual table</a>. +</p></blockquote><a name="enable_dbstat_vtab"></a> +<p><b>SQLITE_ENABLE_DBSTAT_VTAB</b></p><blockquote><p> + This option enables the <a href="dbstat.html">dbstat virtual table</a>. +</p></blockquote><a name="enable_deserialize"></a> +<p><b>SQLITE_ENABLE_DESERIALIZE</b></p><blockquote><p> + This option was formerly used to enable + the <a href="c3ref/serialize.html">sqlite3_serialize()</a> and <a href="c3ref/deserialize.html">sqlite3_deserialize()</a> + interfaces. However, as of SQLite 3.36.0 (2021-06-18) + those interfaces are enabled by default and a new + compile-time option <a href="compile.html#omit_deserialize">SQLITE_OMIT_DESERIALIZE</a> is added + to omit them. +</p></blockquote><a name="enable_explain_comments"></a> +<p><b>SQLITE_ENABLE_EXPLAIN_COMMENTS</b></p><blockquote><p> + This option adds extra logic to SQLite that inserts comment text into the + output of <a href="lang_explain.html">EXPLAIN</a>. These extra comments use extra memory, thus + making <a href="c3ref/stmt.html">prepared statements</a> larger and very slightly slower, and so they are + turned off by default and in most application. But some applications, such + as the <a href="cli.html">command-line shell</a> for SQLite, value clarity of EXPLAIN output + over raw performance and so this compile-time option is available to them. + The SQLITE_ENABLE_EXPLAIN_COMMENTS compile-time option is also enabled + automatically if <a href="compile.html#debug">SQLITE_DEBUG</a> is enabled. +</p></blockquote><a name="enable_fts3"></a> +<p><b>SQLITE_ENABLE_FTS3</b></p><blockquote><p> + When this option is defined in the <a href="amalgamation.html">amalgamation</a>, versions 3 and 4 + of the full-text search engine are added to the build automatically. +</p></blockquote><a name="enable_fts3_parenthesis"></a> +<p><b>SQLITE_ENABLE_FTS3_PARENTHESIS</b></p><blockquote><p> + This option modifies the query pattern parser in FTS3 such that it + supports operators AND and NOT (in addition to the usual OR and NEAR) + and also allows query expressions to contain nested parenthesis. +</p></blockquote><a name="enable_fts3_tokenizer"></a> +<p><b>SQLITE_ENABLE_FTS3_TOKENIZER</b></p><blockquote><p> + This option enables the two-argument version of the <a href="fts3.html#f3tknzr">fts3_tokenizer()</a> + interface. The second argument to fts3_tokenizer() is suppose to be a + pointer to a function (encoded as a BLOB) that implements an + application defined tokenizer. If hostile actors are able to run + the two-argument version of fts3_tokenizer() with an arbitrary second + argument, they could use crash or take control of the process. + <p> + Because of security concerns, the two-argument fts3_tokenizer() feature + was disabled beginning with <a href="releaselog/3_11_0.html">Version 3.11.0</a> (2016-02-15) + unless this compile-time option is used. + <a href="releaselog/3_12_0.html">Version 3.12.0</a> (2016-03-29) added the + <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 + that activates the two-argument version of <a href="fts3.html#f3tknzr">fts3_tokenizer()</a> + for a specific <a href="c3ref/sqlite3.html">database connection</a> at run-time. +</p></blockquote><a name="enable_fts4"></a> +<p><b>SQLITE_ENABLE_FTS4</b></p><blockquote><p> + When this option is defined in the <a href="amalgamation.html">amalgamation</a>, versions 3 and 4 + of the full-text search engine are added to the build automatically. +</p></blockquote><a name="enable_fts5"></a> +<p><b>SQLITE_ENABLE_FTS5</b></p><blockquote><p> + When this option is defined in the <a href="amalgamation.html">amalgamation</a>, versions 5 + of the full-text search engine (<a href="fts5.html">fts5</a>) is added to the build automatically. +</p></blockquote><a name="enable_geopoly"></a> +<p><b>SQLITE_ENABLE_GEOPOLY</b></p><blockquote><p> + When this option is defined in the <a href="amalgamation.html">amalgamation</a>, the <a href="geopoly.html">Geopoly extension</a> + is included in the build. +</p></blockquote><a name="enable_hidden_columns"></a> +<p><b>SQLITE_ENABLE_HIDDEN_COLUMNS</b></p><blockquote><p> + When this option is defined in the <a href="amalgamation.html">amalgamation</a>, + The <a href="vtab.html#hiddencol">hidden columns</a> feature is enabled for virtual tables. +</p></blockquote><a name="enable_icu"></a> +<p><b>SQLITE_ENABLE_ICU</b></p><blockquote><p> + This option causes the + <a href="https://icu.unicode.org">International Components for Unicode</a> + or "ICU" extension to SQLite to be added to the build. +</p></blockquote><a name="enable_iotrace"></a> +<p><b>SQLITE_ENABLE_IOTRACE</b></p><blockquote><p> + When both the SQLite core and the <a href="cli.html">Command Line Interface</a> (CLI) are both + compiled with this option, then the CLI provides an extra command + named ".iotrace" that provides a low-level log of I/O activity. + This option is experimental and may be discontinued in a future release. +</p></blockquote><a name="enable_math_functions"></a> +<p><b>SQLITE_ENABLE_MATH_FUNCTIONS</b></p><blockquote><p> + This macro enables the <a href="lang_mathfunc.html">built-in SQL math functions</a>. This option + is automatically added to the Makefile by the configure script on unix platforms, + unless the --disable-math option is used. + This option is also included on Windows builds using the + "Makefile.msc" makefile for nmake. +</p></blockquote><a name="enable_json1"></a> +<p><b>SQLITE_ENABLE_JSON1</b></p><blockquote><p> + This compile-time option is a no-op. Prior to SQLite version 3.38.0 + (2022-02-22), it was necessary to compile with this option in order + to include the <a href="json1.html">JSON SQL functions</a> in the build. However, beginning + with SQLite version 3.38.0, those functions are included by default. + Use the <a href="compile.html#omit_json">-DSQLITE_OMIT_JSON</a> option to omit them. +</p></blockquote><a name="enable_locking_style"></a> +<p><b>SQLITE_ENABLE_LOCKING_STYLE</b></p><blockquote><p> + This option enables additional logic in the OS interface layer for + Mac OS X. The additional logic attempts to determine the type of the + underlying filesystem and choose and alternative locking strategy + that works correctly for that filesystem type. Five locking strategies + are available:</p> + +<p> <ul> + <li> POSIX locking style. This is the default locking style and the + style used by other (non Mac OS X) Unixes. Locks are obtained and + released using the fcntl() system call.</p> + +<p> <li> AFP locking style. This locking style is used for network file + systems that use the AFP (Apple Filing Protocol) protocol. Locks + are obtained by calling the library function _AFPFSSetLock().</p> + +<p> <li> Flock locking style. This is used for file-systems that do not + support POSIX locking style. Locks are obtained and released using + the flock() system call.</p> + +<p> <li> Dot-file locking style. This locking style is used when neither + flock nor POSIX locking styles are supported by the file system. + Database locks are obtained by creating and entry in the file-system + at a well-known location relative to the database file (a "dot-file") + and relinquished by deleting the same file.</p> + +<p> <li> No locking style. If none of the above can be supported, this + locking style is used. No database locking mechanism is used. When + this system is used it is not safe for a single database to be + accessed by multiple clients. + </ul></p> + +<p> Additionally, five extra <a href="vfs.html">VFS</a> implementations are provided as well as the + default. By specifying one of the extra VFS implementations + when calling <a href="c3ref/open.html">sqlite3_open_v2()</a>, an application may bypass the file-system + detection logic and explicitly select one of the above locking styles. The + five extra <a href="vfs.html">VFS</a> implementations are called "unix-posix", "unix-afp", + "unix-flock", "unix-dotfile" and "unix-none". +</p></blockquote><a name="enable_memory_management"></a> +<p><b>SQLITE_ENABLE_MEMORY_MANAGEMENT</b></p><blockquote><p> + This option adds extra logic to SQLite that allows it to release unused + memory upon request. This option must be enabled in order for the + <a href="c3ref/release_memory.html">sqlite3_release_memory()</a> interface to work. If this compile-time + option is not used, the <a href="c3ref/release_memory.html">sqlite3_release_memory()</a> interface is a + no-op. +</p></blockquote><a name="enable_memsys3"></a> +<p><b>SQLITE_ENABLE_MEMSYS3</b></p><blockquote><p> + This option includes code in SQLite that implements an alternative + memory allocator. This alternative memory allocator is only engaged + 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 + supply a large chunk of memory from which all memory allocations are + taken. + The MEMSYS3 memory allocator uses a hybrid allocation algorithm + patterned after dlmalloc(). Only one of SQLITE_ENABLE_MEMSYS3 and + SQLITE_ENABLE_MEMSYS5 may be enabled at once. +</p></blockquote><a name="enable_memsys5"></a> +<p><b>SQLITE_ENABLE_MEMSYS5</b></p><blockquote><p> + This option includes code in SQLite that implements an alternative + memory allocator. This alternative memory allocator is only engaged + 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 + supply a large chunk of memory from which all memory allocations are + taken. + The MEMSYS5 module rounds all allocations up to the next power + of two and uses a first-fit, buddy-allocator algorithm + that provides strong guarantees against fragmentation and breakdown + subject to certain operating constraints. +</p></blockquote><a name="enable_normalize"></a> +<p><b>SQLITE_ENABLE_NORMALIZE</b></p><blockquote><p> + This option includes the <a href="c3ref/expanded_sql.html">sqlite3_normalized_sql()</a> API. +</p></blockquote><a name="enable_null_trim"></a> +<p><b>SQLITE_ENABLE_NULL_TRIM</b></p><blockquote><p> + This option enables an optimization that omits NULL columns at + the ends of rows, for a space savings on disk. + <p> + Databases generated with this option enabled are not readable + by SQLite version 3.1.6 (2005-03-17) and earlier. Also, + databases generated with this option enabled are prone to + triggering the + <a href="https://www.sqlite.org/src/info/e6e962d6b0f06f46e">e6e962d6b0f06f46</a> + bug in the <a href="c3ref/blob_reopen.html">sqlite3_blob_reopen()</a> interface. For those reasons, + this optimization is disabled by default. However, this optimization + may be enabled by default in a future release of SQLite. +</p></blockquote><a name="enable_offset_sql_func"></a> +<p><b>SQLITE_ENABLE_OFFSET_SQL_FUNC</b></p><blockquote><p> + This option enables support for the <a href="lang_corefunc.html#sqlite_offset">sqlite_offset(X)</a> SQL function. + <p> + The <a href="lang_corefunc.html#sqlite_offset">sqlite_offset(X)</a> SQL function requires a new interface on the + B-tree storage engine, a new opcode in the <a href="opcode.html">virtual machine</a> that + runs SQL statements, and a new conditional in a critical path of the + code generator. To avoid that overhead in applications that do not + need the utility of sqlite_offset(X), the function is disabled by + default. +</p></blockquote><a name="enable_preupdate_hook"></a> +<p><b>SQLITE_ENABLE_PREUPDATE_HOOK</b></p><blockquote><p> + This option enables + <a href="c3ref/preupdate_blobwrite.html">several new APIs</a> that provide callbacks + prior to any change to a <a href="rowidtable.html">rowid table</a>. The callbacks can be used + to record the state of the row before the change occurs. + <p>The action of the preupdate hook is similar to the + <a href="c3ref/update_hook.html">update hook</a> except that the callback is + invoked before the change, not afterwards, and the preupdate + hook interfaces are omitted unless this compile-time option is + used. + <p>The preupdate hook interfaces were originally added to + support the <a href="sessionintro.html">session</a> extension. +</p></blockquote><a name="enable_qpsg"></a> +<p><b>SQLITE_ENABLE_QPSG</b></p><blockquote><p> + This option causes the <a href="queryplanner-ng.html#qpstab">query planner stability guarantee</a> (QPSG) to + be on by default. Normally the QPSG is off and must be activated + at run-time using the <a href="c3ref/c_dbconfig_defensive.html#sqlitedbconfigenableqpsg">SQLITE_DBCONFIG_ENABLE_QPSG</a> option to the + <a href="c3ref/db_config.html">sqlite3_db_config()</a> interface. +</p></blockquote><a name="enable_rbu"></a> +<p><b>SQLITE_ENABLE_RBU</b></p><blockquote><p> + Enable the code the implements the <a href="rbu.html">RBU extension</a>. +</p></blockquote><a name="enable_rtree"></a> +<p><b>SQLITE_ENABLE_RTREE</b></p><blockquote><p> + This option causes SQLite to include support for the + <a href="rtree.html">R*Tree index extension</a>. +</p></blockquote><a name="enable_session"></a> +<p><b>SQLITE_ENABLE_SESSION</b></p><blockquote><p> + This option enables the <a href="sessionintro.html">session extension</a>. +</p></blockquote><a name="enable_snapshot"></a> +<p><b>SQLITE_ENABLE_SNAPSHOT</b></p><blockquote><p> + This option enables the code to support the <a href="c3ref/snapshot.html">sqlite3_snapshot</a> object + and its related interfaces: + <ul> + <li> <a href="c3ref/snapshot_get.html">sqlite3_snapshot_get()</a> (constructor) + <li> <a href="c3ref/snapshot_free.html">sqlite3_snapshot_free()</a> (destructor) + <li> <a href="c3ref/snapshot_open.html">sqlite3_snapshot_open()</a> + <li> <a href="c3ref/snapshot_cmp.html">sqlite3_snapshot_cmp()</a> + <li> <a href="c3ref/snapshot_recover.html">sqlite3_snapshot_recover()</a> + </ul> +</p></blockquote><a name="enable_sorter_references"></a> +<p><b>SQLITE_ENABLE_SORTER_REFERENCES</b></p><blockquote><p> + This option activates an optimization that reduces the memory required + by the sorter at the cost of doing additional B-tree lookups after + the sort has occurred. + <p> + The default sorting procedure is to gather all information that will + ultimately be output into a "record" and pass that complete record + to the sorter. But in some cases, for example if some of the output + columns consists of large BLOB values, the size of the each record + can be large, which means that the sorter has to either use more memory, + and/or write more content to temporary storage. + <p> + When SQLITE_ENABLE_SORTER_REFERENCES is enabled, the records passed to + the sorter often contain only a <a href="lang_createtable.html#rowid">ROWID</a> value. Such records are much + smaller. This means the sorter has much less "payload" to deal with and + can run faster. After sorting has occurred, the ROWID is used to look up + the output column values in the original table. That requires another + search into the table, and could potentially result in a slowdown. Or, + it might be a performance win, depending on how large the values are. + <p> + Even when the SQLITE_ENABLE_SORTER_REFERENCES compile-time option is on, + sorter references are still disabled by default. To use sorter references, + the application must set a sorter reference size threshold using the + <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. + <p> + Because the SQLite developers do not know whether the + SQLITE_ENABLE_SORTER_REFERENCES option will help or hurt performance, + it is disabled by default at this time (2018-05-04). It might be enabled + by default in some future release, depending on what is learned about its + impact on performance. +</p></blockquote><a name="enable_stmt_scanstatus"></a> +<p><b>SQLITE_ENABLE_STMT_SCANSTATUS</b></p><blockquote><p> + This option enables the <a href="c3ref/stmt_scanstatus.html">sqlite3_stmt_scanstatus()</a> and + <a href="c3ref/stmt_scanstatus.html">sqlite3_stmt_scanstatus_v2()</a> interfaces. Those + interfaces are normally omitted from the build + because they imposes a performance penalty, even on statements that + do not use the feature. +</p></blockquote><a name="enable_stmtvtab"></a> +<p><b>SQLITE_ENABLE_STMTVTAB</b></p><blockquote><p> + This compile-time option enables the <a href="stmt.html">SQLITE_STMT virtual table</a> logic. +</p></blockquote><a name="rtree_int_only"></a> +<p><b>SQLITE_RTREE_INT_ONLY</b></p><blockquote><p> + This compile-time option is deprecated and untested. +</p></blockquote><a name="enable_sqllog"></a> +<p><b>SQLITE_ENABLE_SQLLOG</b></p><blockquote><p> + This option enables extra code (especially the <a href="c3ref/c_config_covering_index_scan.html#sqliteconfigsqllog">SQLITE_CONFIG_SQLLOG</a> + option to <a href="c3ref/config.html">sqlite3_config()</a>) that can be used to create logs of all + SQLite processing performed by an application. These logs can be useful + in doing off-line analysis of the behavior of an application, and especially + for performance analysis. In order for the SQLITE_ENABLE_SQLLOG option to + be useful, some extra code is required. The + <a href="https://www.sqlite.org/src/doc/trunk/src/test_sqllog.c">"test_sqllog.c"</a> + source code + file in the SQLite source tree is a working example of the required extra + code. On unix and windows systems, a developer can append the text of the + "test_sqllog.c" source code file to the end of an "sqlite3.c" amalgamation, + recompile the application using the -DSQLITE_ENABLE_SQLLOG option, then + control logging using environment variables. See the header comment on + the "test_sqllog.c" source file for additional detail. +</p></blockquote><a name="enable_stat2"></a> +<p><b>SQLITE_ENABLE_STAT2</b></p><blockquote><p> + This option used to cause the <a href="lang_analyze.html">ANALYZE</a> command to collect + index histogram data in the <b>sqlite_stat2</b> table. But that + functionality was superseded by <a href="compile.html#enable_stat3">SQLITE_ENABLE_STAT3</a> as of + SQLite <a href="releaselog/3_7_9.html">version 3.7.9</a> (2011-11-01). + The SQLITE_ENABLE_STAT2 compile-time option + is now a no-op. +</p></blockquote><a name="enable_stat3"></a> +<p><b>SQLITE_ENABLE_STAT3</b></p><blockquote><p> + This option used to cause the <a href="lang_analyze.html">ANALYZE</a> command to collect + index histogram data in the <b>sqlite_stat3</b> table. But that + functionality was superseded by <a href="compile.html#enable_stat4">SQLITE_ENABLE_STAT4</a> as of + SQLite <a href="releaselog/3_8_1.html">version 3.8.1</a> (2013-10-17). + The SQLITE_ENABLE_STAT3 compile-time option + continued to be supported through <a href="releaselog/3_29_0.html">version 3.29.0</a> (2019-07-10) + but has now become a no-op. + <p> +</p></blockquote><a name="enable_stat4"></a> +<p><b>SQLITE_ENABLE_STAT4</b></p><blockquote><p> + This option adds additional logic to the <a href="lang_analyze.html">ANALYZE</a> command and to + the <a href="optoverview.html">query planner</a> that can help SQLite to chose a better query plan + under certain situations. The <a href="lang_analyze.html">ANALYZE</a> command is enhanced to collect + histogram data from all columns of every index and store that data + in the <a href="fileformat2.html#stat4tab">sqlite_stat4</a> table. The query planner will then use the + histogram data to help it make better index choices. The downside of + this compile-time option is that it violates the + <a href="queryplanner-ng.html#qpstab">query planner stability guarantee</a> making it more difficult to ensure + consistent performance in mass-produced applications. + <p> + SQLITE_ENABLE_STAT4 is an enhancement of <a href="compile.html#enable_stat3">SQLITE_ENABLE_STAT3</a>. STAT3 + only recorded histogram data for the left-most column of each index + whereas the STAT4 enhancement records histogram data from all columns + of each index. + The <a href="compile.html#enable_stat3">SQLITE_ENABLE_STAT3</a> compile-time option has become a no-op. +</p></blockquote><a name="enable_tree_explain"></a> +<p><b>SQLITE_ENABLE_TREE_EXPLAIN</b></p><blockquote><p> + This compile-time option is no longer used. +</p></blockquote><a name="enable_update_delete_limit"></a> +<p><b>SQLITE_ENABLE_UPDATE_DELETE_LIMIT</b></p><blockquote><p> + This option enables an optional ORDER BY and LIMIT clause on + <a href="lang_update.html">UPDATE</a> and <a href="lang_delete.html">DELETE</a> statements.</p> + +<p> <p>If this option is defined, then it must also be + defined when using the <a href="lemon.html">Lemon parser generator</a> tool to generate a parse.c + file. Because of this, this option may only be used when the library is built + from source, not from the <a href="amalgamation.html">amalgamation</a> or from the collection of + pre-packaged C files provided for non-Unix like platforms on the website. + </p> +</p></blockquote><a name="enable_unknown_sql_function"></a> +<p><b>SQLITE_ENABLE_UNKNOWN_SQL_FUNCTION</b></p><blockquote><p> + When the SQLITE_ENABLE_UNKNOWN_SQL_FUNCTION compile-time option is + activated, SQLite will suppress "unknown function" errors when running + an <a href="lang_explain.html">EXPLAIN</a> or <a href="eqp.html">EXPLAIN QUERY PLAN</a>. Instead of throwing an error, + SQLite will insert a substitute no-op function named "unknown()". + The substitution of "unknown()" in place of unrecognized functions + only occurs on <a href="lang_explain.html">EXPLAIN</a> and <a href="eqp.html">EXPLAIN QUERY PLAN</a>, not on ordinary + statements. + <p> + When used in the <a href="cli.html">command-line shell</a>, the + SQLITE_ENABLE_UNKNOWN_SQL_FUNCTION feature allows SQL text that contains + application-defined functions to be pasted into the shell for + analysis and debugging without having to create and load an + extension that implements the application-defined functions. +</p></blockquote><a name="enable_unlock_notify"></a> +<p><b>SQLITE_ENABLE_UNLOCK_NOTIFY</b></p><blockquote><p> + This option enables the <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify()</a> interface and + its associated functionality. See the documentation titled + <a href="unlock_notify.html">Using the SQLite Unlock Notification Feature</a> for additional + information. +</p></blockquote><a name="introspection_pragmas"></a> +<p><b>SQLITE_INTROSPECTION_PRAGMAS</b></p><blockquote><p> + This option is obsolete. It used to enable some extra + some extra PRAGMA statements such as + <a href="pragma.html#pragma_function_list">PRAGMA function_list</a>, <a href="pragma.html#pragma_module_list">PRAGMA module_list</a>, and + <a href="pragma.html#pragma_pragma_list">PRAGMA pragma_list</a>, but those pragmas are now all + enabled by default. See <a href="compile.html#omit_introspection_pragmas">SQLITE_OMIT_INTROSPECTION_PRAGMAS</a>. +</p></blockquote><a name="soundex"></a> +<p><b>SQLITE_SOUNDEX</b></p><blockquote><p> + This option enables the <a href="lang_corefunc.html#soundex">soundex() SQL function</a>. +</p></blockquote><a name="strict_subtype"></a> +<p><b>SQLITE_STRICT_SUBTYPE=1</b></p><blockquote><p> + This option causes <a href="appfunc.html">application-defined SQL functions</a> to raise an SQL + error if they invoke the <a href="c3ref/result_subtype.html">sqlite3_result_subtype()</a> interface but + where not registered with the <a href="c3ref/c_deterministic.html#sqliteresultsubtype">SQLITE_RESULT_SUBTYPE</a> property. + This recommended option helps to identify problems in the + implementation of application-defined SQL functions early in the + development cycle. +</p></blockquote><a name="use_alloca"></a> +<p><b>SQLITE_USE_ALLOCA</b></p><blockquote><p> + If this option is enabled, then the alloca() memory allocator will be + used in a few situations where it is appropriate. This results in a slightly + smaller and faster binary. The SQLITE_USE_ALLOCA compile-time only + works, of course, on systems that support alloca(). +</p></blockquote><a name="use_fcntl_trace"></a> +<p><b>SQLITE_USE_FCNTL_TRACE</b></p><blockquote><p> + This option causes SQLite to issue extra <a href="c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntltrace">SQLITE_FCNTL_TRACE</a> file controls + to provide supplementary information to the VFS. The "vfslog.c" extension + makes use of this to provide enhanced logs of VFS activity. +</p></blockquote><a name="use_seh"></a> +<p><b>SQLITE_USE_SEH</b></p><blockquote><p> + This option enabled Structured Exception Handling (SEH) on Windows builds. + SEH is a Windows-specific technique for catching exceptions raised while + accessing a memory-mapped file. SEH is used to intercept errors that might + occur while accessing the memory-mapped <a href="walformat.html#shm">shm file</a> that are part of + <a href="wal.html">WAL mode</a> processing. If the operating system raised errors while SQLite + is trying to access the shm file, this option causes those errors to be + caught and dealt with by SQLite, rather than aborting the whole process. + <p> + This option only works when compiling on Windows using MSVC. +</p></blockquote><a name="have_zlib"></a> +<p><b>SQLITE_HAVE_ZLIB</b></p><blockquote><p> + This option causes some extensions to link against the + <a href="https://zlib.net">zlib compression library</a>. + <p> + This option has no effect on the SQLite core. It is only used by extensions. + This is option is necessary for the compression and decompression + functions that are part of <a href="sqlar.html">SQL Archive</a> support in the + <a href="cli.html">command-line shell</a>. + <p> + When compiling with this option, it will normally + be necessary to add a linker option to include the zlib library in the + build. Normal this option is "-lz" but might be different on different + systems. + <p> + When building with MSVC on Windows systems, one can put the zlib source + code in the compat/zlib subdirectory of the source tree and then add + the USE_ZLIB=1 option to the nmake command to cause the Makefile.msc + to automatically build and use an appropriate zlib library implementation. +</p></blockquote><a name="yytrackmaxstackdepth"></a> +<p><b>YYTRACKMAXSTACKDEPTH</b></p><blockquote><p> + This option causes the LALR(1) parser stack depth to be tracked + 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>,...) + interface. SQLite's LALR(1) parser has a fixed stack depth + (determined at compile-time using the <a href="compile.html#yystackdepth">YYSTACKDEPTH</a> options). + This option can be used to help determine if an application is + getting close to exceeding the maximum LALR(1) stack depth. +</p></blockquote> + +<a name="disablefeatures"></a> +<h1 id="_options_to_disable_features_normally_turned_on"><span>8. </span> Options To Disable Features Normally Turned On</h1> + +<a name="disable_lfs"></a> +<p><b>SQLITE_DISABLE_LFS</b></p><blockquote><p> + If this C-preprocessor macro is defined, large file support + is disabled. +</p></blockquote><a name="disable_dirsync"></a> +<p><b>SQLITE_DISABLE_DIRSYNC</b></p><blockquote><p> + If this C-preprocessor macro is defined, directory syncs + are disabled. SQLite typically attempts to sync the parent + directory when a file is deleted to ensure the directory + entries are updated immediately on disk. +</p></blockquote><a name="disable_fts3_unicode"></a> +<p><b>SQLITE_DISABLE_FTS3_UNICODE</b></p><blockquote><p> + If this C-preprocessor macro is defined, the <a href="fts3.html#unicode61">unicode61</a> tokenizer + in <a href="fts3.html">FTS3</a> is omitted from the build and is unavailable to + applications. +</p></blockquote><a name="disable_fts4_deferred"></a> +<p><b>SQLITE_DISABLE_FTS4_DEFERRED</b></p><blockquote><p> + If this C-preprocessor macro disables the "deferred token" optimization + in <a href="fts3.html#fts4">FTS4</a>. The "deferred token" optimization avoids loading massive + posting lists for terms that are in most documents of the collection + and instead simply scans for those tokens in the document source. <a href="fts3.html#fts4">FTS4</a> + should get exactly the same answer both with and without this optimization. +</p></blockquote><a name="disable_intrinsic"></a> +<p><b>SQLITE_DISABLE_INTRINSIC</b></p><blockquote><p> + This option disables the use of compiler-specific built-in functions + such as __builtin_bswap32() and __builtin_add_overflow() in GCC and Clang, + or _byteswap_ulong() and _ReadWriteBarrier() with MSVC. +</p></blockquote><a name="disable_pagecache_overflow_stats"></a> +<p><b>SQLITE_DISABLE_PAGECACHE_OVERFLOW_STATS</b></p><blockquote><p> + This option disables the collection of the <a href="c3ref/status.html">sqlite3_status()</a> + <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> + statistics. Setting this option has been shown to increase performance in + high concurrency multi-threaded applications. +</p></blockquote> + +<a name="omitfeatures"></a> + +<h1 id="_options_to_omit_features"><span>9. </span> Options To Omit Features</h1> + +<p>The following options can be used to +<a href="footprint.html">reduce the size of the compiled library</a> +by omitting unused features. This is probably only useful +in embedded systems where space is especially tight, as even with all +features included the SQLite library is relatively small. Don't forget +to tell your compiler to optimize for binary size! (the -Os option if +using GCC). Telling your compiler to optimize for size usually has +a much larger impact on library footprint than employing any of these +compile-time options. You should also verify that +<a href="#debugoptions">debugging options</a> are disabled.</p> + +<p>The macros in this section do not require values. The following +compilation switches all have the same effect:<br> +-DSQLITE_OMIT_ALTERTABLE<br> +-DSQLITE_OMIT_ALTERTABLE=1<br> +-DSQLITE_OMIT_ALTERTABLE=0 +</p> + +<p>If any of these options are defined, then the same set of SQLITE_OMIT_* +options must also be defined when using the <a href="lemon.html">Lemon parser generator</a> +tool to generate the +parse.c file and when compiling the 'mkkeywordhash' tool which generates +the keywordhash.h file. +Because of this, these options may only be used when the library is built +from canonical source, not from the <a href="amalgamation.html">amalgamation</a>. +Some SQLITE_OMIT_* options might work, or appear to work, when used with +the <a href="amalgamation.html">amalgamation</a>. But this is not guaranteed. In general, always compile +from canonical sources in order to take advantage of SQLITE_OMIT_* options. +</p> + +<blockquote> +<i><b>Important Note:</b> The SQLITE_OMIT_* options may not work with the +<a href="amalgamation.html">amalgamation</a>. SQLITE_OMIT_* compile-time +options usually work correctly only when SQLite is built from canonical +source files. +</i> +</blockquote> + + +<p>Special versions of the SQLite amalgamation that do work with a +predetermined set of SQLITE_OMIT_* options can be generated. To do so, +make a copy of the Makefile.linux-gcc makefile template in the canonical +source code distribution. Change the name of your copy to simply "Makefile". +Then edit "Makefile" to set up appropriate compile-time options. Then +type: +</p><div class="codeblock"><pre>make clean; make sqlite3.c +</pre></div> +<p>The resulting "sqlite3.c" amalgamation code file (and its associated +header file "sqlite3.h") can then be moved to a non-unix platform +for final compilation using a native compiler.</p> + +<p>The SQLITE_OMIT_* options are unsupported. By this we mean that +an SQLITE_OMIT_* option that omits code from the build in the current +release might become a no-op in the next release. Or the other way around: +an SQLITE_OMIT_* that is a no-op in the current release might cause code +to be excluded in the next release. Also, not all SQLITE_OMIT_* options +are tested. Some SQLITE_OMIT_* options might cause SQLite to malfunction +and/or provide incorrect answers. + +</p><blockquote> +<i><b>Important Note:</b> +The SQLITE_OMIT_* compile-time options are mostly unsupported. +</i></blockquote> + +<p>The following are the available OMIT options: + +<a name="omit_altertable"></a> +<p><b>SQLITE_OMIT_ALTERTABLE</b></p><blockquote><p> + When this option is defined, the + <a href="lang_altertable.html">ALTER TABLE</a> command is not included in the + library. Executing an <a href="lang_altertable.html">ALTER TABLE</a> statement causes a parse error. +</p></blockquote><a name="omit_analyze"></a> +<p><b>SQLITE_OMIT_ANALYZE</b></p><blockquote><p> + When this option is defined, the <a href="lang_analyze.html">ANALYZE</a> command is omitted from + the build. +</p></blockquote><a name="omit_attach"></a> +<p><b>SQLITE_OMIT_ATTACH</b></p><blockquote><p> + When this option is defined, the <a href="lang_attach.html">ATTACH</a> and <a href="lang_detach.html">DETACH</a> commands are + omitted from the build. +</p></blockquote><a name="omit_authorization"></a> +<p><b>SQLITE_OMIT_AUTHORIZATION</b></p><blockquote><p> + Defining this option omits the authorization callback feature from the + library. The <a href="c3ref/set_authorizer.html">sqlite3_set_authorizer()</a> API function is not present + in the library. +</p></blockquote><a name="omit_autoincrement"></a> +<p><b>SQLITE_OMIT_AUTOINCREMENT</b></p><blockquote><p> + This option is omits the <a href="autoinc.html">AUTOINCREMENT</a> feature. + When this is macro is defined, columns declared as + "<a href="lang_createtable.html#rowid">INTEGER PRIMARY KEY</a> AUTOINCREMENT" + behave in the same way as columns declared as "<a href="lang_createtable.html#rowid">INTEGER PRIMARY KEY</a>" when a + NULL is inserted. The sqlite_sequence system table is neither created, nor + respected if it already exists. +</p></blockquote><a name="omit_autoinit"></a> +<p><b>SQLITE_OMIT_AUTOINIT</b></p><blockquote><p> + For backwards compatibility with older versions of SQLite that lack + the <a href="c3ref/initialize.html">sqlite3_initialize()</a> interface, the <a href="c3ref/initialize.html">sqlite3_initialize()</a> interface + is called automatically upon entry to certain key interfaces such as + <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>. + The overhead of invoking <a href="c3ref/initialize.html">sqlite3_initialize()</a> automatically in this + way may be omitted by building SQLite with the SQLITE_OMIT_AUTOINIT + C-preprocessor macro. When built using SQLITE_OMIT_AUTOINIT, SQLite + will not automatically initialize itself and the application is required + to invoke <a href="c3ref/initialize.html">sqlite3_initialize()</a> directly prior to beginning use of the + SQLite library. +</p></blockquote><a name="omit_automatic_index"></a> +<p><b>SQLITE_OMIT_AUTOMATIC_INDEX</b></p><blockquote><p> + This option is used to omit the + <a href="optoverview.html#autoindex">automatic indexing</a> functionality. + See also: <a href="compile.html#default_automatic_index">SQLITE_DEFAULT_AUTOMATIC_INDEX</a>. +</p></blockquote><a name="omit_autoreset"></a> +<p><b>SQLITE_OMIT_AUTORESET</b></p><blockquote><p> + By default, the <a href="c3ref/step.html">sqlite3_step()</a> interface will automatically invoke + <a href="c3ref/reset.html">sqlite3_reset()</a> to reset the <a href="c3ref/stmt.html">prepared statement</a> if necessary. This + compile-time option changes that behavior so that <a href="c3ref/step.html">sqlite3_step()</a> will + return <a href="rescode.html#misuse">SQLITE_MISUSE</a> if it called again after returning anything other + 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 + intervening call to <a href="c3ref/reset.html">sqlite3_reset()</a>.</p> + +<p> In SQLite <a href="releaselog/3_6_23_1.html">version 3.6.23.1</a> (2010-03-26) + and earlier, <a href="c3ref/step.html">sqlite3_step()</a> used to always + return <a href="rescode.html#misuse">SQLITE_MISUSE</a> if it was invoked again after returning anything + other than <a href="rescode.html#row">SQLITE_ROW</a> without an intervening call to <a href="c3ref/reset.html">sqlite3_reset()</a>. + This caused problems on some poorly written smartphone applications which + did not correctly handle the <a href="rescode.html#locked">SQLITE_LOCKED</a> and <a href="rescode.html#busy">SQLITE_BUSY</a> error + returns. Rather than fix the many defective smartphone applications, + the behavior of SQLite was changed in 3.6.23.2 to automatically reset + the prepared statement. But that changed caused issues in other + improperly implemented applications that were actually looking + for an <a href="rescode.html#misuse">SQLITE_MISUSE</a> return to terminate their query loops. (Anytime + an application gets an SQLITE_MISUSE error code from SQLite, that means the + application is misusing the SQLite interface and is thus incorrectly + implemented.) The SQLITE_OMIT_AUTORESET interface was added to SQLite + <a href="releaselog/3_7_5.html">version 3.7.5</a> (2011-02-01) in an effort to get all of the (broken) + applications to work again without having to actually fix the applications. +</p></blockquote><a name="omit_autovacuum"></a> +<p><b>SQLITE_OMIT_AUTOVACUUM</b></p><blockquote><p> + If this option is defined, the library cannot create or write to + databases that support <a href="pragma.html#pragma_auto_vacuum">auto_vacuum</a>. + Executing a <a href="pragma.html#pragma_auto_vacuum">PRAGMA auto_vacuum</a> statement is not an error + (since unknown PRAGMAs are silently ignored), but does not return a value + or modify the auto-vacuum flag in the database file. If a database that + supports auto-vacuum is opened by a library compiled with this option, it + is automatically opened in read-only mode. +</p></blockquote><a name="omit_between_optimization"></a> +<p><b>SQLITE_OMIT_BETWEEN_OPTIMIZATION</b></p><blockquote><p> + This option disables the use of indices with WHERE clause terms + that employ the BETWEEN operator. +</p></blockquote><a name="omit_blob_literal"></a> +<p><b>SQLITE_OMIT_BLOB_LITERAL</b></p><blockquote><p> + When this option is defined, it is not possible to specify a blob in + an SQL statement using the X'ABCD' syntax. +</p></blockquote><a name="omit_btreecount"></a> +<p><b>SQLITE_OMIT_BTREECOUNT</b></p><blockquote><p> + This option is no longer used for anything. It is a no-op. +</p></blockquote><a name="omit_builtin_test"></a> +<p><b>SQLITE_OMIT_BUILTIN_TEST</b></p><blockquote><p> + This compile-time option has been renamed to <a href="compile.html#untestable">SQLITE_UNTESTABLE</a>. +</p></blockquote><a name="omit_case_sensitive_like_pragma"></a> +<p><b>SQLITE_OMIT_CASE_SENSITIVE_LIKE_PRAGMA</b></p><blockquote><p> + This compile-time option disables the <a href="pragma.html#pragma_case_sensitive_like">PRAGMA case_sensitive_like</a> + command. +</p></blockquote><a name="omit_cast"></a> +<p><b>SQLITE_OMIT_CAST</b></p><blockquote><p> + This option causes SQLite to omit support for the CAST operator. +</p></blockquote><a name="omit_check"></a> +<p><b>SQLITE_OMIT_CHECK</b></p><blockquote><p> + This option causes SQLite to omit support for CHECK constraints. + The parser will still accept CHECK constraints in SQL statements, + they will just not be enforced. +</p></blockquote><a name="omit_compileoption_diags"></a> +<p><b>SQLITE_OMIT_COMPILEOPTION_DIAGS</b></p><blockquote><p> + This option is used to omit the compile-time option diagnostics available + in SQLite, including the <a href="c3ref/compileoption_get.html">sqlite3_compileoption_used()</a> and + <a href="c3ref/compileoption_get.html">sqlite3_compileoption_get()</a> C/C++ functions, the + <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, + and the <a href="pragma.html#pragma_compile_options">compile_options pragma</a>. +</p></blockquote><a name="omit_complete"></a> +<p><b>SQLITE_OMIT_COMPLETE</b></p><blockquote><p> + This option causes the <a href="c3ref/complete.html">sqlite3_complete()</a> and <a href="c3ref/complete.html">sqlite3_complete16()</a> + interfaces to be omitted. +</p></blockquote><a name="omit_compound_select"></a> +<p><b>SQLITE_OMIT_COMPOUND_SELECT</b></p><blockquote><p> + This option is used to omit the compound <a href="lang_select.html">SELECT</a> functionality. + <a href="lang_select.html">SELECT</a> statements that use the + UNION, UNION ALL, INTERSECT or EXCEPT compound SELECT operators will + cause a parse error.</p> + +<p> An <a href="lang_insert.html">INSERT</a> statement with multiple values in the VALUES clause is + implemented internally as a compound SELECT. Hence, this option also + disables the ability to insert more than a single row using an + INSERT INTO ... VALUES ... statement. +</p></blockquote><a name="omit_cte"></a> +<p><b>SQLITE_OMIT_CTE</b></p><blockquote><p> + This option causes support for <a href="lang_with.html">common table expressions</a> to be omitted. +</p></blockquote><a name="omit_datetime_funcs"></a> +<p><b>SQLITE_OMIT_DATETIME_FUNCS</b></p><blockquote><p> + If this option is defined, SQLite's built-in date and time manipulation + functions are omitted. Specifically, the SQL functions julianday(), date(), + time(), datetime() and strftime() are not available. The default column + values CURRENT_TIME, CURRENT_DATE and CURRENT_TIMESTAMP are still available. +</p></blockquote><a name="omit_decltype"></a> +<p><b>SQLITE_OMIT_DECLTYPE</b></p><blockquote><p> + This option causes SQLite to omit support for the + <a href="c3ref/column_decltype.html">sqlite3_column_decltype()</a> and <a href="c3ref/column_decltype.html">sqlite3_column_decltype16()</a> + interfaces. +</p></blockquote><a name="omit_deprecated"></a> +<p><b>SQLITE_OMIT_DEPRECATED</b></p><blockquote><p> + This option causes SQLite to omit support for interfaces + marked as deprecated. This includes + <a href="c3ref/aggregate_count.html">sqlite3_aggregate_count()</a>, + <a href="c3ref/aggregate_count.html">sqlite3_expired()</a>, + <a href="c3ref/aggregate_count.html">sqlite3_transfer_bindings()</a>, + <a href="c3ref/aggregate_count.html">sqlite3_global_recover()</a>, + <a href="c3ref/aggregate_count.html">sqlite3_thread_cleanup()</a> and + <a href="c3ref/aggregate_count.html">sqlite3_memory_alarm()</a> interfaces and + <a href="pragma.html#syntax">PRAGMA</a> statements <a href="pragma.html#pragma_count_changes">PRAGMA count_changes</a>, + <a href="pragma.html#pragma_data_store_directory">PRAGMA data_store_directory</a>, + <a href="pragma.html#pragma_default_cache_size">PRAGMA default_cache_size</a>, + <a href="pragma.html#pragma_empty_result_callbacks">PRAGMA empty_result_callbacks</a>, + <a href="pragma.html#pragma_full_column_names">PRAGMA full_column_names</a>, + <a href="pragma.html#pragma_short_column_names">PRAGMA short_column_names</a>, and + <a href="pragma.html#pragma_temp_store_directory">PRAGMA temp_store_directory</a>. +</p></blockquote><a name="omit_deserialize"></a> +<p><b>SQLITE_OMIT_DESERIALIZE</b></p><blockquote><p> + This option causes the + <a href="c3ref/serialize.html">sqlite3_serialize()</a> and <a href="c3ref/deserialize.html">sqlite3_deserialize()</a> + interfaces to be omitted from the build. +</p></blockquote><a name="omit_diskio"></a> +<p><b>SQLITE_OMIT_DISKIO</b></p><blockquote><p> + This option omits all support for writing to the disk and forces + databases to exist in memory only. This option has not been + maintained and probably does not work with newer versions of SQLite. +</p></blockquote><a name="omit_explain"></a> +<p><b>SQLITE_OMIT_EXPLAIN</b></p><blockquote><p> + Defining this option causes the <a href="lang_explain.html">EXPLAIN</a> command to be omitted from the + library. Attempting to execute an <a href="lang_explain.html">EXPLAIN</a> statement will cause a parse + error. +</p></blockquote><a name="omit_flag_pragmas"></a> +<p><b>SQLITE_OMIT_FLAG_PRAGMAS</b></p><blockquote><p> + This option omits support for a subset of <a href="pragma.html#syntax">PRAGMA</a> commands that + query and set boolean properties. +</p></blockquote><a name="omit_floating_point"></a> +<p><b>SQLITE_OMIT_FLOATING_POINT</b></p><blockquote><p> + This option is used to omit floating-point number support from the SQLite + library. When specified, specifying a floating point number as a literal + (i.e. "1.01") results in a parse error.</p> + +<p> <p>In the future, this option may also disable other floating point + functionality, for example the <a href="c3ref/result_blob.html">sqlite3_result_double()</a>, + <a href="c3ref/bind_blob.html">sqlite3_bind_double()</a>, <a href="c3ref/value_blob.html">sqlite3_value_double()</a> and + <a href="c3ref/column_blob.html">sqlite3_column_double()</a> API functions. + </p> +</p></blockquote><a name="omit_foreign_key"></a> +<p><b>SQLITE_OMIT_FOREIGN_KEY</b></p><blockquote><p> + If this option is defined, then <a href="foreignkeys.html">foreign key constraint</a> syntax is + not recognized. +</p></blockquote><a name="omit_generated_columns"></a> +<p><b>SQLITE_OMIT_GENERATED_COLUMNS</b></p><blockquote><p> + If this option is defined, then <a href="gencol.html">generated column</a> syntax is + not recognized. +</p></blockquote><a name="omit_get_table"></a> +<p><b>SQLITE_OMIT_GET_TABLE</b></p><blockquote><p> + This option causes support for <a href="c3ref/free_table.html">sqlite3_get_table()</a> and + <a href="c3ref/free_table.html">sqlite3_free_table()</a> to be omitted. +</p></blockquote><a name="omit_hex_integer"></a> +<p><b>SQLITE_OMIT_HEX_INTEGER</b></p><blockquote><p> + This option omits support for <a href="lang_expr.html#hexint">hexadecimal integer literals</a>. +</p></blockquote><a name="omit_incrblob"></a> +<p><b>SQLITE_OMIT_INCRBLOB</b></p><blockquote><p> + This option causes support for <a href="c3ref/blob.html">incremental BLOB I/O</a> + to be omitted. +</p></blockquote><a name="omit_integrity_check"></a> +<p><b>SQLITE_OMIT_INTEGRITY_CHECK</b></p><blockquote><p> + This option omits support for the <a href="pragma.html#pragma_integrity_check">integrity_check pragma</a>. +</p></blockquote><a name="omit_introspection_pragmas"></a> +<p><b>SQLITE_OMIT_INTROSPECTION_PRAGMAS</b></p><blockquote><p> + This option omits support for + <a href="pragma.html#pragma_function_list">PRAGMA function_list</a>, <a href="pragma.html#pragma_module_list">PRAGMA module_list</a>, and + <a href="pragma.html#pragma_pragma_list">PRAGMA pragma_list</a>. +</p></blockquote><a name="omit_json"></a> +<p><b>SQLITE_OMIT_JSON</b></p><blockquote><p> + This option omits the <a href="json1.html">JSON SQL functions</a> from the build. +</p></blockquote><a name="omit_like_optimization"></a> +<p><b>SQLITE_OMIT_LIKE_OPTIMIZATION</b></p><blockquote><p> + This option disables the ability of SQLite to use indices to help + resolve <a href="lang_expr.html#like">LIKE</a> and <a href="lang_expr.html#glob">GLOB</a> operators in a WHERE clause. +</p></blockquote><a name="omit_load_extension"></a> +<p><b>SQLITE_OMIT_LOAD_EXTENSION</b></p><blockquote><p> + This option omits the entire extension loading mechanism from + SQLite, including <a href="c3ref/enable_load_extension.html">sqlite3_enable_load_extension()</a> and + <a href="c3ref/load_extension.html">sqlite3_load_extension()</a> interfaces. +</p></blockquote><a name="omit_localtime"></a> +<p><b>SQLITE_OMIT_LOCALTIME</b></p><blockquote><p> + This option omits the "localtime" modifier from the date and time + functions. This option is sometimes useful when trying to compile + the date and time functions on a platform that does not support the + concept of local time. +</p></blockquote><a name="omit_lookaside"></a> +<p><b>SQLITE_OMIT_LOOKASIDE</b></p><blockquote><p> + This option omits the <a href="malloc.html#lookaside">lookaside memory allocator</a>. +</p></blockquote><a name="omit_memorydb"></a> +<p><b>SQLITE_OMIT_MEMORYDB</b></p><blockquote><p> + When this is defined, the library does not respect the special database + name ":memory:" (normally used to create an <a href="inmemorydb.html">in-memory database</a>). If + ":memory:" is passed to <a href="c3ref/open.html">sqlite3_open()</a>, <a href="c3ref/open.html">sqlite3_open16()</a>, or + <a href="c3ref/open.html">sqlite3_open_v2()</a>, a file with this name will be + opened or created. +</p></blockquote><a name="omit_or_optimization"></a> +<p><b>SQLITE_OMIT_OR_OPTIMIZATION</b></p><blockquote><p> + This option disables the ability of SQLite to use an index together + with terms of a WHERE clause connected by the OR operator. +</p></blockquote><a name="omit_pager_pragmas"></a> +<p><b>SQLITE_OMIT_PAGER_PRAGMAS</b></p><blockquote><p> + Defining this option omits pragmas related to the pager subsystem from + the build. +</p></blockquote><a name="omit_pragma"></a> +<p><b>SQLITE_OMIT_PRAGMA</b></p><blockquote><p> + This option is used to omit the <a href="pragma.html#syntax">PRAGMA</a> command + from the library. Note that it is useful to define the macros that omit + specific pragmas in addition to this, as they may also remove supporting code + in other sub-systems. This macro removes the <a href="pragma.html#syntax">PRAGMA</a> command only. +</p></blockquote><a name="omit_progress_callback"></a> +<p><b>SQLITE_OMIT_PROGRESS_CALLBACK</b></p><blockquote><p> + This option may be defined to omit the capability to issue "progress" + callbacks during long-running SQL statements. The + <a href="c3ref/progress_handler.html">sqlite3_progress_handler()</a> + API function is not present in the library. +</p></blockquote><a name="omit_quickbalance"></a> +<p><b>SQLITE_OMIT_QUICKBALANCE</b></p><blockquote><p> + This option omits an alternative, faster B-Tree balancing routine. + Using this option makes SQLite slightly smaller at the expense of + making it run slightly slower. +</p></blockquote><a name="omit_reindex"></a> +<p><b>SQLITE_OMIT_REINDEX</b></p><blockquote><p> + When this option is defined, the <a href="lang_reindex.html">REINDEX</a> + command is not included in the library. + Executing a <a href="lang_reindex.html">REINDEX</a> statement causes + a parse error. +</p></blockquote><a name="omit_schema_pragmas"></a> +<p><b>SQLITE_OMIT_SCHEMA_PRAGMAS</b></p><blockquote><p> + Defining this option omits pragmas for querying the database schema from + the build. +</p></blockquote><a name="omit_schema_version_pragmas"></a> +<p><b>SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS</b></p><blockquote><p> + Defining this option omits pragmas for querying and modifying the + database schema version and user version from the build. Specifically, the + <a href="pragma.html#pragma_schema_version">schema_version</a> and <a href="pragma.html#pragma_user_version">user_version</a> PRAGMAs are omitted. +</p></blockquote><a name="omit_shared_cache"></a> +<p><b>SQLITE_OMIT_SHARED_CACHE</b></p><blockquote><p> + This option builds SQLite without support for <a href="sharedcache.html">shared cache mode</a>. + The <a href="c3ref/enable_shared_cache.html">sqlite3_enable_shared_cache()</a> is omitted along with a fair + amount of logic within the B-Tree subsystem associated with shared + cache management.</p> + +<p> This compile-time option is recommended most applications as it + results in improved performance and reduced library footprint. +</p></blockquote><a name="omit_subquery"></a> +<p><b>SQLITE_OMIT_SUBQUERY</b></p><blockquote><p> + If defined, support for sub-selects and the IN() operator are omitted. +</p></blockquote><a name="omit_tcl_variable"></a> +<p><b>SQLITE_OMIT_TCL_VARIABLE</b></p><blockquote><p> + If this macro is defined, then the special "$<variable-name>" syntax + used to automatically bind SQL variables to TCL variables is omitted. +</p></blockquote><a name="omit_tempdb"></a> +<p><b>SQLITE_OMIT_TEMPDB</b></p><blockquote><p> + This option omits support for TEMP or TEMPORARY tables. +</p></blockquote><a name="omit_trace"></a> +<p><b>SQLITE_OMIT_TRACE</b></p><blockquote><p> + This option omits support for the <a href="c3ref/profile.html">sqlite3_profile()</a> and + <a href="c3ref/profile.html">sqlite3_trace()</a> interfaces and their associated logic. +</p></blockquote><a name="omit_trigger"></a> +<p><b>SQLITE_OMIT_TRIGGER</b></p><blockquote><p> + Defining this option omits support for TRIGGER objects. Neither the + <a href="lang_createtrigger.html">CREATE TRIGGER</a> or <a href="lang_droptrigger.html">DROP TRIGGER</a> + commands are available in this case, and attempting to execute + either will result in a parse error. + This option also disables enforcement of <a href="foreignkeys.html">foreign key constraints</a>, + since the code that implements triggers and which is omitted by this + option is also used to implement <a href="foreignkeys.html#fk_actions">foreign key actions</a>. +</p></blockquote><a name="omit_truncate_optimization"></a> +<p><b>SQLITE_OMIT_TRUNCATE_OPTIMIZATION</b></p><blockquote><p> + A default build of SQLite, if a <a href="lang_delete.html">DELETE</a> statement has no WHERE clause + and operates on a table with no triggers, an optimization occurs that + causes the DELETE to occur by dropping and recreating the table. + Dropping and recreating a table is usually much faster than deleting + the table content row by row. This is the "truncate optimization". +</p></blockquote><a name="omit_utf16"></a> +<p><b>SQLITE_OMIT_UTF16</b></p><blockquote><p> + This macro is used to omit support for UTF16 text encoding. When this is + defined all API functions that return or accept UTF16 encoded text are + unavailable. These functions can be identified by the fact that they end + with '16', for example <a href="c3ref/prepare.html">sqlite3_prepare16()</a>, <a href="c3ref/column_blob.html">sqlite3_column_text16()</a> and + <a href="c3ref/bind_blob.html">sqlite3_bind_text16()</a>. +</p></blockquote><a name="omit_vacuum"></a> +<p><b>SQLITE_OMIT_VACUUM</b></p><blockquote><p> + When this option is defined, the <a href="lang_vacuum.html">VACUUM</a> + command is not included in the library. + Executing a <a href="lang_vacuum.html">VACUUM</a> statement causes + a parse error. +</p></blockquote><a name="omit_view"></a> +<p><b>SQLITE_OMIT_VIEW</b></p><blockquote><p> + Defining this option omits support for VIEW objects. Neither the + <a href="lang_createview.html">CREATE VIEW</a> nor the <a href="lang_dropview.html">DROP VIEW</a> + commands are available in this case, and + attempting to execute either will result in a parse error.</p> + +<p> WARNING: If this macro is defined, it will not be possible to open a database + for which the schema contains VIEW objects. +</p></blockquote><a name="omit_virtualtable"></a> +<p><b>SQLITE_OMIT_VIRTUALTABLE</b></p><blockquote><p> + This option omits support for the <a href="c3ref/vtab.html">Virtual Table</a> + mechanism in SQLite. +</p></blockquote><a name="omit_wal"></a> +<p><b>SQLITE_OMIT_WAL</b></p><blockquote><p> + This option omits the "<a href="wal.html">write-ahead log</a>" (a.k.a. "<a href="wal.html">WAL</a>") capability. +</p></blockquote><a name="omit_windowfunc"></a> +<p><b>SQLITE_OMIT_WINDOWFUNC</b></p><blockquote><p> + This option omits <a href="windowfunctions.html">window functions</a> from the build. +</p></blockquote><a name="omit_wsd"></a> +<p><b>SQLITE_OMIT_WSD</b></p><blockquote><p> + This option builds a version of the SQLite library that contains no + Writable Static Data (WSD). WSD is global variables and/or static + variables. Some platforms do not support WSD, and this option is necessary + in order for SQLite to work those platforms.</p> + +<p> Unlike other OMIT options which make the SQLite library smaller, + this option actually increases the size of SQLite and makes it run + a little slower. Only use this option if SQLite is being built for an + embedded target that does not support WSD. +</p></blockquote><a name="omit_xfer_opt"></a> +<p><b>SQLITE_OMIT_XFER_OPT</b></p><blockquote><p> + This option omits support for optimizations that help statements + of the form "INSERT INTO ... SELECT ..." run faster. +</p></blockquote><a name="untestable"></a> +<p><b>SQLITE_UNTESTABLE</b></p><blockquote><p> + A standard SQLite build includes a small amount of logic associated + with <a href="c3ref/test_control.html">sqlite3_test_control()</a> to exercise + parts of the SQLite core that are otherwise difficult to validate. + This compile-time option omits that extra testing logic. This + compile-time option was called "SQLITE_OMIT_BUILTIN_TEST" prior + to SQLite version 3.16.0 (2017-01-02). The name was changed + to better describe the implications of using it. + <p> + Setting this compile-time option prevents SQLite from being fully + testable. Branch test coverage drops from 100% down to about 95%. + <p> + SQLite developers follow the NASA principle of + "fly what you test and test what you fly". This principle is violated + if this option is enabled for delivery but disabled for testing. + But if this option is enabled during testing, not all branches are + reachable. Therefore, the use of this compile-time option is discouraged. +</p></blockquote><a name="zero_malloc"></a> +<p><b>SQLITE_ZERO_MALLOC</b></p><blockquote><p> + This option omits both the <a href="malloc.html#defaultalloc">default memory allocator</a> and the + <a href="malloc.html#memdebug">debugging memory allocator</a> from the build and substitutes a stub + memory allocator that always fails. SQLite will not run with this + stub memory allocator since it will be unable to allocate memory. But + this stub can be replaced at start-time using + <a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_covering_index_scan.html#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a>,...) or + <a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_covering_index_scan.html#sqliteconfigheap">SQLITE_CONFIG_HEAP</a>,...). + So the net effect of this compile-time option is that it allows SQLite + to be compiled and linked against a system library that does not support + malloc(), free(), and/or realloc(). +</p></blockquote> +<a name="debugoptions"></a> +</p><h1 id="_analysis_and_debugging_options"><span>10. </span> Analysis and Debugging Options</h1> +<a name="debug"></a> +<p><b>SQLITE_DEBUG</b></p><blockquote><p> + The SQLite source code contains literally thousands of assert() statements + used to verify internal assumptions and subroutine preconditions and + postconditions. These assert() statements are normally turned off + (they generate no code) since turning them on makes SQLite run approximately + three times slower. But for testing and analysis, it is useful to turn + the assert() statements on. The SQLITE_DEBUG compile-time option does this. + <p>SQLITE_DEBUG also enables some other debugging features, such as + special <a href="pragma.html#syntax">PRAGMA</a> statements that turn on tracing and listing features + used for troubleshooting and analysis of the <a href="opcode.html">VDBE</a> and code generator. +</p></blockquote><a name="memdebug"></a> +<p><b>SQLITE_MEMDEBUG</b></p><blockquote><p> + The SQLITE_MEMDEBUG option causes an instrumented + <a href="malloc.html#memdebug">debugging memory allocator</a> + to be used as the default memory allocator within SQLite. The + instrumented memory allocator checks for misuse of dynamically allocated + memory. Examples of misuse include using memory after it is freed, + writing off the ends of a memory allocation, freeing memory not previously + obtained from the memory allocator, or failing to initialize newly + allocated memory. +</p></blockquote> +<a name="win32options"></a> +<h1 id="_windows_specific_options"><span>11. </span> Windows-Specific Options</h1> +<a name="win32_heap_create"></a> +<p><b>SQLITE_WIN32_HEAP_CREATE</b></p><blockquote><p> + This option forces the Win32 native memory allocator, when enabled, to + create a private heap to hold all memory allocations. +</p></blockquote><a name="win32_malloc_validate"></a> +<p><b>SQLITE_WIN32_MALLOC_VALIDATE</b></p><blockquote><p> + This option forces the Win32 native memory allocator, when enabled, to + make strategic calls into the HeapValidate() function if assert() is also + enabled. +</p></blockquote> +<a name="linkage"></a> +<h1 id="compiler_linkage_and_calling_convention_control"><span>12. </span>Compiler Linkage and Calling Convention Control</h1> + +<p>The following macros specify interface details +for certain kinds of SQLite builds. The Makefiles will normally +handle setting these macros automatically. Application developers should +not need to worry with these macros. The following documentation about these +macros is included for completeness.</p> + +<a name="api"></a> +<p><b>SQLITE_API</b></p><blockquote><p> + This macro identifies an externally visible interface for SQLite. + This macro is sometimes set to "extern". But the definition is + compiler-specific. +</p></blockquote><a name="apicall"></a> +<p><b>SQLITE_APICALL</b></p><blockquote><p> + This macro identifies the calling convention used by public interface + routines in SQLite which accept a fixed number of arguments. + This macro is normally defined to be nothing, + though on Windows builds it can sometimes be set to "__cdecl" or "__stdcall". + The "__cdecl" setting is the default, but "__stdcall" is used when SQLite + is intended to be compiled as a Windows system library. + <p> + A single function declaration should contain no more than one of + 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>. +</p></blockquote><a name="callback"></a> +<p><b>SQLITE_CALLBACK</b></p><blockquote><p> + This macro specifies the calling convention used with callback pointers + in SQLite. This macro is normally defined to be nothing, though on Windows + builds it can sometimes be set to "__cdecl" or "__stdcall". The + "__cdecl" setting is the default, but "__stdcall" is used when SQLite + is intended to be compiled as a Windows system library. +</p></blockquote><a name="cdecl"></a> +<p><b>SQLITE_CDECL</b></p><blockquote><p> + This macro specifies the calling convention used by varargs interface + routines in SQLite. This macro is normally defined to be nothing, + though on Windows builds it can sometimes be set to "__cdecl". This + macro is used on varargs routines and so cannot be set to "__stdcall" + since the __stdcall calling convention does not support varargs functions. + <p> + A single function declaration should contain no more than one of + 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>. +</p></blockquote><a name="extern"></a> +<p><b>SQLITE_EXTERN</b></p><blockquote><p> + This macro specifies linkage for public interface variables in SQLite. + It should normally be allowed to default to "extern". +</p></blockquote><a name="stdcall"></a> +<p><b>SQLITE_STDCALL</b></p><blockquote><p> + This macro is no longer used and is now deprecated. +</p></blockquote><a name="sysapi"></a> +<p><b>SQLITE_SYSAPI</b></p><blockquote><p> + This macro identifies the calling convention used by operating system + interfaces for the target platform for an SQLite build. + This macro is normally defined to be nothing, + though on Windows builds it can sometimes be set to "__stdcall". + <p> + A single function declaration should contain no more than one of + 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>. +</p></blockquote><a name="tclapi"></a> +<p><b>SQLITE_TCLAPI</b></p><blockquote><p> + This macro specifies the calling convention used by the + <a href="http://www.tcl.tk">TCL</a> library interface routines. + This macro is not used by the SQLite core, but only by the <a href="tclsqlite.html">TCL Interface</a> + and <a href="testing.html#tcl">TCL test suite</a>. + This macro is normally defined to be nothing, + though on Windows builds it can sometimes be set to "__cdecl". This + macro is used on TCL library interface routines which are always compiled + as __cdecl, even on platforms that prefer to use __stdcall, so this + macro should not be set to __stdcall unless the platform has a custom + TCL library build that supports __stdcall. + <p> + This macro may not be used in combination with any of <a href="compile.html#apicall">SQLITE_APICALL</a>, + <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>. +</p></blockquote> +<p align="center"><small><i>This page last modified on <a href="https://sqlite.org/docsrc/honeypot" id="mtimelink" data-href="https://sqlite.org/docsrc/finfo/pages/compile.in?m=1a49b43fd9">2024-01-09 20:59:08</a> UTC </small></i></p> + |