Compile-time Options Small. Fast. Reliable. Choose any three. Home Menu About Documentation Download License Support Purchase Search About Documentation Download Support Purchase Search Documentation Search Changelog Compile-time Options Table Of Contents 1. Overview 2. Recommended Compile-time Options 3. Platform Configuration 4. Options To Set Default Parameter Values 5. Options To Set Size Limits 6. Options To Control Operating Characteristics 7. Options To Enable Features Normally Turned Off 8. Options To Disable Features Normally Turned On 9. Options To Omit Features 10. Analysis and Debugging Options 11. Windows-Specific Options 12. Compiler Linkage and Calling Convention Control 1. Overview 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. The compile_options pragma can be used to determine which of the options listed below were used in building a given copy of SQLite. 2. Recommended Compile-time Options The following compile-time options are recommended for applications that are able to use them, in order to minimized the number of CPU cycles and the bytes of memory used by SQLite. Not all of these compile-time options are usable by every application. For example, the SQLITE_THREADSAFE=0 option is only usable by applications that never access SQLite from more than one thread at a time. And the SQLITE_OMIT_PROGRESS_CALLBACK option is only usable by applications that do not use the sqlite3_progress_handler() interface. And so forth. It is impossible to test every possible combination of compile-time options for SQLite. But the following set of compile-time options is one configuration that is always fully tested. SQLITE_DQS=0. This setting disables the double-quoted string literal misfeature. SQLITE_THREADSAFE=0. Setting -DSQLITE_THREADSAFE=0 causes all of the mutex and thread-safety logic in SQLite to be omitted. This is the single compile-time option causes SQLite to run about 2% faster and also reduces the size of the library by about 2%. But the downside is that using the compile-time option means that SQLite can never be used by more than a single thread at a time, even if each thread has its own database connection. SQLITE_DEFAULT_MEMSTATUS=0. This setting causes the sqlite3_status() interfaces that track memory usage to be disabled. This helps the sqlite3_malloc() routines run much faster, and since SQLite uses sqlite3_malloc() internally, this helps to make the entire library faster. SQLITE_DEFAULT_WAL_SYNCHRONOUS=1. For maximum database safety following a power loss, the setting of PRAGMA synchronous=FULL is recommended. However, in WAL mode, complete database integrity is guaranteed with PRAGMA synchronous=NORMAL. With PRAGMA synchronous=NORMAL in WAL mode, recent changes to the database might be rolled back by a power loss, but the database will not be corrupted. Furthermore, transaction commit is much faster in WAL mode using synchronous=NORMAL than with the default synchronous=FULL. For these reasons, it is recommended that the synchronous setting be changed from FULL to NORMAL when switching to WAL mode. This compile-time option will accomplish that. SQLITE_LIKE_DOESNT_MATCH_BLOBS. Historically, SQLite has allowed BLOB operands to the LIKE and GLOB operators. But having a BLOB as an operand of LIKE or GLOB complicates and slows the LIKE optimization. When this option is set, it means that the LIKE and GLOB operators always return FALSE if either operand is a BLOB. That simplifies the implementation of the LIKE optimization and allows queries that use the LIKE optimization to run faster. SQLITE_MAX_EXPR_DEPTH=0. Setting the maximum expression parse-tree depth to zero disables all checking of the expression parse-tree depth, which simplifies the code resulting in faster execution, and helps the parse tree to use less memory. SQLITE_OMIT_DECLTYPE. By omitting the (seldom-needed) ability to return the declared type of columns from the result set of query, prepared statements can be made to consume less memory. SQLITE_OMIT_DEPRECATED. Omitting deprecated interfaces and features will not help SQLite to run any faster. It will reduce the library footprint, however. And it is the right thing to do. SQLITE_OMIT_PROGRESS_CALLBACK. The progress handler callback counter must be checked in the inner loop of the bytecode engine. By omitting this interface, a single conditional is removed from the inner loop of the bytecode engine, helping SQL statements to run slightly faster. SQLITE_OMIT_SHARED_CACHE. Omitting the possibility of using shared cache allows many conditionals in performance-critical sections of the code to be eliminated. This can give a noticeable improvement in performance. SQLITE_OMIT_AUTOINIT. The SQLite library needs to be initialized using a call to sqlite3_initialize() before certain interfaces are used. This initialization normally happens automatically the first time it is needed. However, with the SQLITE_OMIT_AUTOINIT option, the automatic initialization is omitted. This helps many API calls to run a little faster (since they do not have to check to see if initialization has already occurred and then run initialization if it has not previously been invoked) but it also means that the application must call sqlite3_initialize() manually. If SQLite is compiled with -DSQLITE_OMIT_AUTOINIT and a routine like sqlite3_malloc() or sqlite3_vfs_find() or sqlite3_open() is invoked without first calling sqlite3_initialize(), the likely result will be a segfault. SQLITE_STRICT_SUBTYPE=1. This option causes an error to be raised if an application defined function that does not have the SQLITE_RESULT_SUBTYPE property invokes the sqlite3_result_subtype() interface. The sqlite3_result_subtype() interface does not work reliably unless the function is registered with the SQLITE_RESULT_SUBTYPE property. This compile-time option is designed to bring this problem to the attention of developers early. When all of the recommended compile-time options above are used, the SQLite library will be approximately 3% smaller and use about 5% fewer CPU cycles. So these options do not make a huge difference. But in some design situations, every little bit helps. Library-level configuration options, such as those listed above, may optionally be defined in a client-side header file. Defining SQLITE_CUSTOM_INCLUDE=myconfig.h (with no quotes) will cause sqlite3.c to include myconfig.h early on in the compilation process, enabling the client to customize the flags without having to explicitly pass all of them to the compiler. 3. 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 "sqlite_cfg.h". The "sqlite_cfg.h" file usually contains other configuration options, especially "HAVE_INTERFACE" type options generated by the configure process. Note that this header is intended only for use for platform-level configuration, not library-level configuration. To set SQLite-level configuration flags in a custom header, define SQLITE_CUSTOM_INCLUDE=myconfig.h, as described in the previous section. 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 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_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. SQLITE_BYTEORDER=(0|1234|4321) SQLite needs to know if the native byte order of the target CPU is big-endian or little-endian. The SQLITE_BYTEORDER preprocessor is set to 4321 for big-endian machines and 1234 for little-endian machines, or it can be 0 to mean that the byte order must be determined at run-time. There are #ifdefs in the code that set SQLITE_BYTEORDER automatically for all common platforms and compilers. However, it may be advantageous to set SQLITE_BYTEORDER appropriately when compiling SQLite for obscure targets. If the target byte order cannot be determined at compile-time, then SQLite falls back to doing run-time checks, which always work, though with a small performance penalty. 4. 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 over…