Artifact 6714d0828ad2ba32e8e5875596f0506590ccf3b5:

<title>Compilation Options For SQLite</title>
<tcl>hd_keywords {compile-time options}</tcl>
<h1>1.0 Compilation Options For SQLite</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 [relfootprint | smaller compiled library size]) 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>
<tcl>
proc COMPILE_OPTION {name text} {
if {[regexp {(SQLITE|HAVE)_([A-Z0-9_]+)} $name all prefix label]} {
hd_fragment [string tolower $label]
hd_keywords $all -D$all
}
if {[regexp {^YY([A-Z0-9_]+)} $name all label]} {
hd_fragment [string tolower $all]
hd_keywords $all
}
hd_puts <p><b>$name</b></p>
regsub -all "\n\\s*\n" $text "</p>\n\n<p>" text
hd_resolve <blockquote><p>$text</p></blockquote>
}
</tcl>
<a name="osconfig"></a>
<h2>1.1 Platform Configuration</h2>
<tcl>
COMPILE_OPTION {_HAVE_SQLITE_CONFIG_H} {
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.
}
COMPILE_OPTION {HAVE_FDATASYNC} {
If the HAVE_FDATASYNC compile-time option is true, then the default [VFS]
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.
}
COMPILE_OPTION {HAVE_GMTIME_R} {
If the HAVE_GMTIME_R option is true and if [SQLITE_OMIT_DATETIME_FUNCS] 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 [SQLITE_OMIT_DATETIME_FUNCS] is not defined or is false, then the
built-in [date and time functions] are used to implement the CURRENT_TIME,
CURRENT_DATE, and CURRENT_TIMESTAMP keywords and neither gmtime_r() nor
gmtime() is ever called.
}
COMPILE_OPTION {HAVE_ISNAN} {
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().
}
COMPILE_OPTION {HAVE_LOCALTIME_R} {
If the HAVE_LOCALTIME_R option is true, then SQLite uses the threadsafe
localtime_r() library routine instead of localtime()
to help implement the [localtime modifier]
to the built-in [date and time functions].
}
COMPILE_OPTION {HAVE_LOCALTIME_S} {
If the HAVE_LOCALTIME_S option is true, then SQLite uses the threadsafe
localtime_s() library routine instead of localtime()
to help implement the [localtime modifier]
to the built-in [date and time functions].
}
COMPILE_OPTION {HAVE_MALLOC_USABLE_SIZE} {
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
[SQLITE_CONFIG_MALLOC] 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.
}
COMPILE_OPTION {HAVE_STRCHRNUL} {
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().
}
COMPILE_OPTION {HAVE_USLEEP} {
If the HAVE_USLEEP option is true, then the default unix VFS uses the
usleep() system call to implement the xSleep method. If this option is
undefined or false, then xSleep on unix is implemented using sleep() which
means that [sqlite3_sleep()] will have a minimum wait interval of 1000
milliseconds regardless of its argument.
}
COMPILE_OPTION {HAVE_UTIME} {
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.
}
</tcl>
<a name="defaults"></a>
<h2>1.2 Options To Set Default Parameter Values</h2>
<tcl>
COMPILE_OPTION {SQLITE_DEFAULT_AUTOMATIC_INDEX=<i>&lt;0 or 1&gt;</i>} {
This macro determines the initial setting for [PRAGMA automatic_index]
for newly opened [database connections].
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: [SQLITE_OMIT_AUTOMATIC_INDEX]
}
COMPILE_OPTION {SQLITE_DEFAULT_AUTOVACUUM=<i>&lt;0 or 1 or 2&gt;</i>} {
This macro determines if SQLite creates databases with the
[auto_vacuum] 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
[PRAGMA auto_vacuum] command.
}
COMPILE_OPTION {SQLITE_DEFAULT_CACHE_SIZE=<i>&lt;N&gt;</i>} {
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
[PRAGMA cache_size] command. The default value is -2000, which translates
into a maximum of 2048000 bytes per cache.
}
COMPILE_OPTION {SQLITE_DEFAULT_FILE_FORMAT=<i>&lt;1 or 4&gt;</i>} {
The default [schema format number] 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 [descending indices] and has a tighter encoding for
boolean values.
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 version 3.7.10, the default
schema format is 4.
The schema format number for a new database can be set at runtime using
the [PRAGMA legacy_file_format] command.
}
COMPILE_OPTION {SQLITE_DEFAULT_FILE_PERMISSIONS=<i>N</i>} {
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.
}
COMPILE_OPTION {SQLITE_DEFAULT_FOREIGN_KEYS=<i>&lt;0 or 1&gt;</i>} {
This macro determines whether enforcement of
[foreign key constraints] 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 [foreign_keys pragma]. 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.
}
COMPILE_OPTION {SQLITE_DEFAULT_MMAP_SIZE=<i>N</i>} {
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 [SQLITE_MAX_MMAP_SIZE] can be modified
at start-time using the
[sqlite3_config]([SQLITE_CONFIG_MMAP_SIZE]) call, or at run-time
using the [mmap_size pragma].
}
COMPILE_OPTION {SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT=<i>&lt;bytes&gt;</i>} {
This option sets the size limit on [rollback journal] files in
[journal_mode pragma | persistent journal mode] and
[locking_mode | exclusive locking mode] and on the size of the
write-ahead log file in [WAL mode]. 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 [journal_size_limit pragma].
}
COMPILE_OPTION {SQLITE_DEFAULT_LOCKING_MODE=<i>&lt;1 or 0&gt;</i>} {
If set to 1, then the default [locking_mode] is set to EXCLUSIVE.
If omitted or set to 0 then the default [locking_mode] is NORMAL.
}
COMPILE_OPTION {SQLITE_DEFAULT_MEMSTATUS=<i>&lt;1 or 0&gt;</i>} {
This macro is used to determine whether or not the features enabled and
disabled using the SQLITE_CONFIG_MEMSTATUS argument to [sqlite3_config()]
are available by default. The default value is 1 ([SQLITE_CONFIG_MEMSTATUS]
related features enabled).
}
COMPILE_OPTION {SQLITE_DEFAULT_PAGE_SIZE=<i>&lt;bytes&gt;</i>} {
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 [PRAGMA page_size] command.
}
COMPILE_OPTION {SQLITE_DEFAULT_SYNCHRONOUS=<i>&lt;0-3&gt;</i>} {
This macro determines the default value of the
[PRAGMA synchronous] setting. If not overridden at compile-time,
the default setting is 2 (FULL).
}
COMPILE_OPTION {SQLITE_DEFAULT_WAL_SYNCHRONOUS=<i>&lt;0-3&gt;</i>} {
This macro determines the default value of the
[PRAGMA synchronous] setting for database files that open in
[WAL mode]. If not overridden at compile-time, this value is the
same as [SQLITE_DEFAULT_SYNCHRONOUS].
<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 [PRAGMA synchronous] 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
[SQLITE_DEFAULT_SYNCHRONOUS] and so no automatic synchronous setting
changes will ever occur.
}
COMPILE_OPTION {SQLITE_DEFAULT_WAL_AUTOCHECKPOINT=<i>&lt;pages&gt;</i>} {
This macro sets the default page count for the [WAL]
[checkpointing | automatic checkpointing] feature. If unspecified,
the default page count is 1000.
}
COMPILE_OPTION {SQLITE_DEFAULT_WORKER_THREADS=<i>N</i>} {
This macro sets the default value for
the [SQLITE_LIMIT_WORKER_THREADS] parameter. The [SQLITE_LIMIT_WORKER_THREADS]
parameter sets the maximum number of auxiliary threads that a single
[prepared statement] will launch to assist it with a query. If not specified,
the default maximum is 0.
The value set here cannot be more than [SQLITE_MAX_WORKER_THREADS].
}
COMPILE_OPTION {SQLITE_EXTRA_DURABLE} {
The SQLITE_EXTRA_DURABLE compile-time option that used to cause the default
[PRAGMA synchronous] setting to be EXTRA, rather than FULL. This option
is no longer supported. Use
[SQLITE_DEFAULT_SYNCHRONOUS|SQLITE_DEFAULT_SYNCHRONOUS=3] instead.
}
COMPILE_OPTION {SQLITE_FTS3_MAX_EXPR_DEPTH=<i>N</i>} {
This macro sets the maximum depth of the search tree that corresponds to
the right-hand side of the MATCH operator in an [FTS3] or [FTS4] 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 [phrase queries] and [NEAR queries] 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.
}
COMPILE_OPTION {SQLITE_LIKE_DOESNT_MATCH_BLOBS} {
This compile-time option causes the [LIKE] operator to always return
False if either operand is a BLOB. The default behavior of [LIKE]
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 [LIKE] 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 [LIKE] processing logic
(see [https://www.sqlite.org/src/info/05f43be8fdda9f]) 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 [LIKE] operator only and has
no impact on the [sqlite3_strlike()] C-language interface.
}
COMPILE_OPTION {SQLITE_MAX_MMAP_SIZE=<i>N</i>} {
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 [SQLITE_DEFAULT_MMAP_SIZE] or
sqlite3_config([SQLITE_CONFIG_MMAP_SIZE]) or the
run-time memory-mapped I/O address space size (set by
sqlite3_file_control([SQLITE_FCNTL_MMAP_SIZE]) or
[PRAGMA mmap_size]) as long as those other settings are less than the
maximum value defined here.
}
COMPILE_OPTION {SQLITE_MAX_SCHEMA_RETRY=<i>N</i>} {
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.
}
COMPILE_OPTION {SQLITE_MAX_WORKER_THREADS=<i>N</i>} {
Set an upper bound on the [sqlite3_limit](db,[SQLITE_LIMIT_WORKER_THREADS],N)
setting that determines the maximum number of auxiliary threads that a single
[prepared statement] will use to aid with CPU-intensive computations
(mostly sorting). See also the [SQLITE_DEFAULT_WORKER_THREADS] options.
}
COMPILE_OPTION {SQLITE_MINIMUM_FILE_DESCRIPTOR=<i>N</i>} {
The unix [VFS] 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.
}
COMPILE_OPTION {SQLITE_POWERSAFE_OVERWRITE=<i>&lt;0 or 1&gt;</i>} {
This option changes the default assumption about [powersafe overwrite]
for the underlying filesystems for the unix and windows [VFSes].
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.
}
COMPILE_OPTION {SQLITE_REVERSE_UNORDERED_SELECTS} {
This option causes the [PRAGMA reverse_unordered_selects] setting to be
enabled by default. When enabled, [SELECT] 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.
}
COMPILE_OPTION {SQLITE_SORTER_PMASZ=<i>N</i>} {
If multi-threaded processing is enabled via the
[PRAGMA threads] setting, then sort operations will
attempt to start helper threads when the amount of content
to be sorted exceeds the minimum of the [cache_size] and PMA Size
determined by the [SQLITE_CONFIG_PMASZ] start-time option.
This compile-time option sets the default value for the
[SQLITE_CONFIG_PMASZ] start-time option.
The default value is 250.
}
COMPILE_OPTION {SQLITE_STMTJRNL_SPILL=<i>N</i>} {
The SQLITE_STMTJRNL_SPILL compile-time option determines the
default setting of the [SQLITE_CONFIG_STMTJRNL_SPILL] start-time
setting. That setting determines the size threshold above which
[statement journals] are moved from memory to disk.
}
COMPILE_OPTION {SQLITE_WIN32_MALLOC} {
This option enables the use of the Windows Heap API functions for memory
allocation instead of the standard library malloc() and free() routines.
}
COMPILE_OPTION {YYSTACKDEPTH=<i>&lt;max_depth&gt;</i>} {
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.
}
</tcl>
<h2>1.3 Options To Set Size Limits</h2>
<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 [database connections] using the
[sqlite3_limit()] interface.</p>
<p>The compile-time options for setting upper bounds are
[limits | documented separately]. The following is a list of
the available settings:</p>
<ul>
<li> [SQLITE_MAX_ATTACHED] </li>
<li> [SQLITE_MAX_COLUMN] </li>
<li> [SQLITE_MAX_COMPOUND_SELECT] </li>
<li> [SQLITE_MAX_EXPR_DEPTH] </li>
<li> [SQLITE_MAX_FUNCTION_ARG] </li>
<li> [SQLITE_MAX_LENGTH] </li>
<li> [SQLITE_MAX_LIKE_PATTERN_LENGTH] </li>
<li> [SQLITE_MAX_PAGE_COUNT] </li>
<li> [SQLITE_MAX_SQL_LENGTH] </li>
<li> [SQLITE_MAX_VARIABLE_NUMBER] </li>
</ul>
<a name="controlfeatures"></a>
<h2>1.4 Options To Control Operating Characteristics</h2>
<tcl>
COMPILE_OPTION {SQLITE_4_BYTE_ALIGNED_MALLOC} {
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().
}
COMPILE_OPTION {SQLITE_CASE_SENSITIVE_LIKE} {
If this option is present, then the built-in [LIKE] operator will be
case sensitive. This same effect can be achieved at run-time using
the [case_sensitive_like pragma].
}
COMPILE_OPTION {SQLITE_DIRECT_OVERFLOW_READ} {
When this option is present, content contained in
[overflow pages] of the database file is read directly from disk,
bypassing the [page cache], during read transactions. In applications
that do a lot of reads of large BLOBs, this option might improve read
performance.
}
COMPILE_OPTION {SQLITE_HAVE_ISNAN} {
If this option is present, then SQLite will use the isnan() function from
the system math library. This is an alias for the [HAVE_ISNAN] configuration
option.
}
COMPILE_OPTION {SQLITE_OS_OTHER=<i>&lt;0 or 1&gt;</i>} {
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
[sqlite3_vfs | operating system interface]. Applications must use
[sqlite3_vfs_register()] to register an appropriate interface before
using SQLite. Applications must also supply implementations for the
[sqlite3_os_init()] and [sqlite3_os_end()] interfaces. The usual practice
is for the supplied [sqlite3_os_init()] to invoke [sqlite3_vfs_register()].
SQLite will automatically invoke [sqlite3_os_init()] when it initializes.
This option is typically used when building SQLite for an embedded
platform with a custom operating system.
}
COMPILE_OPTION {SQLITE_SECURE_DELETE} {
This compile-time option changes the default setting of the
[secure_delete pragma]. When this option is not used, secure_delete defaults
to off. When this option is present, secure_delete defaults to on.
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
[secure_delete pragma] for additional information.
}
COMPILE_OPTION {SQLITE_THREADSAFE=<i>&lt;0 or 1 or 2&gt;</i>} {
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
[database connection] (or any [prepared statements] derived from
that database connection) at the same time.
To put it another way, SQLITE_THREADSAFE=1 sets the default
[threading mode] to Serialized. SQLITE_THREADSAFE=2 sets the default
[threading mode] to Multi-threaded. And SQLITE_THREADSAFE=0 sets the
[threading mode] to Single-threaded.
The value of SQLITE_THREADSAFE can be determined at run-time
using the [sqlite3_threadsafe()] interface.
When SQLite has been compiled with SQLITE_THREADSAFE=1 or
SQLITE_THREADSAFE=2 then the [threading mode]
can be altered at run-time using the [sqlite3_config()] interface together
with one of these verbs:
<ul>
<li>[SQLITE_CONFIG_SINGLETHREAD]
<li>[SQLITE_CONFIG_MULTITHREAD]
<li>[SQLITE_CONFIG_SERIALIZED]
</ul>
The [SQLITE_OPEN_NOMUTEX] and
[SQLITE_OPEN_FULLMUTEX] flags to [sqlite3_open_v2()] can also be used
to adjust the [threading mode] of individual [database connections]
at run-time.
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 [threading mode] at start-time or run-time.
See the [threading mode] documentation for additional information
on aspects of using SQLite in a multithreaded environment.
}
COMPILE_OPTION {SQLITE_TEMP_STORE=<i>&lt;0 through 3&gt;</i>} {
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:
<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
[PRAGMA temp_store] command to override</td></tr>
<tr><td align="center">2</td><td>Use memory by default but allow the
[PRAGMA temp_store] command to override</td></tr>
<tr><td align="center">3</td><td>Always use memory</td></tr>
</table>
The default setting is 1.
Additional information can be found in [tempstore | tempfiles.html].
}
COMPILE_OPTION {SQLITE_TRACE_SIZE_LIMIT=<i>N</i>} {
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
[sqlite3_trace()] is limited to <i>N</i> bytes.
}
COMPILE_OPTION {SQLITE_USE_URI} {
This option causes the [URI filename] process logic to be enabled by
default.
}
</tcl>
<a name="enablefeatures"></a>
<h2>1.5 Options To Enable Features Normally Turned Off</h2>
<tcl>
COMPILE_OPTION {SQLITE_ALLOW_URI_AUTHORITY} {
[URI filenames] 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.
}
COMPILE_OPTION {SQLITE_ALLOW_COVERING_INDEX_SCAN=<i>&lt;0 or 1&gt;</i>} {
This C-preprocess macro determines the default setting of the
[SQLITE_CONFIG_COVERING_INDEX_SCAN] 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.
}
COMPILE_OPTION {SQLITE_ENABLE_8_3_NAMES=<i>&lt;1 or 2&gt;</i>} {
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 [URI filenames] 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.
See
}
COMPILE_OPTION {SQLITE_ENABLE_API_ARMOR} {
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.
}
COMPILE_OPTION {SQLITE_ENABLE_ATOMIC_WRITE} {
If this C-preprocessor macro is defined and if the
xDeviceCharacteristics method of [sqlite3_io_methods] object for
a database file reports (via one of the [SQLITE_IOCAP_ATOMIC] 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.
}
COMPILE_OPTION {SQLITE_ENABLE_COLUMN_METADATA} {
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:
<ul>
<li> [sqlite3_column_database_name()] </li>
<li> [sqlite3_column_database_name16()] </li>
<li> [sqlite3_column_table_name()] </li>
<li> [sqlite3_column_table_name16()] </li>
<li> [sqlite3_column_origin_name()] </li>
<li> [sqlite3_column_origin_name16()] </li>
</ul>
}
COMPILE_OPTION {SQLITE_ENABLE_DBSTAT_VTAB} {
This option enables the [dbstat virtual table].
}
COMPILE_OPTION {SQLITE_ENABLE_EXPLAIN_COMMENTS} {
This option adds extra logic to SQLite that inserts comment text into the
output of [EXPLAIN]. These extra comments use extra memory, thus
making [prepared statements] larger and very slightly slower, and so they are
turned off by default and in most application. But some applications, such
as the [command-line shell] 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 [SQLITE_DEBUG] is enabled.
}
COMPILE_OPTION {SQLITE_ENABLE_FTS3} {
When this option is defined in the [amalgamation], version 3
of the full-text search engine is added to the build automatically.
}
COMPILE_OPTION {SQLITE_ENABLE_FTS3_PARENTHESIS} {
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.
}
COMPILE_OPTION {SQLITE_ENABLE_FTS3_TOKENIZER} {
This option enables the two-argument version of the [fts3_tokenizer()]
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 [Version 3.11.0] unless this compile-time
option is used.
[Version 3.12.0] added the
[sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER],1,0) interface
that activates the two-argument version of [fts3_tokenizer()]
for a specific [database connection] at run-time.
}
COMPILE_OPTION {SQLITE_ENABLE_FTS4} {
When this option is defined in the [amalgamation], versions 3 and 4
of the full-text search engine is added to the build automatically.
}
COMPILE_OPTION {SQLITE_ENABLE_FTS5} {
When this option is defined in the [amalgamation], versions 5
of the full-text search engine ([fts5]) is added to the build automatically.
}
COMPILE_OPTION {SQLITE_ENABLE_ICU} {
This option causes the
[http://www.icu-project.org/ | International Components for Unicode]
or "ICU" extension to SQLite to be added to the build.
}
COMPILE_OPTION {SQLITE_ENABLE_IOTRACE} {
When both the SQLite core and the [Command Line Interface] (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.
}
COMPILE_OPTION {SQLITE_ENABLE_JSON1} {
When this option is defined in the [amalgamation], the
[JSON SQL functions] are added to the build automatically.
}
COMPILE_OPTION {SQLITE_ENABLE_LOCKING_STYLE} {
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:
<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.
<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().
<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.
<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.
<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>
Additionally, five extra [VFS] implementations are provided as well as the
default. By specifying one of the extra VFS implementations
when calling [sqlite3_open_v2()], an application may bypass the file-system
detection logic and explicitly select one of the above locking styles. The
five extra [VFS] implementations are called "unix-posix", "unix-afp",
"unix-flock", "unix-dotfile" and "unix-none".
}
COMPILE_OPTION {SQLITE_ENABLE_MEMORY_MANAGEMENT} {
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
[sqlite3_release_memory()] interface to work. If this compile-time
option is not used, the [sqlite3_release_memory()] interface is a
no-op.
}
COMPILE_OPTION {SQLITE_ENABLE_MEMSYS3} {
This option includes code in SQLite that implements an alternative
memory allocator. This alternative memory allocator is only engaged
when the [SQLITE_CONFIG_HEAP] option to [sqlite3_config()] 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.
}
COMPILE_OPTION {SQLITE_ENABLE_MEMSYS5} {
This option includes code in SQLite that implements an alternative
memory allocator. This alternative memory allocator is only engaged
when the [SQLITE_CONFIG_HEAP] option to [sqlite3_config()] 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.
}
COMPILE_OPTION {SQLITE_ENABLE_PREUPDATE_HOOK} {
This option enables
[sqlite3_preupdate_hook|several new APIs] that provide callbacks
prior to any change to a [rowid table]. 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
[sqlite3_update_hook|update hook] 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 [session] extension.
}
COMPILE_OPTION {SQLITE_ENABLE_RBU} {
Enable the code the implements the [RBU extension].
}
COMPILE_OPTION {SQLITE_ENABLE_RTREE} {
This option causes SQLite to include support for the
[rtree | R*Tree index extension].
}
COMPILE_OPTION {SQLITE_ENABLE_SESSION} {
This option enables the [session extension].
}
COMPILE_OPTION {SQLITE_ENABLE_STMT_SCANSTATUS} {
This option enables the [sqlite3_stmt_scanstatus()] interface. The
[sqlite3_stmt_scanstatus()] interface is normally omitted from the build
because it imposes a small performance penalty, even on statements that
do not use the feature.
}
COMPILE_OPTION {SQLITE_RTREE_INT_ONLY} {
If this option is used together with [SQLITE_ENABLE_RTREE] then the
[rtree | R*Tree extension] will only store 32-bit signed integer
coordinates and all internal computations will be done using integers
instead of floating point numbers.
}
COMPILE_OPTION {SQLITE_ENABLE_SQLLOG} {
This option enables extra code (especially the [SQLITE_CONFIG_SQLLOG]
option to [sqlite3_config()]) 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="http://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.
}
COMPILE_OPTION {SQLITE_ENABLE_STAT2} {
This option used to cause the [ANALYZE] command to collect
index histogram data in the <b>sqlite_stat2</b> table. But that
functionality was superceded by [SQLITE_ENABLE_STAT3] as of
SQLite version 3.7.9. The SQLITE_ENABLE_STAT2 compile-time option
is now a no-op.
}
COMPILE_OPTION {SQLITE_ENABLE_STAT3} {
This option adds additional logic to the [ANALYZE] command and to
the [query planner] that can help SQLite to chose a better query plan
under certain situations. The [ANALYZE] command is enhanced to collect
histogram data from the left-most column of each index and store that data
in the [sqlite_stat3] table. The query planner will then use the
histogram data to help it make better index choices. Note, however,
that the use of histogram data in query planner violates the
[query planner stability guarantee] which is important to some applications.
<p>
}
COMPILE_OPTION {SQLITE_ENABLE_STAT4} {
This option adds additional logic to the [ANALYZE] command and to
the [query planner] that can help SQLite to chose a better query plan
under certain situations. The [ANALYZE] command is enhanced to collect
histogram data from all columns of every index and store that data
in the [sqlite_stat4] 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
[query planner stability guarantee] making it more difficult to ensure
consistent performance in mass-produced applications.
<p>
SQLITE_ENABLE_STAT4 is an enhancement of [SQLITE_ENABLE_STAT3]. 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 [SQLITE_ENABLE_STAT3] compile-time option is a no-op and is ignored
if the SQLITE_ENABLE_STAT4 compile-time option is used.
}
COMPILE_OPTION {SQLITE_ENABLE_TREE_EXPLAIN} {
This compile-time option is no longer used.
}
COMPILE_OPTION {SQLITE_ENABLE_UPDATE_DELETE_LIMIT} {
This option enables an optional ORDER BY and LIMIT clause on
[UPDATE] and [DELETE] statements.
<p>If this option is defined, then it must also be
defined when using the 'lemon' 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 [amalgamation] or from the collection of
pre-packaged C files provided for non-Unix like platforms on the website.
</p>
}
COMPILE_OPTION {SQLITE_ENABLE_UNLOCK_NOTIFY} {
This option enables the [sqlite3_unlock_notify()] interface and
its associated functionality. See the documentation titled
[Using the SQLite Unlock Notification Feature] for additional
information.
}
COMPILE_OPTION {SQLITE_SOUNDEX} {
This option enables the [soundex() SQL function].
}
COMPILE_OPTION {SQLITE_USE_FCNTL_TRACE} {
This option causes SQLite to issue extra [SQLITE_FCNTL_TRACE] file controls
to provide supplementary information to the VFS. The "vfslog.c" extension
makes use of this to provide enhanced logs of VFS activity.
}
COMPILE_OPTION {YYTRACKMAXSTACKDEPTH} {
This option causes the LALR(1) parser stack depth to be tracked
and reported using the [sqlite3_status]([SQLITE_STATUS_PARSER_STACK],...)
interface. SQLite's LALR(1) parser has a fixed stack depth
(determined at compile-time using the [YYSTACKDEPTH] options).
This option can be used to help determine if an application is
getting close to exceeding the maximum LALR(1) stack depth.
}
</tcl>
<a name="disablefeatures"></a>
<h2>1.6 Options To Disable Features Normally Turned On</h2>
<tcl>
COMPILE_OPTION {SQLITE_DISABLE_LFS} {
If this C-preprocessor macro is defined, large file support
is disabled.
}
COMPILE_OPTION {SQLITE_DISABLE_DIRSYNC} {
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.
}
COMPILE_OPTION {SQLITE_DISABLE_FTS3_UNICODE} {
If this C-preprocessor macro is defined, the [unicode61] tokenizer
in [FTS3] is omitted from the build and is unavailable to
applications.
}
COMPILE_OPTION {SQLITE_DISABLE_FTS4_DEFERRED} {
If this C-preprocessor macro disables the "deferred token" optimization
in [FTS4]. 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. [FTS4]
should get exactly the same answer both with and without this optimization.
}
</tcl>
<tcl>
hd_fragment "omitfeatures"
hd_keywords "omitfeatures"
</tcl>
<h2>1.7 Options To Omit Features</h2>
<p>The following options can be used to
[relfootprint | reduce the size of the compiled library]
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 'lemon' 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 [amalgamation].
Some SQLITE_OMIT_* options might work, or appear to work, when used with
the [amalgamation]. 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
[amalgamation]. 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:
<blockquote><tt>make clean; make sqlite3.c</tt></blockquote>
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.
<blockquote>
<i><b>Important Note:</b>
The SQLITE_OMIT_* compile-time options are unsupported.
</i></blockquote>
<tcl>
COMPILE_OPTION {SQLITE_OMIT_ALTERTABLE} {
When this option is defined, the
[ALTER TABLE] command is not included in the
library. Executing an [ALTER TABLE] statement causes a parse error.
}
COMPILE_OPTION {SQLITE_OMIT_ANALYZE} {
When this option is defined, the [ANALYZE] command is omitted from
the build.
}
COMPILE_OPTION {SQLITE_OMIT_ATTACH} {
When this option is defined, the [ATTACH] and [DETACH] commands are
omitted from the build.
}
COMPILE_OPTION {SQLITE_OMIT_AUTHORIZATION} {
Defining this option omits the authorization callback feature from the
library. The [sqlite3_set_authorizer()] API function is not present
in the library.
}
COMPILE_OPTION {SQLITE_OMIT_AUTOINCREMENT} {
This option is used to omit the
[AUTOINCREMENT] functionality. When this
is macro is defined, columns declared as
"[INTEGER PRIMARY KEY] AUTOINCREMENT"
behave in the same way as columns declared as "[INTEGER PRIMARY KEY]" when a
NULL is inserted. The sqlite_sequence system table is neither created, nor
respected if it already exists.
}
COMPILE_OPTION {SQLITE_OMIT_AUTOINIT} {
For backwards compatibility with older versions of SQLite that lack
the [sqlite3_initialize()] interface, the [sqlite3_initialize()] interface
is called automatically upon entry to certain key interfaces such as
[sqlite3_open()], [sqlite3_vfs_register()], and [sqlite3_mprintf()].
The overhead of invoking [sqlite3_initialize()] 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 [sqlite3_initialize()] directly prior to beginning use of the
SQLite library.
}
COMPILE_OPTION {SQLITE_OMIT_AUTOMATIC_INDEX} {
This option is used to omit the
[automatic indexing] functionality.
See also: [SQLITE_DEFAULT_AUTOMATIC_INDEX].
}
COMPILE_OPTION {SQLITE_OMIT_AUTORESET} {
By default, the [sqlite3_step()] interface will automatically invoke
[sqlite3_reset()] to reset the [prepared statement] if necessary. This
compile-time option changes that behavior so that [sqlite3_step()] will
return [SQLITE_MISUSE] if it called again after returning anything other
than [SQLITE_ROW], [SQLITE_BUSY], or [SQLITE_LOCKED] unless there was an
intervening call to [sqlite3_reset()].
In SQLite version 3.6.23.1 and earlier, [sqlite3_step()] used to always
return [SQLITE_MISUSE] if it was invoked again after returning anything
other than [SQLITE_ROW] without an intervening call to [sqlite3_reset()].
This caused problems on some poorly written smartphone applications which
did not correctly handle the [SQLITE_LOCKED] and [SQLITE_BUSY] 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 [SQLITE_MISUSE] 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
version 3.7.5 in an effort to get all of the (broken)
applications to work again without having to actually fix the applications.
}
COMPILE_OPTION {SQLITE_OMIT_AUTOVACUUM} {
If this option is defined, the library cannot create or write to
databases that support [auto_vacuum].
Executing a [PRAGMA auto_vacuum] 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.
}
COMPILE_OPTION {SQLITE_OMIT_BETWEEN_OPTIMIZATION} {
This option disables the use of indices with WHERE clause terms
that employ the BETWEEN operator.
}
COMPILE_OPTION {SQLITE_OMIT_BLOB_LITERAL} {
When this option is defined, it is not possible to specify a blob in
an SQL statement using the X'ABCD' syntax.
}
COMPILE_OPTION {SQLITE_OMIT_BTREECOUNT} {
When this option is defined, an optimization that accelerates counting
all entries in a table (in other words, an optimization that helps
"SELECT count(*) FROM table" run faster) is omitted.
}
COMPILE_OPTION {SQLITE_OMIT_BUILTIN_TEST} {
A standard SQLite build includes a small amount of logic controlled
by the [sqlite3_test_control()] interface that is used to exercise
parts of the SQLite core that are difficult to control and measure using
the standard API. This option omits that built-in test logic.
}
COMPILE_OPTION {SQLITE_OMIT_CAST} {
This option causes SQLite to omit support for the CAST operator.
}
COMPILE_OPTION {SQLITE_OMIT_CHECK} {
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.
}
COMPILE_OPTION {SQLITE_OMIT_COMPILEOPTION_DIAGS} {
This option is used to omit the compile-time option diagnostics available
in SQLite, including the [sqlite3_compileoption_used()] and
[sqlite3_compileoption_get()] C/C++ functions, the
[sqlite_compileoption_used()] and [sqlite_compileoption_get()] SQL functions,
and the [compile_options pragma].
}
COMPILE_OPTION {SQLITE_OMIT_COMPLETE} {
This option causes the [sqlite3_complete()] and [sqlite3_complete16()]
interfaces to be omitted.
}
COMPILE_OPTION {SQLITE_OMIT_COMPOUND_SELECT} {
This option is used to omit the compound [SELECT] functionality.
[SELECT] statements that use the
UNION, UNION ALL, INTERSECT or EXCEPT compound SELECT operators will
cause a parse error.
An [INSERT] 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.
}
COMPILE_OPTION {SQLITE_OMIT_CTE} {
This option causes support for [common table expressions] to be omitted.
}
COMPILE_OPTION {SQLITE_OMIT_DATETIME_FUNCS} {
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.
}
COMPILE_OPTION {SQLITE_OMIT_DECLTYPE} {
This option causes SQLite to omit support for the
[sqlite3_column_decltype()] and [sqlite3_column_decltype16()]
interfaces.
}
COMPILE_OPTION {SQLITE_OMIT_DEPRECATED} {
This option causes SQLite to omit support for interfaces
marked as deprecated. This includes
[sqlite3_aggregate_count()],
[sqlite3_expired()],
[sqlite3_transfer_bindings()],
[sqlite3_global_recover()],
[sqlite3_thread_cleanup()] and
[sqlite3_memory_alarm()] interfaces.
}
COMPILE_OPTION {SQLITE_OMIT_DISKIO} {
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.
}
COMPILE_OPTION {SQLITE_OMIT_EXPLAIN} {
Defining this option causes the [EXPLAIN] command to be omitted from the
library. Attempting to execute an [EXPLAIN] statement will cause a parse
error.
}
COMPILE_OPTION {SQLITE_OMIT_FLAG_PRAGMAS} {
This option omits support for a subset of [PRAGMA] commands that
query and set boolean properties.
}
COMPILE_OPTION {SQLITE_OMIT_FLOATING_POINT} {
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>In the future, this option may also disable other floating point
functionality, for example the [sqlite3_result_double()],
[sqlite3_bind_double()], [sqlite3_value_double()] and
[sqlite3_column_double()] API functions.
</p>
}
COMPILE_OPTION {SQLITE_OMIT_FOREIGN_KEY} {
If this option is defined, then [foreign key constraint] syntax is
not recognized.
}
COMPILE_OPTION {SQLITE_OMIT_GET_TABLE} {
This option causes support for [sqlite3_get_table()] and
[sqlite3_free_table()] to be omitted.
}
COMPILE_OPTION {SQLITE_OMIT_INCRBLOB} {
This option causes support for [sqlite3_blob | incremental BLOB I/O]
to be omitted.
}
COMPILE_OPTION {SQLITE_OMIT_INTEGRITY_CHECK} {
This option omits support for the [integrity_check pragma].
}
COMPILE_OPTION {SQLITE_OMIT_LIKE_OPTIMIZATION} {
This option disables the ability of SQLite to use indices to help
resolve [LIKE] and [GLOB] operators in a WHERE clause.
}
COMPILE_OPTION {SQLITE_OMIT_LOAD_EXTENSION} {
This option omits the entire extension loading mechanism from
SQLite, including [sqlite3_enable_load_extension()] and
[sqlite3_load_extension()] interfaces.
}
COMPILE_OPTION {SQLITE_OMIT_LOCALTIME} {
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.
}
COMPILE_OPTION {SQLITE_OMIT_LOOKASIDE} {
This option omits the [lookaside memory allocator].
}
COMPILE_OPTION {SQLITE_OMIT_MEMORYDB} {
When this is defined, the library does not respect the special database
name ":memory:" (normally used to create an [in-memory database]). If
":memory:" is passed to [sqlite3_open()], [sqlite3_open16()], or
[sqlite3_open_v2()], a file with this name will be
opened or created.
}
COMPILE_OPTION {SQLITE_OMIT_OR_OPTIMIZATION} {
This option disables the ability of SQLite to use an index together
with terms of a WHERE clause connected by the OR operator.
}
COMPILE_OPTION {SQLITE_OMIT_PAGER_PRAGMAS} {
Defining this option omits pragmas related to the pager subsystem from
the build.
}
COMPILE_OPTION {SQLITE_OMIT_PRAGMA} {
This option is used to omit the [PRAGMA] 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 [PRAGMA] command only.
}
COMPILE_OPTION {SQLITE_OMIT_PROGRESS_CALLBACK} {
This option may be defined to omit the capability to issue "progress"
callbacks during long-running SQL statements. The
[sqlite3_progress_handler()]
API function is not present in the library.
}
COMPILE_OPTION {SQLITE_OMIT_QUICKBALANCE} {
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.
}
COMPILE_OPTION {SQLITE_OMIT_REINDEX} {
When this option is defined, the [REINDEX]
command is not included in the library.
Executing a [REINDEX] statement causes
a parse error.
}
COMPILE_OPTION {SQLITE_OMIT_SCHEMA_PRAGMAS} {
Defining this option omits pragmas for querying the database schema from
the build.
}
COMPILE_OPTION {SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS} {
Defining this option omits pragmas for querying and modifying the
database schema version and user version from the build. Specifically, the
[schema_version] and [user_version] PRAGMAs are omitted.
}
COMPILE_OPTION {SQLITE_OMIT_SHARED_CACHE} {
This option builds SQLite without support for shared-cache mode.
The [sqlite3_enable_shared_cache()] is omitted along with a fair
amount of logic within the B-Tree subsystem associated with shared
cache management.
}
COMPILE_OPTION {SQLITE_OMIT_SUBQUERY} {
If defined, support for sub-selects and the IN() operator are omitted.
}
COMPILE_OPTION {SQLITE_OMIT_TCL_VARIABLE} {
If this macro is defined, then the special "$<variable-name>" syntax
used to automatically bind SQL variables to TCL variables is omitted.
}
COMPILE_OPTION {SQLITE_OMIT_TEMPDB} {
This option omits support for TEMP or TEMPORARY tables.
}
COMPILE_OPTION {SQLITE_OMIT_TRACE} {
This option omits support for the [sqlite3_profile()] and
[sqlite3_trace()] interfaces and their associated logic.
}
COMPILE_OPTION {SQLITE_OMIT_TRIGGER} {
Defining this option omits support for TRIGGER objects. Neither the
[CREATE TRIGGER] or [DROP TRIGGER]
commands are available in this case, and attempting to execute
either will result in a parse error.
This option also disables enforcement of [foreign key constraints],
since the code that implements triggers and which is omitted by this
option is also used to implement [foreign key actions].
}
COMPILE_OPTION {SQLITE_OMIT_TRUNCATE_OPTIMIZATION} {
A default build of SQLite, if a [DELETE] 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".
}
COMPILE_OPTION {SQLITE_OMIT_UTF16} {
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 [sqlite3_prepare16()], [sqlite3_column_text16()] and
[sqlite3_bind_text16()].
}
COMPILE_OPTION {SQLITE_OMIT_VACUUM} {
When this option is defined, the [VACUUM]
command is not included in the library.
Executing a [VACUUM] statement causes
a parse error.
}
COMPILE_OPTION {SQLITE_OMIT_VIEW} {
Defining this option omits support for VIEW objects. Neither the
[CREATE VIEW] nor the [DROP VIEW]
commands are available in this case, and
attempting to execute either will result in a parse error.
WARNING: If this macro is defined, it will not be possible to open a database
for which the schema contains VIEW objects.
}
COMPILE_OPTION {SQLITE_OMIT_VIRTUALTABLE} {
This option omits support for the [sqlite3_vtab | Virtual Table]
mechanism in SQLite.
}
COMPILE_OPTION {SQLITE_OMIT_WAL} {
This option omits the "[write-ahead log]" (a.k.a. "[WAL]") capability.
}
COMPILE_OPTION {SQLITE_OMIT_WSD} {
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.
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.
}
COMPILE_OPTION {SQLITE_OMIT_XFER_OPT} {
This option omits support for optimizations that help statements
of the form "INSERT INTO ... SELECT ..." run faster.
}
COMPILE_OPTION {SQLITE_ZERO_MALLOC} {
This option omits both the [default memory allocator] and the
[debugging memory allocator] 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
[sqlite3_config]([SQLITE_CONFIG_MALLOC],...) or
[sqlite3_config]([SQLITE_CONFIG_HEAP],...).
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().
}
</tcl>
<a name="debugoptions"></a>
<h2>1.8 Analysis and Debugging Options</h2>
<tcl>
COMPILE_OPTION {SQLITE_DEBUG} {
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 [PRAGMA] statements that turn on tracing and listing features
used for troubleshooting and analysis of the [VDBE] and code generator.
}
COMPILE_OPTION {SQLITE_MEMDEBUG} {
The SQLITE_MEMDEBUG option causes an instrumented
[debugging memory allocator]
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.
}
</tcl>
<a name="win32options"></a>
<h2>1.9 Windows-Specific Options</h2>
<tcl>
COMPILE_OPTION {SQLITE_WIN32_HEAP_CREATE} {
This option forces the Win32 native memory allocator, when enabled, to
create a private heap to hold all memory allocations.
}
COMPILE_OPTION {SQLITE_WIN32_MALLOC_VALIDATE} {
This option forces the Win32 native memory allocator, when enabled, to
make strategic calls into the HeapValidate() function if assert() is also
enabled.
}
</tcl>
<a name="linkage"></a>
<h2>1.10 Compiler Linkage Control</h2>
<p>The following macros specify
interface linkage 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 documention aboue these
macros is included completeness.</p>
<tcl>
COMPILE_OPTION {SQLITE_API} {
This macro identifies a externally visible interface for SQLite.
This macro is sometimes set to "extern". But the definition is
compiler-specific.
}
COMPILE_OPTION {SQLITE_APICALL} {
This macro identifies the calling convention used by public interface
routines 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>
A single function declaration should contain no more than one of
the following: [SQLITE_APICALL], [SQLITE_CALLBACK], [SQLITE_CDECL],
or [SQLITE_SYSCALL].
}
COMPILE_OPTION {SQLITE_CALLBACK} {
This macro specifies the calling convention used by 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>
A single function declaration should contain no more than one of
the following: [SQLITE_APICALL], [SQLITE_CALLBACK], [SQLITE_CDECL],
or [SQLITE_SYSCALL].
}
COMPILE_OPTION {SQLITE_CDECL} {
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: [SQLITE_APICALL], [SQLITE_CALLBACK], [SQLITE_CDECL],
or [SQLITE_SYSCALL].
}
COMPILE_OPTION {SQLITE_SYSCALL} {
This macro identifies the calling convention used by operating system
interfaces for target the 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: [SQLITE_APICALL], [SQLITE_CALLBACK], [SQLITE_CDECL],
or [SQLITE_SYSCALL].
}
COMPILE_OPTION {SQLITE_TCLAPI} {
This macro specifies the calling convention used by the
[http://www.tcl.tk | TCL] library interface routines.
This macro is not used by the SQLite core, but only by the [TCL Interface]
and [TCL test suite].
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 as a custom
TCL library build that supports __stdcall.
<p>
This macro may not be used in combination with any of [SQLITE_APICALL],
[SQLITE_CALLBACK], [SQLITE_CDECL], or [SQLITE_SYSCALL].
}
</tcl>

This page was generated in about
0.006s by
Fossil 2.8 [7b0dbe8079] 2019-02-20 22:28:24