Small. Fast. Reliable.
Choose any three.
About Documentation Download License Support Purchase

1.0 Compilation Options For SQLite

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 omit SQLite features (resulting in a smaller compiled library size) or to change the default values of some parameters.

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.

1.1 Platform Configuration

_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_INTERFACE" type options generated by autoconf scripts.

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.

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.

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().

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.

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.

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.

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.

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().

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.

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.

1.2 Options To Set Default Parameter Values

SQLITE_DEFAULT_AUTOMATIC_INDEX=<0 or 1>

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.

See also: SQLITE_OMIT_AUTOMATIC_INDEX

SQLITE_DEFAULT_AUTOVACUUM=<0 or 1 or 2>

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.

SQLITE_DEFAULT_CACHE_SIZE=<N>

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.

SQLITE_DEFAULT_FILE_FORMAT=<1 or 4>

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.

SQLITE_DEFAULT_FILE_PERMISSIONS=N

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.

SQLITE_DEFAULT_FOREIGN_KEYS=<0 or 1>

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.

SQLITE_DEFAULT_MMAP_SIZE=N

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 N 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.

SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT=<bytes>

This option sets the size limit on rollback journal files in persistent journal mode and 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.

SQLITE_DEFAULT_LOCKING_MODE=<1 or 0>

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.

SQLITE_DEFAULT_MEMSTATUS=<1 or 0>

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).

SQLITE_DEFAULT_PAGE_SIZE=<bytes>

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.

SQLITE_DEFAULT_SYNCHRONOUS=<0-3>

This macro determines the default value of the PRAGMA synchronous setting. If not overridden at compile-time, the default setting is 2 (FULL).

SQLITE_DEFAULT_WAL_SYNCHRONOUS=<0-3>

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.

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.

SQLITE_DEFAULT_WAL_AUTOCHECKPOINT=<pages>

This macro sets the default page count for the WAL automatic checkpointing feature. If unspecified, the default page count is 1000.

SQLITE_DEFAULT_WORKER_THREADS=N

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.

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=3 instead.

SQLITE_FTS3_MAX_EXPR_DEPTH=N

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.

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.

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.

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.

This compile-time option affects the SQL LIKE operator only and has no impact on the sqlite3_strlike() C-language interface.

SQLITE_MAX_MMAP_SIZE=N

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.

SQLITE_MAX_SCHEMA_RETRY=N

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.

SQLITE_MAX_WORKER_THREADS=N

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.

SQLITE_MINIMUM_FILE_DESCRIPTOR=N

The unix VFS will never use a file descriptor less than N. The default value of N is 3.

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.

SQLITE_POWERSAFE_OVERWRITE=<0 or 1>

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.

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.

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.

SQLITE_SORTER_PMASZ=N

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.

SQLITE_STMTJRNL_SPILL=N

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.

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.

YYSTACKDEPTH=<max_depth>

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.

1.3 Options To Set Size Limits

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.

The compile-time options for setting upper bounds are documented separately. The following is a list of the available settings:

1.4 Options To Control Operating Characteristics

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().

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.

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.

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.

SQLITE_OS_OTHER=<0 or 1>

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 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.

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.

SQLITE_THREADSAFE=<0 or 1 or 2>

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:

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.

SQLITE_TEMP_STORE=<0 through 3>

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:

SQLITE_TEMP_STOREMeaning
0Always use temporary files
1Use files by default but allow the PRAGMA temp_store command to override
2Use memory by default but allow the PRAGMA temp_store command to override
3Always use memory

The default setting is 1. Additional information can be found in tempfiles.html.

SQLITE_TRACE_SIZE_LIMIT=N

If this macro is defined to a positive integer N, then the length of strings and BLOB that are expanded into parameters in the output of sqlite3_trace() is limited to N bytes.

SQLITE_USE_URI

This option causes the URI filename process logic to be enabled by default.

1.5 Options To Enable Features Normally Turned Off

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.

Some future versions of SQLite may change to enable this feature by default.

SQLITE_ALLOW_COVERING_INDEX_SCAN=<0 or 1>

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.

SQLITE_ENABLE_8_3_NAMES=<1 or 2>

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 "8_3_names=1" 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 8_3_names=0 query parameter. See

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.

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.

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:

SQLITE_ENABLE_DBSTAT_VTAB

This option enables the dbstat virtual table.

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.

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.

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.

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.

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.

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.

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.

SQLITE_ENABLE_ICU

This option causes the International Components for Unicode or "ICU" extension to SQLite to be added to the build.

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.

SQLITE_ENABLE_JSON1

When this option is defined in the amalgamation, the JSON SQL functions are added to the build automatically.

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:

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".

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.

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.

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.

SQLITE_ENABLE_RBU

Enable the code the implements the RBU extension.

SQLITE_ENABLE_RTREE

This option causes SQLite to include support for the R*Tree index extension.

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.

SQLITE_RTREE_INT_ONLY

If this option is used together with SQLITE_ENABLE_RTREE then the 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.

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 "test_sqllog.c" 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.

SQLITE_ENABLE_STAT2

This option used to cause the ANALYZE command to collect index histogram data in the sqlite_stat2 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.

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.

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.

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.

SQLITE_ENABLE_TREE_EXPLAIN

This compile-time option is no longer used.

SQLITE_ENABLE_UPDATE_DELETE_LIMIT

This option enables an optional ORDER BY and LIMIT clause on UPDATE and DELETE statements.

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.

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.

SQLITE_SOUNDEX

This option enables the soundex() SQL function.

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.

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.

1.6 Options To Disable Features Normally Turned On

SQLITE_DISABLE_LFS

If this C-preprocessor macro is defined, large file support is disabled.

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.

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.

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.

1.7 Options To Omit Features

The following options can be used to 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 debugging options are disabled.

The macros in this section do not require values. The following compilation switches all have the same effect:
-DSQLITE_OMIT_ALTERTABLE
-DSQLITE_OMIT_ALTERTABLE=1
-DSQLITE_OMIT_ALTERTABLE=0

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.

Important Note: 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.

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:

make clean; make sqlite3.c
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.

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.

Important Note: The SQLITE_OMIT_* compile-time options are unsupported.

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.

SQLITE_OMIT_ANALYZE

When this option is defined, the ANALYZE command is omitted from the build.

SQLITE_OMIT_ATTACH

When this option is defined, the ATTACH and DETACH commands are omitted from the build.

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.

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.

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.

SQLITE_OMIT_AUTOMATIC_INDEX

This option is used to omit the automatic indexing functionality. See also: SQLITE_DEFAULT_AUTOMATIC_INDEX.

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.

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.

SQLITE_OMIT_BETWEEN_OPTIMIZATION

This option disables the use of indices with WHERE clause terms that employ the BETWEEN operator.

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.

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.

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.

SQLITE_OMIT_CAST

This option causes SQLite to omit support for the CAST operator.

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.

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.

SQLITE_OMIT_COMPLETE

This option causes the sqlite3_complete() and sqlite3_complete16() interfaces to be omitted.

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.

SQLITE_OMIT_CTE

This option causes support for common table expressions to be omitted.

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.

SQLITE_OMIT_DECLTYPE

This option causes SQLite to omit support for the sqlite3_column_decltype() and sqlite3_column_decltype16() interfaces.

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.

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.

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.

SQLITE_OMIT_FLAG_PRAGMAS

This option omits support for a subset of PRAGMA commands that query and set boolean properties.

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.

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.

SQLITE_OMIT_FOREIGN_KEY

If this option is defined, then foreign key constraint syntax is not recognized.

SQLITE_OMIT_GET_TABLE

This option causes support for sqlite3_get_table() and sqlite3_free_table() to be omitted.

SQLITE_OMIT_INCRBLOB

This option causes support for incremental BLOB I/O to be omitted.

SQLITE_OMIT_INTEGRITY_CHECK

This option omits support for the integrity_check pragma.

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.

SQLITE_OMIT_LOAD_EXTENSION

This option omits the entire extension loading mechanism from SQLite, including sqlite3_enable_load_extension() and sqlite3_load_extension() interfaces.

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.

SQLITE_OMIT_LOOKASIDE

This option omits the lookaside memory allocator.

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.

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.

SQLITE_OMIT_PAGER_PRAGMAS

Defining this option omits pragmas related to the pager subsystem from the build.

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.

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.

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.

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.

SQLITE_OMIT_SCHEMA_PRAGMAS

Defining this option omits pragmas for querying the database schema from the build.

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.

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.

SQLITE_OMIT_SUBQUERY

If defined, support for sub-selects and the IN() operator are omitted.

SQLITE_OMIT_TCL_VARIABLE

If this macro is defined, then the special "$" syntax used to automatically bind SQL variables to TCL variables is omitted.

SQLITE_OMIT_TEMPDB

This option omits support for TEMP or TEMPORARY tables.

SQLITE_OMIT_TRACE

This option omits support for the sqlite3_profile() and sqlite3_trace() interfaces and their associated logic.

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.

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".

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().

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.

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.

SQLITE_OMIT_VIRTUALTABLE

This option omits support for the Virtual Table mechanism in SQLite.

SQLITE_OMIT_WAL

This option omits the "write-ahead log" (a.k.a. "WAL") capability.

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.

SQLITE_OMIT_XFER_OPT

This option omits support for optimizations that help statements of the form "INSERT INTO ... SELECT ..." run faster.

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().

1.8 Analysis and Debugging Options

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.

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.

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.

1.9 Windows-Specific Options

SQLITE_WIN32_HEAP_CREATE

This option forces the Win32 native memory allocator, when enabled, to create a private heap to hold all memory allocations.

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.