<title>Compilation Options For SQLite</title>
<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 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>
<a name="defaults"></a>
<h2>1.1 Options To Set Default Parameter Values</h2>
<tcl>
proc COMPILE_OPTION {name text} {
if {[regexp {SQLITE_([A-Z0-9_]+)} $name all label]} {
hd_fragment [string tolower $label]
hd_keywords $all
}
hd_puts <p><b>$name</b></p>
hd_resolve <blockquote>$text</blockquote>
}
COMPILE_OPTION {SQLITE_DEFAULT_AUTOVACUUM=<i><1 or 0></i>} {
This macro determines if SQLite creates databases with the
[auto_vacuum] flag set by default. The default value is 0
(do not create auto-vacuum databases). In any case the
compile-time default may be overridden by the
[PRAGMA auto_vacuum] command.
}
COMPILE_OPTION {SQLITE_DEFAULT_CACHE_SIZE=<i><pages></i>} {
This macro sets the default size of the page-cache for each attached
database, in pages. This can be overridden by the
[PRAGMA cache_size] comamnd. The default value is 2000.
}
COMPILE_OPTION {SQLITE_DEFAULT_PAGE_SIZE=<i><bytes></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 1024. The compile-time default may be overridden at
runtime by the [PRAGMA page_size] command.
}
COMPILE_OPTION {SQLITE_DEFAULT_TEMP_CACHE_SIZE=<i><pages></i>} {
This macro sets the default size of the page-cache for temporary files
created by SQLite to store intermediate results, in pages. It does
not affect the page-cache for the temp database, where tables created
using [CREATE TABLE | CREATE TEMP TABLE] are stored. The default value
is 500.
}
</tcl>
<h2>1.2 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 which 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_PAGE_SIZE] </li>
<li> [SQLITE_MAX_SQL_LENGTH] </li>
<li> [SQLITE_MAX_VARIABLE_NUMBER] </li>
</ul>
<a name="controlfeatures"></a>
<h2>1.3 Options To Control Operating Characteristics</h2>
<tcl>
COMPILE_OPTION {SQLITE_THREADSAFE=<i><0 or 1></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.
<p>The value of SQLITE_THREADSAFE can be determined at run-time
using the [sqlite3_threadsafe()] interface.</p>
<p>When SQLite has been compiled with SQLITE_THREADSAFE=1 then mutexing
can be disabled at run-time using the [sqlite3_config()] interface together
with the [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD], and
[SQLITE_CONFIG_SERIALIZED] verbs.</p>
}
</tcl>
<a name="enablefeatures"></a>
<h2>1.4 Options To Enable Features Normally Turned Off</h2>
<a name="omitfeatures"></a>
<h2>1.5 Options To Omit Features</h2>
<p>The following options are used to reduce the size of the compiled
library by omiting optional 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).</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_XXX
options must also be defined when using the 'lemon' tool to generate a parse.c
file. Because of this, these options may only used when the library is built
from source, not from the collection of pre-packaged C files provided for
non-UNIX like platforms on the website.
</p>
<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_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_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_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_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_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.
}
COMPILE_OPTION {SQLITE_OMIT_CONFLICT_CLAUSE} {
In the future, this option will be used to omit the
[ON CONFLICT] clause from the library.
}
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_DATETIME are still available.
}
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_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, FOREIGN KEY clauses in column declarations are
ignored.
}
COMPILE_OPTION {SQLITE_OMIT_INTEGRITY_CHECK} {
This option may be used to omit the
[integrity_check] PRAGMA.
}
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_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_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_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_TRIGGER} {
Defining this option omits support for VIEW 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.
<p>
WARNING: If this macro is defined, it will not be possible to open a database
for which the schema contains TRIGGER objects.
</p>
}
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.
<p>
WARNING: If this macro is defined, it will not be possible to open a database
for which the schema contains VIEW objects.
</p>
}
</tcl>