Configuration Options

#define SQLITE_CONFIG_SINGLETHREAD  1  /* nil */
#define SQLITE_CONFIG_MULTITHREAD   2  /* nil */
#define SQLITE_CONFIG_SERIALIZED    3  /* nil */
#define SQLITE_CONFIG_MALLOC        4  /* sqlite3_mem_methods* */
#define SQLITE_CONFIG_GETMALLOC     5  /* sqlite3_mem_methods* */
#define SQLITE_CONFIG_SCRATCH       6  /* void*, int sz, int N */
#define SQLITE_CONFIG_PAGECACHE     7  /* void*, int sz, int N */
#define SQLITE_CONFIG_HEAP          8  /* void*, int nByte, int min */
#define SQLITE_CONFIG_MEMSTATUS     9  /* boolean */
#define SQLITE_CONFIG_MUTEX        10  /* sqlite3_mutex_methods* */
#define SQLITE_CONFIG_GETMUTEX     11  /* sqlite3_mutex_methods* */
/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ 
#define SQLITE_CONFIG_LOOKASIDE    13  /* int int */
#define SQLITE_CONFIG_PCACHE       14  /* sqlite3_pcache_methods* */
#define SQLITE_CONFIG_GETPCACHE    15  /* sqlite3_pcache_methods* */
#define SQLITE_CONFIG_LOG          16  /* xFunc, void* */

These constants are the available integer configuration options that can be passed as the first argument to the sqlite3_config() interface.

New configuration options may be added in future releases of SQLite. Existing configuration options might be discontinued. Applications should check the return code from sqlite3_config() to make sure that the call worked. The sqlite3_config() interface will return a non-zero error code if a discontinued or unsupported configuration option is invoked.

SQLITE_CONFIG_SINGLETHREAD

There are no arguments to this option. This option sets the threading mode to Single-thread. In other words, it disables all mutexing and puts SQLite into a mode where it can only be used by a single thread. If SQLite is compiled with the SQLITE_THREADSAFE=0 compile-time option then it is not possible to change the threading mode from its default value of Single-thread and so sqlite3_config() will return SQLITE_ERROR if called with the SQLITE_CONFIG_SINGLETHREAD configuration option.

SQLITE_CONFIG_MULTITHREAD

There are no arguments to this option. This option sets the threading mode to Multi-thread. In other words, it disables mutexing on database connection and prepared statement objects. The application is responsible for serializing access to database connections and prepared statements. But other mutexes are enabled so that SQLite will be safe to use in a multi-threaded environment as long as no two threads attempt to use the same database connection at the same time. If SQLite is compiled with the SQLITE_THREADSAFE=0 compile-time option then it is not possible to set the Multi-thread threading mode and sqlite3_config() will return SQLITE_ERROR if called with the SQLITE_CONFIG_MULTITHREAD configuration option.

SQLITE_CONFIG_SERIALIZED

There are no arguments to this option. This option sets the threading mode to Serialized. In other words, this option enables all mutexes including the recursive mutexes on database connection and prepared statement objects. In this mode (which is the default when SQLite is compiled with SQLITE_THREADSAFE=1) the SQLite library will itself serialize access to database connections and prepared statements so that the application is free to use the same database connection or the same prepared statement in different threads at the same time. If SQLite is compiled with the SQLITE_THREADSAFE=0 compile-time option then it is not possible to set the Serialized threading mode and sqlite3_config() will return SQLITE_ERROR if called with the SQLITE_CONFIG_SERIALIZED configuration option.

SQLITE_CONFIG_MALLOC

This option takes a single argument which is a pointer to an instance of the sqlite3_mem_methods structure. The argument specifies alternative low-level memory allocation routines to be used in place of the memory allocation routines built into SQLite. SQLite makes its own private copy of the content of the sqlite3_mem_methods structure before the sqlite3_config() call returns.

SQLITE_CONFIG_GETMALLOC

This option takes a single argument which is a pointer to an instance of the sqlite3_mem_methods structure. The sqlite3_mem_methods structure is filled with the currently defined memory allocation routines. This option can be used to overload the default memory allocation routines with a wrapper that simulations memory allocation failure or tracks memory usage, for example.

SQLITE_CONFIG_MEMSTATUS

This option takes single argument of type int, interpreted as a boolean, which enables or disables the collection of memory allocation statistics. When memory allocation statistics are disabled, the following SQLite interfaces become non-operational:

• sqlite3_memory_used()
• sqlite3_memory_highwater()
• sqlite3_soft_heap_limit()
• sqlite3_status()

Memory allocation statistics are enabled by default unless SQLite is compiled with SQLITE_DEFAULT_MEMSTATUS=0 in which case memory allocation statistics are disabled by default.

SQLITE_CONFIG_SCRATCH

This option specifies a static memory buffer that SQLite can use for scratch memory. There are three arguments: A pointer an 8-byte aligned memory buffer from which the scrach allocations will be drawn, the size of each scratch allocation (sz), and the maximum number of scratch allocations (N). The sz argument must be a multiple of 16. The sz parameter should be a few bytes larger than the actual scratch space required due to internal overhead. The first argument must be a pointer to an 8-byte aligned buffer of at least sz*N bytes of memory. SQLite will use no more than one scratch buffer per thread. So N should be set to the expected maximum number of threads. SQLite will never require a scratch buffer that is more than 6 times the database page size. If SQLite needs needs additional scratch memory beyond what is provided by this configuration option, then sqlite3_malloc() will be used to obtain the memory needed.

SQLITE_CONFIG_PAGECACHE

This option specifies a static memory buffer that SQLite can use for the database page cache with the default page cache implemenation. This configuration should not be used if an application-define page cache implementation is loaded using the SQLITE_CONFIG_PCACHE option. There are three arguments to this option: A pointer to 8-byte aligned memory, the size of each page buffer (sz), and the number of pages (N). The sz argument should be the size of the largest database page (a power of two between 512 and 32768) plus a little extra for each page header. The page header size is 20 to 40 bytes depending on the host architecture. It is harmless, apart from the wasted memory, to make sz a little too large. The first argument should point to an allocation of at least sz*N bytes of memory. SQLite will use the memory provided by the first argument to satisfy its memory needs for the first N pages that it adds to cache. If additional page cache memory is needed beyond what is provided by this option, then SQLite goes to sqlite3_malloc() for the additional storage space. The implementation might use one or more of the N buffers to hold memory accounting information. The pointer in the first argument must be aligned to an 8-byte boundary or subsequent behavior of SQLite will be undefined.

SQLITE_CONFIG_HEAP

This option specifies a static memory buffer that SQLite will use for all of its dynamic memory allocation needs beyond those provided for by SQLITE_CONFIG_SCRATCH and SQLITE_CONFIG_PAGECACHE. There are three arguments: An 8-byte aligned pointer to the memory, the number of bytes in the memory buffer, and the minimum allocation size. If the first pointer (the memory pointer) is NULL, then SQLite reverts to using its default memory allocator (the system malloc() implementation), undoing any prior invocation of SQLITE_CONFIG_MALLOC. If the memory pointer is not NULL and either SQLITE_ENABLE_MEMSYS3 or SQLITE_ENABLE_MEMSYS5 are defined, then the alternative memory allocator is engaged to handle all of SQLites memory allocation needs. The first pointer (the memory pointer) must be aligned to an 8-byte boundary or subsequent behavior of SQLite will be undefined.

SQLITE_CONFIG_MUTEX

This option takes a single argument which is a pointer to an instance of the sqlite3_mutex_methods structure. The argument specifies alternative low-level mutex routines to be used in place the mutex routines built into SQLite. SQLite makes a copy of the content of the sqlite3_mutex_methods structure before the call to sqlite3_config() returns. If SQLite is compiled with the SQLITE_THREADSAFE=0 compile-time option then the entire mutexing subsystem is omitted from the build and hence calls to sqlite3_config() with the SQLITE_CONFIG_MUTEX configuration option will return SQLITE_ERROR.

SQLITE_CONFIG_GETMUTEX

This option takes a single argument which is a pointer to an instance of the sqlite3_mutex_methods structure. The sqlite3_mutex_methods structure is filled with the currently defined mutex routines. This option can be used to overload the default mutex allocation routines with a wrapper used to track mutex usage for performance profiling or testing, for example. If SQLite is compiled with the SQLITE_THREADSAFE=0 compile-time option then the entire mutexing subsystem is omitted from the build and hence calls to sqlite3_config() with the SQLITE_CONFIG_GETMUTEX configuration option will return SQLITE_ERROR.

SQLITE_CONFIG_LOOKASIDE

This option takes two arguments that determine the default memory allocation for the lookaside memory allocator on each database connection. The first argument is the size of each lookaside buffer slot and the second is the number of slots allocated to each database connection. This option sets the default lookaside size. The SQLITE_DBCONFIG_LOOKASIDE verb to sqlite3_db_config() can be used to change the lookaside configuration on individual connections.

SQLITE_CONFIG_PCACHE

This option takes a single argument which is a pointer to an sqlite3_pcache_methods object. This object specifies the interface to a custom page cache implementation. SQLite makes a copy of the object and uses it for page cache memory allocations.

SQLITE_CONFIG_GETPCACHE

This option takes a single argument which is a pointer to an sqlite3_pcache_methods object. SQLite copies of the current page cache implementation into that object.

SQLITE_CONFIG_LOG

The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a function with a call signature of void(*)(void*,int,const char*), and a pointer to void. If the function pointer is not NULL, it is invoked by sqlite3_log() to process each logging event. If the function pointer is NULL, the sqlite3_log() interface becomes a no-op. The void pointer that is the second argument to SQLITE_CONFIG_LOG is passed through as the first parameter to the application-defined logger function whenever that function is invoked. The second parameter to the logger function is a copy of the first parameter to the corresponding sqlite3_log() call and is intended to be a result code or an extended result code. The third parameter passed to the logger is log message after formatting via sqlite3_snprintf(). The SQLite logging interface is not reentrant; the logger function supplied by the application must not invoke any SQLite interface. In a multi-threaded application, the application-defined logger function must be threadsafe.

See also lists of Objects, Constants, and Functions.

*** DRAFT ***